skins/how-to-use.md

---

gitea: none
include_toc: true

---

# How to Use This Repository

If anything is unclear, just shoot me a message on Discord.

## 1. Create Your Account on git.sulejmani.xyz

(If you don't want to share your mail with me DM me on Discord)

Sign up here:
[https://git.sulejmani.xyz/user/sign\_up](https://git.sulejmani.xyz/user/sign_up)

![Register](/docs/register.png)

Check your email and click the confirmation link to activate your account.

![Check Mail](/docs/check_mail.png)
![Activation Email](/docs/activation_mail.png)

Then confirm your password to complete the process.

![Activate Account](/docs/activate_account.png)

---

## 2. Generate an Access Token

Go to [https://git.sulejmani.xyz/](https://git.sulejmani.xyz/) and open your **Settings**.

![Navigate Settings](/docs/navigate_settings.png)

Under the **Applications** section, create a new token.

* Check all permissions (as shown in the image)
* Give it a clear and recognizable name

![Generate Token](/docs/applications_generate_token.png)

Once the token is generated, **copy and save it securely**, you won’t be able to see it again.

![Copy Token](/docs/copy_token.png)

---

## 3. Create a New Repository

Still on [https://git.sulejmani.xyz/](https://git.sulejmani.xyz/), click the **+** icon in the top right corner to create a new repo.

![Start Creating New Repo](/docs/start_create_new_repo.png)

* Name it however you like
* Use `skins-template` as the template
* Enable all template items

You now have your own copy of the template repo.

![Template Repo](/docs/template_repo.png)

---

## 4. Set Up Secrets for Deployment

Go to your repository's **Settings**.

![Navigate Repo Settings](/docs/navigate_repository_settings.png)

Then under **Actions** open the **Secrets** tab and add this:

| Secret Name | Secret Value               |
| ----------- | -------------------------- |
| `TOKEN`     | The token you just created |

![Add Secret](/docs/secret.png)

Then under **Actions** open the **Variables** tab and add these two:

| Variable Name        | Variable Value      |
| -------------------- | ------------------- |
| `CONTAINER_REGISTRY` | `git.sulejmani.xyz` |
| `OSUID`              | Your osu player id  |

So in my case my osu profile is https://osu.ppy.sh/users/13792719 and I use 13792719

![Example Variables](/docs/example_variables.png)

---

## 5. Clone the Repository

If you don’t have Git installed, download it here:
👉 [https://git-scm.com/downloads/win](https://git-scm.com/downloads/win)

Choose where to clone the repo (e.g. `D:/git/`) and run:

```bash
git config --global user.name "Your Name"
git config --global user.email "{yourusername}@sulejmani.xyz" # or your real mail if you dont mind anyone looking 

git lfs install

git clone https://git.sulejmani.xyz/{yourusername}/{yourrepositoryname}.git
```

---

## 6. Prepare Your Skins

In your cloned repo, open `hardlink-songs-folder.bat`.

Edit the source and target paths. For example, if:

* Your osu! skins are in `E:\osu!\skins`
* Your repo is in `D:\git\skins`

Then update the line on the script like this:

```bat
robocopy "E:\osu!\skins" "D:\git\skins\Skins" /MIR /COPYALL /SEC /B /XJ /DCOPY:T /J
```

**For the git Path the Skins folder needs to have a capital S**

Run the batch file by double-clicking it.

---

## 7. Change Skin Order, add descriptions, and ignore Skins.

### Skin Order
This is optional, but recommended. In the `workflows` folder, open `skins.json`.

Edit the order and descriptions as you like.

here's an example:

```json
{
  "order": [
    "- Barely still Jace",
    "- Jace"
  ],
  "descriptions": {
    "- Barely still Jace": "My main skin.",
    "- Jace": "My secondary skin, only really used for EZ."
  }
}
```

Make sure the order matches the skins folder name in the `Skins` folder.

### Ignore Skins

There is a .gitignore file in the root of the repo. You can add any skins you don't want to be uploaded.

Here's an example:

```
*WhiteCat*
*Vaxei*
```
So in this example if a Skin has WhiteCat  or Vaxei in the name, it will be ignored.

---

## 8. Upload Your Skins

Open a terminal (cmd or PowerShell) in your repo directory:

```cmd
cd D:\git\skins  # update this to your actual path
```

Then run:

```bash
git add .
git commit -m "Adding skins"
git config --global credential.helper cache
git push
```

Your skins will now be uploaded.

---

## 9. Monitor Upload Progress

Go to your repo's **Actions** tab.

![navigate-actions](/docs/navigate_actions.png)

You’ll see the workflow progress there.

![progress](/docs/progress.png)

If something goes wrong, check the logs—or just ping me on Discord.

---

## 10. Update Skins in the Future

To update your skins later:

1. Re-run `hardlink-songs-folder.bat`
2. Run the same upload commands:

```bash
git pull
git add .
git commit -m "Updating skins"
git push
```

---

11. Handle duplicate skin.ini names

After you pushed your skins you should be able to see a job starting in the "Actions"

![Actions Tab](/docs/actions-tab.png)

If you open the most recent job and click on `Check for Duplicate skin.ini Names` you should be able to see some logs.

![Skin.ini Logs](/docs/skinini-logs.png)

If there are duplicate entries I recommend you fix those locally and run step 10. again, after the job went through for the first time.

---

### 12. Adding your skin to https://git.sulejmani.xyz/osc/skins

After you did every step it should be in https://git.sulejmani.xyz/osc/skins after a couple minutes, if it doesn't show up please message me on Discord.

---

## 13. Troubleshooting

### Add Skin order, add skin descriptions

Edit `.gitea/workflows/skins.json` like described in step 6.

### Committed all the files but nothing is happening

Make sure the skins folder is called `Skins` and not `skins`.

### Skin names wrong

The Scirpt takes skin names based off of the `skin.ini` file in the skin, to fix that change it in the `skin.ini` file.