Git Course 0%

Branch types and naming

Intermediate Core Git ≈ 8 min

Before this lesson

What you will learn

  • The purpose and lifetime of each kind of branch a team uses
  • The naming pattern type/issue-short-title and why the issue number matters
  • Where each kind starts from and where it merges back

After this lesson you can

  • I can name a branch for any issue the team's way and know where to start it from

Why this matters

Branch names are the first thing colleagues see in the branch list and in merge requests. A good name says what the branch is for and links to the issue; a bad name (test, ana-branch, new) forces everyone to open it to find out. Branch kinds matter too: a hotfix starts from the release, not from main, and a release branch lives for weeks while a docs branch lives for a day.

The kinds

Kind Purpose Starts from Merges into Lives Example
main (older: master) The current, working version; always releasable – – forever main
develop (some teams) Integration branch where features collect before a release main main at release time forever develop
feature New behaviour users notice main (or develop) main (or develop) via merge request days to weeks feature/21-difficulty-filter
fix A bug fix on the normal schedule main main hours to days fix/15-empty-distance
docs Documentation only main main hours to days docs/12-windows-install-steps
chore Housekeeping: dependencies, tooling, cleanup main main hours to days chore/44-ignore-pytest-cache
hotfix Urgent fix for production the release tag or release branch the release and main hours hotfix/23-region-name
release (some teams) Stabilizing a version: only fixes allowed main or develop at feature freeze main, then tagged days to weeks release/1.3

Whether your team has develop and release branches depends on its strategy (lesson 13.3); the short-lived kinds exist everywhere. master is the historical default name; new repositories and this course use main.

Naming

The pattern in the playground's CONTRIBUTING, which most teams use with small variations:

Text
type/issue-short-title
docs/12-windows-install-steps
fix/15-empty-distance
feature/21-difficulty-filter
hotfix/23-region-name
  • type from the table above.
  • issue number: GitLab and GitHub link the branch to the issue, and the merge request created from it inherits the link. Some teams put the number first (12-docs-windows); follow yours.
  • short title: lowercase, hyphens, three to five words that say what, not how. No spaces, no capitals, no special characters other than /, -, ., _.

GitLab can create the branch for you from an issue: on the issue page, Create merge request → Create branch produces 12-installation-guide-is-missing-the-windows-steps, named from the title. Perfectly acceptable; many teams simply use that.

Where to start from

The branch starts from the commit HEAD is on when you run git switch -c. Rules that prevent a lot of trouble:

  • Feature, fix, docs, chore: from an up-to-date main (git switch main && git pull first).
  • Hotfix: from the released version, usually a tag: git switch -c hotfix/23-region-name v1.2.0, so the fix contains nothing unreleased. It is then merged into the release line and into main.
  • Never from another feature branch, unless the two are meant to ship together; otherwise your branch drags the other's unfinished work along.
Terminal
$ git switch -c hotfix/23-region-name v1.2.0
Switched to a new branch 'hotfix/23-region-name'

Lifetime

Short-lived branches are the whole idea: create, do one thing, merge, delete. A branch older than two weeks is a warning sign: it will conflict with everything that happened on main meanwhile. If work takes longer, merge partial steps behind the scenes (a documentation page with a "draft" note, a feature behind a setting), or at least update the branch from main regularly (lesson 6.4).

Common mistakes

  • Branching from a stale main. Pull first; otherwise you start behind and merge into a moved target.
  • One branch for many issues. Review takes weeks and conflicts pile up. One issue, one branch.
  • Reusing a merged branch for new work. Delete it and create a fresh one; the name should match the new issue.
  • Personal names as branch names. ana-work says nothing and cannot be linked to an issue.

Try it yourself

Goal: name and create branches for three work items by the team's rules.

  1. Read the "Branches" rules in the playground's CONTRIBUTING.md.
  2. Create, from an up-to-date main, a branch for issue #33 "FAQ: add a question about Windows" and one for issue #15 "Trail list crashes when distance is empty".
  3. Create a hotfix branch for issue #23 starting from the tag v1.2.0 if your playground has one (git tag v1.2.0 on any commit first, if not).
  4. List them with git branch, then delete the three with git branch -d.

Expected result: docs/33-faq-windows-question, fix/15-empty-distance and hotfix/23-region-name appear in the list; all delete cleanly because they have no commits of their own.

Show solution

Terminal
$ git switch main && git pull
$ git switch -c docs/33-faq-windows-question
$ git switch -c fix/15-empty-distance main
$ git switch -c hotfix/23-region-name v1.2.0
$ git branch
$ git switch main
$ git branch -d docs/33-faq-windows-question fix/15-empty-distance hotfix/23-region-name
The second form, git switch -c <name> <start>, creates the branch from a named starting point without switching there first.

Check yourself

1. Which branch name follows the convention?
2. Where should a hotfix branch start from?
3. A feature branch has existed for six weeks. What is the main risk?

Key terms

main Branch Hotfix Feature Issue (ticket)

Related