DEV Community

Amaresh Pelleti
Amaresh Pelleti

Posted on Originally published at devtoolhub.com

Git Branch Naming Conventions: Patterns and a CI Check

Originally published on DevToolHub.

The git branch naming conventions I would use are a lowercase type/short-description pattern, such as fix/empty-password-crash, with an optional ticket number. Git enforces only a short list of hard rules, so the useful part is checking the rest automatically.

I tested on Git 2.56.0 and gh 2.103.3, including a CI check that passed and failed on real pull requests.

What Git refuses

From git check-ref-format, confirmed with git check-ref-format --branch: spaces, .., ~ ^ :, ? * [, backslashes, a leading dash, a .lock ending, bad slashes, and @{. Uppercase is allowed, and so are $, ;, &, | and backticks.

Why feature and feature/login clash

Each branch is a file under .git/refs/heads/, so a branch cannot be both a file and a directory:

git branch feature
git branch feature/login
# fatal: cannot lock ref 'refs/heads/feature/login': 'refs/heads/feature' exists
Enter fullscreen mode Exit fullscreen mode

It fails in the other order too. A prefix scheme, where every name is type/name, avoids it.

Case

On my APFS Mac, creating Foo and then foo failed with a branch named 'foo' already exists. Use lowercase.

The pattern

type/short-description
type/123-short-description
Enter fullscreen mode Exit fullscreen mode

type is feat, fix, docs or chore. gh issue develop 4 -n fix/4-empty-password-crash creates a branch linked to issue #4 with that name; the default name is 4-login-page-crashes-on-empty-password.

A CI check

name: branch-name
on:
  pull_request:
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Check branch name
        env:
          BRANCH: ${{ github.head_ref }}
        run: |
          if ! echo "$BRANCH" | grep -Eq '^(feat|fix|docs|chore)/[a-z0-9]+(-[a-z0-9]+)*$'; then
            echo "Branch '$BRANCH' must look like feat/short-name, fix/..., docs/... or chore/..."
            exit 1
          fi
          echo "Branch name OK: $BRANCH"
Enter fullscreen mode Exit fullscreen mode

The PR from chore/add-branch-check passed and the one from Fix_Login-Bug failed. The name goes through env: because Git allows $ and ; in names, so inlining it in the script could run shell commands.

What I did not test

One Mac, one repo. Not tested: Linux or Windows, rulesets for branch names, required status checks, renaming a pushed branch, Jira or Linear linking.

Full write-up with the complete rules table and FAQ: Git Branch Naming Conventions.

Top comments (0)