How to organize your git branches

Darío Kondratiuk on September 17, 2018

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 wa... [Read Full]
markdown guide
 

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.

 

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.

 

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.

 

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!

 
 

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!

 

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.

 

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.

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.

 

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.

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.

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.

 
 

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:

endoflineblog.com/gitflow-consider...
endoflineblog.com/oneflow-a-git-br...

I highly recommend reading all three before approaching the whiteboard.

Cheers!

 

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

 

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.

 

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.

 

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

 

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. :)

 

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 (github.com/nvie/gitflow). 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 gitflow.prefix.support support/
git config gitflow.prefix.versiontag
git config gitflow.path.hooks <path>:/.git/hooks
 

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.

 

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.

 
 

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).

 

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 github.com/ralcr/Jit

 
 

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.

code of conduct - report abuse