# Git on PatchHub

Every PatchHub project is a git repository over HTTPS.

## Clone

```sh
git clone https://patchhub.sh/<owner>/<project>.git
```

Public projects clone without a password.

Private projects need your username and an access token (from https://patchhub.sh/settings) as the password.

## Branches

| Branch | Meaning |
|---|---|
| `main` | The main version. |
| `patches/<id>` | Each published patch, applied on the version it was made for. |

PatchHub's internal refs are hidden.

## Push

When git asks, use your PatchHub username, and an access token as the password.

### Push `main` (maintainer)

```sh
git push patchhub HEAD:main
```

This updates the main version. PatchHub re-applies everyone's patches on top of it automatically.

### Push any other branch: a draft patch

```sh
git push patchhub HEAD:dark-mode
```

PatchHub turns the branch into your draft patch and prints its link.

Push the same branch again to update that draft.

Then publish it on the website, or with `publish_patch` / `POST /api/v1/patches/{id}/publish`.

The branch must start from `main`'s history (clone first, then commit).

### Push a tag: a version (maintainer)

```sh
git tag v1.0 && git push patchhub v1.0
```

An annotated tag's message becomes the version notes.

## Refused pushes

| Message | Why | What to do |
|---|---|---|
| only the maintainer can push to main | You don't maintain this project | Push a branch instead; it becomes your patch. |
| main can't be deleted | Deleting main is blocked | |
| patches/* branches are managed by PatchHub | Those mirror published patches | Use another branch name. |
| only the maintainer can push tags | Tags are versions | Ask the maintainer. |
| this branch doesn't share history with main | Your branch started elsewhere | Clone the project, then commit on top. |
| Authentication failed | Wrong username or token | Create a new token at https://patchhub.sh/settings. |