DEV Community

Cover image for How to organize your git branches
Darío Kondratiuk
Darío Kondratiuk

Posted on • Updated on • Originally published at

How to organize your git branches

I remember implementing git in my team. I think it was more than 6 years ago. At that time, A successful git branching model by Vincent Driessen was required reading if you wanted to learn how to work with git effectively. Since then, I've been following the "Git Flow" style. But, this past year, I've been influenced by many developers from the community, and started using git in different ways depending on the projects I was working on.

Before getting into the different branching styles, it's important to remember that, although many git clients treat slashes ("/") as a directory separator, there is no such thing as folders or directories in the git specification. You will see this implemented in many UI clients, but I never found it on console clients, or on websites like Github or GitLab.

That being said, Let's explore some ways of organizing branches, so you don't get lost in a sea of code.


Although Gitflow doesn't mention branch folders, many devs use "Feature branches", "Hotfix branches" and "Release branches" and create folders accordingly.
So basically, a GitFlow organization would have these three folders:

  • feature[s]
  • hotfix[es]/fixes
  • release[s]

As there is no public document talking about this, I've seen some working copies using those folders in plural and others in singular.

Gitflow with steroids

I found myself adding two more folders to my Gitflow repos:

  • Docs: For branches related to markdown or release documents.
  • Task: For branches which are neither features nor fixes. Such as, clean up scripts or refactors.

BPMP (Branch-Push-Merge-Prune)

I’ve seen this a lot in many projects. The branch-push-merge-prune is the anti-folder method. I'm not saying that chaos is a way of organizing branches. People using this method like to have their working copy clean. They would just branch, push, create a pull request and then delete the branch (manually or via git fetch prune) as soon as the PR is merged.


I found myself using what I call a "module-based" branching model on a big project where I got quite lost in a sea of features and fixes. So I started to create branches based on its modules.

You could mix Gitflow with this module-based approach, something like "backoffice/billing/fixes/billing-values", but that may be too much.


I first saw Meir using this approach and I loved it. It’s great for projects like Puppeteer-sharp where the roadmap is clear.
In a version-based repo you create each branch inside a "vX.X" folder. What is cool about this is that it’s time-based, so it's easier to find branches and also it's super easy to delete old versions with this simple git command:

git branch | grep -e "vX.X/" | xargs git branch -D

Again, this could be mixed with Gitflow folders, but...


If tickets numbers (tickets, issues or whatever you call them) are part of your team's language using a ticket-based system could be a perfect fit.
You could use a folder, such as "tickets/242" or "issues/242", or just simply call it "242".


If none of these systems is for you, you can follow Nick's idea and implement an Emoji-based system :)

Final words

Two final thoughts to close this post. First, if you work on a team where you normally checkout each other branches, e.g. for local testing, I'd recommend you share the style with your team.
And finally, clean your working copy frequently. This will help you find your branches quickly, and also speed up your local repo.

Don't stop coding!

Originally posted on

Top comments (28)

cseeman profile image

I do a lot of ticket based naming but also like to tack on a little blurb about the ticket name so I can look at the branch and know right away which ticket. So something like "T-123/add-new-button". Then when you are in your git bash, and run git branch you can figure out your branches a bit better. I do need to get better at remembering to delete stale local and remote branches.

jasonkarns profile image
Jason Karns • Edited

Oof, ticket-based prefixes virtually eliminates the benefit of tab completion! Do you memorize ticket numbers? git co 9<tab> is not going to give me anything useful, nor will 97<tab> or 974<tab>. With ticket based prefixes you have to type every digit of the ticket number, down to probably the one's place. Given that most companies are probably in the thousands or more of tickets, you're typing at least 4 characters before you can even hope to get a completion match. I get cranky if I have to type more than 2 characters to get a completion match.

cseeman profile image

I could see it getting a little tricky. I usually do a git branch so I can see my local branches, and it makes it a bit better for typing it out, especially with the little quick summary blurb that is also in the branch naming. I do love my tab completion too!

sublimegeek profile image
Jonathan Irvin

I do the same. Usually, in a professional setting, you're working with something like JIRA so it makes sense to prefix a branch with a ticket (as a way to say "this branch is related to this story") and then a short human-readable description of the feature.

As a general rule of thumb, if your brain has to pause and make sense of a branch name, it's too complex.

hardkoded profile image
Darío Kondratiuk

That's cool, I like it.

napicella profile image
Nicola Apicella • Edited

Nice post! Even though Michael Larson did not elaborate the answer enough, he has a point :)
Papers and other publications like DevOps show that the most effective way to organize code branches is trunk based development.
Team productivity, release time even test coverage have a beneficial impact when using this strategy.
You might want to check out the Continuos delivery book and the devops report.
In case what I m saying is not new to you, then a little mention in the article would make it even nicer and would give people the opportunity to dig into an alternative approach.
Thanks for sharing!

mrlarson2007 profile image
Michael Larson

I have done both, Trunk Based Development is the way to go for teams with high code velocity. Feature branches can be manageable for very small teams. But it's not scalable.

stealthmusic profile image
Jan Wedel

We’ve also used both for a team of 6 and Feature branches often end in merge conflicts especially at the end of a sprint. Although you can build it, it usually prevents you deploying and system testing your code on a production like environment. Quick feedback is important. So we commit on develop branch and only follow git flow for releases.

Thread Thread
guitarkat profile image

Yeah I do commits on dev branch as well. I always pull from dev to prevent conflicts, but you don't always win but it's not a last minute scramble to get the code on the feature if too close on the files working.

adymitruk_64 profile image
Adam Dymitruk

Right. Because the Linux kernel doesn't scale. TBD is based on pseudo science, usually coming from the agile dogma proponents. I'll show you peer reviewed papers on the benefits of smoking too.

Thread Thread
mrlarson2007 profile image
Michael Larson • Edited

I can't really speak to how Linux project works or how they organize their code. What I can tell you is that there has been research done that shows that TBD allows an organization to scale as their code velocity increases and the number of developers increases too. Great book that has results from a multi year study said this:

  1. Teams that developed off trunk/master had more frequent and stable releases and did not need a "code freeze" to stabilize things regardless of size
  2. As long as branches are short lived, and integrated daily with trunk/master it does not violate the spirit of TBD.
  3. longer lived branches are acceptable for open source since not everyone is working on it full time.

Forsgren PhD, Nicole. Accelerate: The Science of Lean Software and DevOps: Building and Scaling High Performing Technology Organizations (Kindle Locations 971-985). IT Revolution Press. Kindle Edition.

I can also attest to this from personal experience working on a large volunteer project with lots of developers, before starting TBD merging feature branches was stressful event and took hours to complete. We went from quarterly releases to weekly after we switched to TBD and other changes that where made to support that. We could not do that if we still had those long lived feature branches, and we no longer have to deal with the pain of merging large branches of code.

Thread Thread
mrlarson2007 profile image
Michael Larson

Adam, if you have any research that shows the opposite I would be certainly interested in reading it. At the end of the day its up to you to decide how you want to organize your projects. I know there is a time places for branches, but the trouble I have seen is the longer these branches live, the more pain they cause. There is a tipping point where any benefit to placing code in a feature branch is out weighed by pain it causes the team when they need to integrate that code back into the main line.

mrlarson2007 profile image
Michael Larson

Three words: trunk based development.

jessekphillips profile image
Jesse Phillips
  • Short lived branches
  • work to completion
keremispirli profile image

GitFlow by Driessen is indeed a must-read when you want to design your git branching strategy, but in past years two more articles are added to that:

I highly recommend reading all three before approaching the whiteboard.


jasonkarns profile image
Jason Karns • Edited

I think the number of screenshots of GUI tooling is telling with regards to the various prefix naming schemes. Primarily because branch name prefixes are hostile to CLI users due to the fact the prefixes hamper tab completion.

For each and every "directory" level in the prefix, you've added 2 extra characters minimum that are must be typed before even potentially getting a completion match. Given the sheer number of times that branch names are typed out, I find it astonishing why anyone would increase the friction in that area.

I optimize my branch names to actually facilitate my development workflow, which means making it more efficient to switch, merge, rebase or otherwise use the branch names. Branch names are the interface for how we work with git. They are not a metadata storage system.

I too used to think that adding all this metadata to my branch names was valuable. But after seeing how much friction it actually caused in my day to day (nay, minute to minute) workflow, I had to think more critically about the value such a scheme was actually providing. And unfortunately, besides the slightly-OCD "good, clean, organized" feeling, the value list came up pretty short. As in, I can't think of any solid value it actually provides.

You're working on a bugfix, that includes a tiny refactor. So it's not a fix/ or refactor/. Your feature branch better include documentation updates along with it, so it's not purely feature/ or docs/. And even if those prefixes were accurate, what decision do they help with? What actionable information do they carry? None, in my experience. Only added frustration at the extra characters I have to type every single time I type a branch name in git (hundreds of times a day).

yatiac profile image
Rafael E.

We use a mix of git flow with ticket based. So each feature corresponds to a ticket and we have a naming convention like : [us|b|t]-[number]-[initials] where:
us = user story
b = bug
t = task

we end up with branches like: us-01234-ye, b-65432-jq and so one.

at the end of each one we just do a feature finish.

cescquintero profile image
Francisco Quintero 🇨🇴

I've always preferred BPMP because I've seen projects where feature branches live an eternity.

Also, depending on the project and management tool, a combo between ticket and BPMP is fine as well.

I like keeping things in order and BPMP let's me do that in git branches.

ikemkrueger profile image
Ikem Krueger

What does „BPMP“ stands for?

guitarkat profile image
Kat • Edited

Ours is ticket based but I also tie it to bugfixes, features, release(through tagging and a dev and staging branch respectively) and master being prod.

I like these folders but what if you are not using gitflow? My guitgui splits it with the prefixes bugfix/, features/ which is pulled from the ticketing system.

I really like the idea of the documentation being in there and just tasks being seeing as tasks (I can do this now actually - neat idea).

I do love the logical splitting of modules. If you have a current repo with the folder setup I've mentioned, how do you translate it with an old repo or current? But I'm also worried about it conflicting with my current setup but maybe there is a way to mix? I think there is. This has given me some really good things to think about.

Also how to you get gitflow on a current repo?

Thank you for this awesome post. :)

asparallel profile image
AsParallel • Edited

Since no one answered and they're good questions:

  • I like these folders but what if you are not using gitflow?

Most guis will interpret the branch name as prefix/identity, gitflow doesn't have any impact on this, it just exploits it. You can choose your own adventure in that regard.

  • But I'm also worried about it conflicting with my current setup but maybe there is a way to mix?

The most natural way to mix would be to do a branch name with prefix/ticket-number, or prefix/#ticket-number if your system mandates the # to detect a ticket identity. You can also just put ticket numbers in the commit message body. In our case we require a ticket link to all associated issues, stories and epics so that's where we put the linkages. I've yet to see a system that won't correctly detect them there.

If you want to customize, see the end of this reply.

Note: regex: ʌ# is the matcher for comments on the git commit message, so be wary if using git-cli

  • Also how to you get gitflow on a current repo?
cd {local_repo_clone_dir} 
git checkout master
git branch -u origin/master
git flow init -d
  • Notes on gitflow, behavior

Gitflow as a tool is just an automator ( It creates a branch based on a convention, sets some configuration properties on the repository and the automates merging the finished code to the target branches.

Specifically regarding gitflow: Some products that support gitflow (ex: bitbucket) include githooks on the precommit event to check for naming convention. But that is the extent of the integration

The gitflow tool itself sets the following properties which can be used to configure how your branches are constructed.

Note: If you do pull requests as part of your process, you'll need to break out of gitflow at the PR stage as it's not supported.

git config gitflow.branch.master master
git config gitflow.branch.develop develop
git symbolic-ref HEAD refs/heads/master
git commit --allow-empty --quiet -m Initial commit
git branch --no-track develop master
git checkout -q develop
git config gitflow.prefix.feature feature/
git config gitflow.prefix.bugfix bugfix/
git config gitflow.prefix.release release/
git config gitflow.prefix.hotfix hotfix/
git config support/
git config gitflow.prefix.versiontag
git config gitflow.path.hooks <path>:/.git/hooks
androzhk profile image

I've also seen author initials used to prefix the branch.
John Smith work on ticket FOO-42 -> js/FOO-42-doing-cool-stuff
Cannot say it's a way to go, but it has some pros

jasonkarns profile image
Jason Karns • Edited

Git already has a mechanism to prefix author initials... remotes. If you need to segment branches by author, I would humbly submit that you ought to be using forks.

asparallel profile image
AsParallel • Edited

This assumes you're using github. If you're bound to a central repository in an enterprise scenario, there's generally only 1 repo per project and forks aren't a thing.

Note: They should be a thing, but most enterprises also don't "get" source control, of any kind. Using author initials to supplement a gui is almost as bad an idea as using the commit title line to track project management information.

andersonjoseph profile image
Anderson. J

I've never had a way to organize my git branches. 'Gitflow with steroids' seems a good idea to start. Thanks!

bdwakefield profile image
Benjamin D Wakefield

All that stuff with folders feels like a whole lot of overkill. Why? Just name your branches (we currently copy part of the link from Trello since that is what we are using for tasks right now: 1234-name-of-card), merge without a fast forward, nuke when done. Tag your releases. I've yet to see any real compelling evidence that keeping all of this stuff around forever or going 6 feet deep into folders etc really buys anything.

We've got persistent branches for each environment; but only because builds are tied to them. Releases are prepped using a hard reset of master once everything has been, QA'd, UAT'd, approved, and a release tag created.

ralcr profile image
Cristian Baluta • Edited

Kind of tsk based with full task name, even made a tool to create and switch between branches with ease by using only the task number

hardkoded profile image
Darío Kondratiuk

That's pretty cool!