A Simplified Convention for Naming Branches and Commits in Git

There are many excellent naming conventions regarding git branches and commits.

But what if you want something very lean and simple?

Here is a proposition.

Branch Naming Convention

The Git Branching Naming Convention article is an excellent base.
However, you can simplify even more.

Category

A git branch should start with a category. Pick one of these: feature, bugfix, hotfix, or test.

• feature is for adding, refactoring or removing a feature
• bugfix is for fixing a bug
• hotfix is for changing code with a temporary solution and/or without following the usual process (usually because of an emergency)
• test is for experimenting outside of an issue/ticket

Reference

After the category, there should be a "/" followed by the reference of the issue/ticket you are working on. If there's no reference, just add no-ref.

Description

After the reference, there should be another "/" followed by a description which sums up the purpose of this specific branch. This description should be short and "kebab-cased".

By default, you can use the title of the issue/ticket you are working on. Just replace any special character by "-".

To sum up, follow this pattern when branching:

git branch <category/reference/description-in-kebab-case>

Examples:

• You need to add, refactor or remove a feature: git branch feature/issue-42/create-new-button-component
• You need to fix a bug: git branch bugfix/issue-342/button-overlap-form-on-mobile
• You need to fix a bug really fast (possibly with a temporary solution): git branch hotfix/no-ref/registration-form-not-working
• You need to experiment outside of an issue/ticket: git branch test/no-ref/refactor-components-with-atomic-design

Commit Naming Convention

For commits, you can combine and simplify the Angular Commit Message Guideline and the Conventional Commits guideline.

Category

A commit message should start with a category of change. You can pretty much use the following 4 categories for everything: feat, fix, refactor, and chore.

• feat is for adding a new feature
• fix is for fixing a bug
• refactor is for changing code for peformance or convenience purpose (e.g. readibility)
• chore is for everything else (writing documentation, formatting, adding tests, cleaning useless code etc.)

After the category, there should be a ":" announcing the commit description.

Statement(s)

After the colon, the commit description should consist in short statements describing the changes.

Each statement should start with a verb conjugated in an imperative way. Statements should be seperated from themselves with a ";".

To sum up, follow this pattern when committing:

git commit -m '<category: do something; do some other things>'

Examples:

• git commit -m 'feat: add new button component; add new button components to templates'
• git commit -m 'fix: add the stop directive to button component to prevent propagation'
• git commit -m 'refactor: rewrite button component in TypeScript'
• git commit -m 'chore: write button documentation'

References

sources

• article: Git Branching Name Convention
• article: Conventional Commits 1.0.0
• article: Commit Message Guideline
• article: A Successful Git Branching Model

Comments

[0xKali]

Awesome! Writing good commit messages and branch naming has always been tricky for me. From now on, I'll just use this convention.

[Juanmabs22]

Why "feat" for commits and "feature" for branch name's?

[Piotr Kożuchowski]

Is there any merit to differentiating branches by hotfix/, bugfix/, feature/, refactor/ etc?
We have this kind of distinction in JIRA (or any other issue tracking system), so why should we copy that into repository as well?

The release will consist of tickets that got signed off by business, so I'm thinking from repository perspective I only need to know which branch is related to signed off tickets. So maybe just dev/JIRA-XXX is plenty?

[federico]

I've been differentiating branches as mentioned by the OP as this allows me to quickly tell what the branch is about, rather than having to open up JIRA to find the title/description associated with the ticket ID.

The downside is the branch names can get pretty lengthy but I don't mind.

[Almog Shtaigmann]

That's a great explanation! Thanks!

[Ferdous Islam]

why not add the issue/ticket number in the commit messages as well? So that even after the branch is merged each commits can be traced to that issue/task.

[Old Starchy]

I've heard its bad practice to use the default merge commit message (though I haven't looked into why), but if you do it will be there. Assuming you're creating merge commits that is.

I don't really like the idea of repeating information in every commit unless I can automate it (reliably).

[Frank Ilunga]

Thanks

[Carlos]

Great article. Thanks.

[Dhruv Pankaj Patel]

okay that's pretty helpful, thanks 👍

[Aman Kumar]

Amazing article, I get a clear understanding of how to write the commit message or create the branch and its naming convention.

[David Asiamah]

This is a good post. Thanks.