DEV Community


Posted on • Updated on

Git Branch Naming Convention

Working on a big company with projects that could scale from a one-man team then suddenly to a 20 developers team, having a manageable code repository is a need. Most Proof of Concept projects start with a repository with all changes being applied directly to the master branch. Elevating one into a proper big scale repository is a common path being taken by new developers when their small-scale project is suddenly noticed.

On my end, having to work on dozens of different projects like these, I came up with this branch naming convention.

I separated these branches into two categories:

Code Flow Branches

These branches which we expect to be permanently available on the repository follow the flow of code changes starting from development until the production.

  • Development (dev)

    All new features and bug fixes should be brought to the development branch. Resolving developer codes conflicts should be done as early as here.

  • QA/Test (test)

    Contains all codes ready for QA testing.

  • Staging (staging , Optional)

    It contains tested features that the stakeholders wanted to be available either for a demo or a proposal before elevating into the production. Decisions are made here if a feature should be finally brought to the production code.

  • Master (master)

    The production branch, if the repository is published, this is the default branch being presented.

Except for Hotfixes, we want our codes to follow a one-way merge starting from development > test > staging > production.

Temporary Branches

As the name implies, these are disposable branches that can be created and deleted by need of the developer or deployer.

  • Feature

    Any code changes for a new module or use case should be done on a feature branch. This branch is created based on the current development branch. When all changes are Done, a Pull Request/Merge Request is needed to put all of these to the development branch.


    • feature/integrate-swagger
    • feature/JIRA-1234
    • feature/JIRA-1234_support-dark-theme

It is recommended to use all lower caps letters and hyphen (-) to separate words unless it is a specific item name or ID. Underscore (_) could be used to separate the ID and description.

  • Bug Fix

    If the code changes made from the feature branch were rejected after a release, sprint or demo, any necessary fixes after that should be done on the bugfix branch.


    • bugfix/more-gray-shades
    • bugfix/JIRA-1444_gray-on-blur-fix
  • Hot Fix

    If there is a need to fix a blocker, do a temporary patch, apply a critical framework or configuration change that should be handled immediately, it should be created as a Hotfix. It does not follow the scheduled integration of code and could be merged directly to the production branch, then on the development branch later.


    • hotfix/disable-endpoint-zero-day-exploit
    • hotfix/increase-scaling-threshold
  • Experimental

    Any new feature or idea that is not part of a release or a sprint. A branch for playing around.


    • experimental/dark-theme-support
  • Build

    A branch specifically for creating specific build artifacts or for doing code coverage runs.


    • build/jacoco-metric
  • Release

    A branch for tagging a specific release version


    • release/myapp-1.01.123

    Git also supports tagging a specific commit history of the repository. A release branch is used if there is a need to make the code available for checkout or use.

  • Merging

    A temporary branch for resolving merge conflicts, usually between the latest development and a feature or Hotfix branch. This can also be used if two branches of a feature being worked on by multiple developers need to be merged, verified and finalized.


    • merge/dev_lombok-refactoring
    • merge/combined-device-support

Any organization can come up with their own convention. This applies to my current Team's need and there could be a better approach which could improve upon these. What are your conventions on your own organization?

Top comments (15)

shvahabi profile image
Shahed • Edited

Very thorough summary of all usual conventions. Just want to add after the Black Lives Matter movement, git provided option to use names other than master, the option is: git init --initial-branch=stable. Hence technically speaking master is deprecated in favour of other names such as stable or main.

jstewart8053 profile image
jstewart8053 • Edited

You mean after the Black Lives Matter movement. It's not a 'thing'. smh
Very helpful post though, what do you think about emojis in commits? I have seen a lot on the issue lately.

shvahabi profile image
Shahed • Edited

Sure you are right, since English is not my native language πŸ˜…. The correct word is movement, and thanks. I edited my original reply.

Thread Thread
jstewart8053 profile image

No worries :)

Thread Thread
gitbusycoding profile image
Ravi Ponamgi

Liked "No worries", considering the OP was made with the best of intentions.

slidenerd profile image
slidenerd • Edited

What do you call a branch where you start a python project empty, add a gitignore, readme, poetry, tox, pre-commit, add a setup pyproject.toml install pytest and run some tests inside the tests directory which you also create

evilkittenlord profile image

Everything needs a naming scheme. :)
Folks might be interested in the naming scheme I've been using that enables automatic semver detection.

prox_sea profile image
Eduardo Zepeda

This is so useful, most people should read this post.

clifton893 profile image
Clifton Long Jr.

Great post, and very helpful! πŸ˜„

robertotonino profile image
Roberto Tonino

Great post, thanks! Definitely gonna use this convention :)

I would suggest a branch for dependencies upgrading too (expecially ones with breaking changes), what do you think?

couchcamote profile image
couchcamote • Edited

Glad to have helped.
For new dependencies upgrading we can consider that as a new feature. Basically, it is like new code changes with new libraries and code updated to use them. It should also follow the dev-test-stage-prod flow and it usually has planned schedule for release.

ponyjackal profile image

Thanks for your post,

gitbusycoding profile image
Ravi Ponamgi

Great summary!

ahmadf20 profile image
ahmad faaiz

Great! Thanks~

djaegerscript profile image
Adjie Djaka Permana

Much new knowledge, thanks for sharing it