33.8 Git Branch Naming

20231228

For team-based projects a naming scheme of username/issue_a_brief_description is recommended. For example a branch created by github user kt working on issue #34 described as support csv import might be:

kt/34_support_csv_import

For a team-based project with regular tasks assigned to individuals the preferred naming scheme begins with the team member’s git username or their initials. This makes it clear who created and is responsible for a particular branch, but should not be seen as discouraging others from contributing to that branch through pull requests.

The slash separates the username. The use of the slash can be problematic when URIs are added to the branch, resulting in the slash becoming ambiguous, though it also blends in nicely with the URI scheme. The use of slash is common and supported by some git tools.

The issue number associated with the branch follows the slash. The issue number is a readily usable key to identify the activity. This significantly assists in searching and tracking specific activity and quickly linking the branch back to an issue. We are also assuming that each branch is typically associated with an issue.

Finally a brief description confirms the activity. It should be kept short but descriptive with underscore (_) separating words rather than hyphen (-). Either can be chosen as a standard but the underscore is often interpreted as a space and so works well for the branch name. The hyphen can get confused with command line arguments.

A widely used alternative convention for naming branches is to begin with a token, then a slash, then a descriptive name, like feat/search_bar.

Common tokens include feat (feature), wip (work in progess), bug, new, test, dev, doc.

---

Your donation will support ongoing availability and give you access to the PDF version of this book. Desktop Survival Guides include Data Science, GNU/Linux, and MLHub. Books available on Amazon include Data Mining with Rattle and Essentials of Data Science. Popular open source software includes rattle, wajig, and mlhub. Hosted by Togaware, a pioneer of free and open source software since 1984. Copyright © 1995-2022 Graham.Williams@togaware.com Creative Commons Attribution-ShareAlike 4.0