DEV Community

Kai Thorne
Kai Thorne

Posted on

Git Branch Naming That Won't Make Your Team Hate You

#git #python #devops #productivity

Every team I've worked with has that one person whose branch names look like a cat walked across the keyboard:

git branch
  feature/Fix-login-page
  fix-login-123
  stuff
  WIP
  main
  my-changes-3-final-REALLY-final
Enter fullscreen mode Exit fullscreen mode

Code review becomes archaeology. CI pipelines show WIP (which one?). git branch --merged is useless.

I've been that person. And I've cleaned up after that person. This is the tool I wish I'd had years ago.

The Convention: type/description

One rule: type/description. That's it.

feature/add-login          # ✅
fix/null-pointer           # ✅
docs/readme-spelling       # ✅
chore/update-deps          # ✅
refactor/auth-middleware   # ✅
Enter fullscreen mode Exit fullscreen mode

Allowed types: feature, feat, fix, bugfix, hotfix, chore, refactor, docs, style, test, perf, ci, build, release, deps.

Every branch name follows the same pattern. Every teammate reads it the same way. Every CI pipeline understands it.

Meet git-ninja 🥷

git-ninja is a single-file Python script with zero dependencies. Drop it in your repo and it enforces the convention (free version available on the product page):

# Download git-ninja (free, no deps)
curl -O https://kaithorne.gumroad.com/l/git-ninja-pro
# Or copy the script directly from the product page

# Make it executable
chmod +x git-ninja

# Check your current branch
./git-ninja check

# Check all branches
./git-ninja list

# Install as a pre-commit hook
./git-ninja init
Enter fullscreen mode Exit fullscreen mode

Here's what check looks like on a bad branch:

$ git checkout -b my-crappy-name
$ git-ninja check

🔍 Checking branch: my-crappy-name

❌ Found 1 issue(s):
   1. Does not match pattern — expected 'type/description' (e.g., 'feature/add-login')

💡 Suggested: feature/my-crappy-name
   Rename: 'git branch -m <newname>'
Enter fullscreen mode Exit fullscreen mode

And on a clean branch:

$ git checkout -b feature/add-rate-limiting
$ git-ninja check

🔍 Checking branch: feature/add-rate-limiting

✅ Branch name follows convention.
Enter fullscreen mode Exit fullscreen mode

Pre-commit Hook — Set It and Forget It

Run git-ninja init once and it installs a pre-commit hook. Every git commit on a non-compliant branch gets blocked with a clear message.

$ git checkout -b fix-login
$ touch test.txt && git add test.txt
$ git commit -m "wip"

❌ Branch name does not follow convention: type/description
   Rename: git branch -m fix/login
Enter fullscreen mode Exit fullscreen mode

The hook is a simple shell script — no npm, no Python packages, no node_modules. It works on every system that has git and python3.

Configuration

Create .git-ninja.json in your repo root:

{
  "types": ["feature", "fix", "chore", "docs", "refactor", "test", "ci"],
  "max_length": 50
}
Enter fullscreen mode Exit fullscreen mode

No config file? No problem. It uses sensible defaults.

Why Not Husky / Lefthook / etc?

You should use those too! git-ninja solves exactly one problem (branch naming) and solves it well. It's:

  • Zero dependencies — no npm install, no package.json, no node_modules
  • Single file — drop git-ninja in your repo and it works
  • Portable — works on every OS with Python 3.6+
  • Fast — runs in ~50ms, no startup overhead

Pro Version

For teams that want enforcement across the whole org, there's a Pro version ($2.99) that adds:

  • Team config sharing — one JSON config, distributed via URL
  • GitHub Action — plug-and-play CI check for PRs
  • Auto-fix — one command to rename non-compliant branches
  • HTML audit reports — color-coded branch health for your dashboards
  • Slack/webhook alerts — notify the team on violations

The free version (MIT, open source) handles individual and small-team use. The Pro version is for orgs that need consistency across dozens of repos and contributors.

Install It Now 

# Quick install — grab the free script
curl -L -o git-ninja https://kaithorne.gumroad.com/l/git-ninja-pro
chmod +x git-ninja
./git-ninja init

# Or get the Pro version with team features
# → https://kaithorne.gumroad.com/l/git-ninja-pro
Enter fullscreen mode Exit fullscreen mode

Then rename any branches that don't follow the convention:

git branch -m feature/$(git rev-parse --abbrev-ref HEAD | sed 's/^/feature\//')
Enter fullscreen mode Exit fullscreen mode

Your future self — and every dev who reads your repo — will thank you.

What branch naming convention does your team use? I've seen feature/, fix/, chore/, and some wild ones like JIRA-1234/short-desc. Drop yours in the comments — always looking for better patterns.

P.S. — I built git-ninja because I got tired of manual branch audits in code reviews. It's MIT licensed and the full source is available. If you need team-wide enforcement, the Pro version is $2.99 and pays for itself in the first PR review it saves.

Top comments (0)