git-branch

Files (1)

• SKILL.md

SKILL.md (first lines)

# Git Branch Naming Guidelines

## Naming Style

Use one convention in every repository, whatever its existing branches look like,
unless the repository's agent instruction files set another (see
[Existing Branches and Instructions](#existing-branches-and-instructions)):

- `<type>/issue-<N>-<slug>` for work on an issue (e.g., `feat/issue-123-add-login-page`)
- `<type>/<slug>` for anything else (e.g., `ci/pin-python-patch`)

`<type>` is the [Conventional Commits](https://www.conventionalcommits.org/) type the
change would carry (`feat:`, `fix:`, `docs:`, …), whether or not the repository's commit
messages use that format, plus two branch-only types, `hotfix/` and `release/`:

- `feat/`: New features (e.g., `feat/issue-123-add-login-page`)
- `fix/`: Bug fixes (e.g., `fix/issue-64-timestamp-fields`)
- `docs/`, `test/`, `refactor/`, `perf/`, `build/`, `ci/`, `chore/`: Changes of that
  type (e.g., `docs/issue-67-readme-concurrency`, `chore/update-dependencies`)
- `hotfix/`: Fixes shipped outside the normal release flow, such as a patch cut from a
  release tag (e.g., `hotfix/security-patch`); ordinary bug fixes use `fix/`
- `release/`: Release preparation, such as a version bump (e.g., `release/v1.2.0`)

`<slug>` is a few lowercase words from the issue title, or from the change's one-line
summary when there is no issue, joined by hyphens.

## Stacked Layers

Each layer of a stack is its own branch, named with the same convention:

- **Layers for different issues** each carry their own issue: `fix/issue-12-…` below
  `feat/issue-14-…`.
- **One issue split into several layers:** every layer carries that issue's number, its
  slug names the layer's part, and its type is that layer's own change type, e.g.,
  `refactor/issue-42-extract-parser` below `feat/issue-42-parse-lists`. The pull request
  of a lower layer refers to the issue; the layer that completes it closes it (the
  `github-workflow` skill, if installed, has the details).

## Label Table

An issue's change-type label sets the branch type. The same type starts the pull
request title (`<type>: <description>`).

| Change-type label | Branch type |
| ----------------- | ----------- |
| `bug`             | `fix`       |
| `build`           | `build`     |
| `chore`           | `chore`     |
| `ci`              | `ci`        |
| `documentation`   | `docs`      |
| `enhancement`     | `feat`      |
| `perf`            | `perf`      |
| `refactor`        | `refactor`  |
| `test`            | `test`      |

When the issue has no change-type label, or there is no issue, derive the type from the
change. When the pull request title disagrees with the label, the title wins: it states
what the change actually is, and the branch is deleted after the merge.

Other skills point here for this table. `hotfix/` and `release/` have no label.

## Existing Branches and Instructions

A repository's agent instruction files (AGENTS.md, CLAUDE.md) override this
convention: when they set another naming scheme, follow it. Existing branches do not:
when they follow another scheme that no instruction file sets, name new branches with
this convention anyway. Do not rename existing branches on your own; rename one only
when the user asks, and use the scheme that applies for the new name.

## Additional Rules

- Dots allowed only for version numbers in `release/` branches
- Do NOT use `git -C <path>` when the current directory is already the repository root

From jmfontaine/agent-skills, Apache-2.0.

More from jmfontaine/agent-skills