How do you name your git branches?

Michael Lee 🍕 on December 19, 2018

I'm currently evaluating an alternative to Jira for managing our software development projects at work. One of the things that I'm having a hard ti... [Read Full]
markdown guide
 

If I were less lazy, I'd probably reference an issue number, but I usually give my name and a description of the general task. In looking at current branches:

  ben/add-haptic-feedback
  ben/small-meta-fix
  ben/some-gardening
 

This is pretty much what I do, our agile tracking software at work (Clubhouse) gives you tags based on the issue number, which automatically connects the ticket to the branch. You end up with branches that look like this:

wuz/ch1234/story-name-from-clubhouse

They have a nice copy button, which makes it easy to check out new branches.

If I am working on a non-work project, I use:

wuz/name-of-thing-i-am-doing
 

I got a little too generic at one point, reused a branch name and halted the server's code from updating (the person reporting the stall didn't know git fetch --prune … my office is a relatively recent git convert. don't judge… ).

I use a version of Ben's:

my-initials/dev2018/feature

Useful side effect: keeps little reminders for myself come time for annual self evaluation.

 
 

why your name is relevant to the feature? does someone who takes it over (in case you get sick or you take 1y off time) needs to rename it? Just my curiosity... Thanks

 

Git Flow is a well known and established way of handling branches that works really well on pretty much any sized project in my experience.

atlassian.com/git/tutorials/compar...

master = current state of the live site.

develop = stable development environment that keeps all developers in sync.

feature/feature-name = unstable new features under development or refactoring that might break the site.

hotfix = fixing a critical bug on the live site.

 

I'm surprised this is the only post mentioning Git Flow! I've been using it for a few years and absolutely love it. It's especially nice to have a methodology a CLI tool too.

The Atlassian docs are great, but whenever I want to look a Git Flow thing up I go here: danielkummer.github.io/git-flow-ch...

 

I know right? I was expecting the article to be about Git Flow, but it wasn't. Then I was expecting the first comment I saw to be about Git Flow, but it wasn't. Then I was expecting at least one comment to be about Git Flow, but there weren't any.

I had to make things right!

 

This plus JIRA-123 ticket number works well for us, so feature/WEB-123_some_description_to_help is picked up by JIRA and branches and commits are linked to the ticket, sorted.

On the traceability side we tag commits and record these as releases in JIRA giving us requirement to deployment tracking.

For all the flack JIRA gets I've yet to see another system link things together as easily and clearly

 
 

I see feature branches as being temporary (the branch is usually deleted after merge). What I find to matter the most are the commits.

The solution for references in the VCS will probably depend on the new issue tracker. If you're using Github to track issues, the org/repo#issue format works pretty well for issues that are across repositories. If the issue is in the same repository, it can be referenced simply by the issue number (#issue format).

 

At my company we use an alternative app (that looks like Trello), and we name our branches according to the task number in the URL (so if this is mycompany.com/task/38, we will git checkout -b t38, the "t" standing for task. We tried to name our branches by the goal of the fix/feature, but it quickly become unefficient because you need to think of a good name to illustrate your branches, and chances are that your branches will evolve and not only do what you intended in the begining...

So instead we put a link in the PR description in order to view the full spec of the issue or the feature. Maybe the best would have been to create git issues instead of Trello-like task, but this is already better and scalable for us right now.

 

Mine can go from very generic jag/fix-dropdown-bug to something ridiculous jag/brand-spankin-new-footer-sets haha. The only thing that I try to avoid is having emojis in the branch names because it can screw up some terminals.

 
 

Here's something I want to try in the near future, and it's entirely inspired by Phabricator.

I won't allow the creation of "fix" or "feature branches" or personal dev branches in the "origin" remote repository. That is something the devs should keep on their local machine(s). If they must keep two machines in sync with each other then they can reference each other as Git remotes, or use a Raspberry PI or network storage in the middle. That's easy to set up using git. But pushing those non-standard / non-approved branches to origin would be rejected by Phabricator.

Essentially the Phabricator-controlled repo would only allow one or two main branches (e.g. master and develop, something that is latest stable and the other with latest reviewed changes).

Phabricator encourages to use a strict code review process using a tool called "Differential". Only reviewed and approved changes are merged as a squash-commit into the main development branch. It's a bit radical, because it gets rid of in-between commit history... but maybe it also makes the overall commit history more readable, since each code review should have a meaningful description, test plan, assigned reviewers etc.

 

Generally I do contributor/issuenumber-briefname, e.g. fluffy/294-fix-broken-frobnicator. If it's an ad-hoc topic branch I'll leave out the issue number if I don't feel like going through the rigamarole of opening an issue first.

For release staging I do e.g. release/v0.1.9 or maybe release/v0.1.9-new-haptics if there's a specific impetus or major feature to the release. (And of course when I cut a release I tag the commit that was used to build it.)

On projects where either I'm the sole contributor or I expect other people to work in their own forks, I generally use feature instead of contributor name (e.g. feature/123-object-hierarchy or whatever) although that's more a force of habit at that point since it's not like there's any point to namespacing my branches.

 

If there is no ID possible, I usually try to come up with a description of the feature that is as short as possible.

This is what i do as well, if there is an ID available.

Depending on the projects structure, i define where the change occurs/what is affected.

An example: Adding a new Rest Endpoint to the backend for querying invoices:

backend/query-invoices

 
+ master
+ dev
+ v2018
  + feature1
    + root
    + user1
    + user2
  + feature2/sub-feature
    + root
    + user1
    + user2

Turns out that some features are re engineered over years so root year folder helps in isolating feature names. Also root branch is created to differentiate sub feature folder as you can have sub folders inside features.

Ideally it is bad practice to have too many feature branches, and too many branches as well.

Best way is to distribute code across multiple repositories and either create packages with good package manager or use links with sub repositories.

 

Overall, we use a fork-and-branch model. The rest depends on where in the project lifecycle things are and what our customer-dictates are.

Early in a project-lifecycle, there often aren't "issues", per se. It's usually "we need IOC by <insert date that's some fraction of the length of time that it likely ought to be>". It usually works out to a flow like:

  • initialize project in relevant git-service: do the initial commit so you can begin to branch; set up branch-protection on the base-branch(es)
  • Gen-off a "project-scaffolding" branch: add issue templates, MR/PR templates, contribution guides, CoCs, baseline test-configs (syntax linters for the languages/frameworks to be used), etc. Then merge that in
  • Start forking off IOC-supporting branches (naming is ad hoc)

Because we do work for multiple customers, things begin to deviate once the above is done. Some customers want issues managed in Jira. Some want issues managed elsewhere. Some are fine leaving them wholly contained within a given git service. Once we're to the point that there's discreet defined tasks that need to be individually coordinated and tracked, then we start using the customer-preferred tracking system. For tasks tracked wholly within the git service, we usually just do "Issue_<NUMBER>" to reflect the git issue-ID. If customer is mandating Jira, then we usually do "<PROJECT_ABBREVIATION>-<NUMBER>". For other issue tracking systems, we do either whatever's native to that system or whatever the customer asks.

...And if we're doing stuff on spec (anticipating a need for a customer or our own organization), then it's pretty much dealer'sdeveloper's-choice.

 

pre - for the pre-production environment
testing - for the integration environment
hotfix/DEV-1234 - for the hotfix branches, with DEV-1234 being the JIRA issue for the project
feature/DEV-1234 - for the feature branches, with DEV-1234 being the JIRA issue for the project

 

I like the key word prepended to the id of the issue! Very clean way to sort branches :)

 

I have a little script that takes the title of a Github Issue and kebab_cases it. I also prefix the Issue number, so all our branches are like:

5634-add-watever-to-watever
5670-fix-watever
5793-add-things

We use issue numbers a lot when we talk in the team, so when I want to checkout a branch, I just do git checkout the issue number and tab tab.

We do not prefix with the name of the developer because we have cases where one developer can take over the job of another developer.

 

Key prefix is here typical for Atlassian Toolchain because it will connect / link different components of whole system together, for example: BitBucket/Git branch or Bamboo build to actual Jira issue ticket. In addition it is useful when branch briefly describe its purpose, i.e.:
feature/DEV-42-dark-theme or bugfix/DEV-666-fix-comments-box

 

Branches in personal projects are just <bug/fix/feature?>_short-desc.

At work, my personal branches are named as abhnv/<sprint#/bug/feature>_small-description. We don't use issue numbers because Asana task ids are very long. We tend to put them in PR merges' commit message.

 

So far (since I'm a Git noobie), with Jira as well, I use branches named like:
eljay/DEV-1234 restructure frobnicator

Note: those are not spaces (U+0020) in there, they are non-breaking spaces (U+00A0).

The name is to help keep branches straight with the other 200 developers on the team. The DEV-1234 is the associated Jira number. The very short descriptive is to remind me what the heck it is related to.

Regarding Jira...

I'm not happy with Jira. I suspect that it is not Jira's fault, but rather how our team's Jira has been configured. I've no experience administering or configuring Jira. From what I've read, Jira has bazillions of configuration capabilities.

It appears that our Jira is configured for the PM folks, and not very much useful for the development team. Which makes it very awkward to use. And (also probably our fault) our team's Sprint Backlog is commingled with the PO's Product Backlog, which leads to all sorts of stepping-on-toes all around.

For Jira fans, I'm betting that what I just said is a "Oh my, you're doing it wrong!" moment.

I have previously used TFS as a project and issue tracker, and I do like Jira better. Even our awkward Jira.

 

Referencing an issue number is such a great practice, but I usually forget. I just try to be as semantic as I can:

jacobherrington/email-ui-spike
jacobherrington/bug/fix-checkout-input-padding
jacobherrington/chore/add-some-automation-script
 

Where I work we name our branches like so.
For any new feature you want to add :
feat/user-email-notifications
For any bug fix
fix/user-signup-buttons

 

I do a mix of Git-Flow branch naming and separators for ID and key.

Template:
{type}/{ticket number / name / indicator}/{max 5 word desc}

Exp:
feature/dev-27/user_profile_images_update
hotfix/blog-17/left_menu_padding
bug/project-2486457/header_bannder_width_fix

The integer related to the ticket number in whatever ticket tracking program is used. JIRA, OneProject, etc. Then a short desc. to indicate what the change set relates to.

 

In my team we use to name the git branches following this pattern:
username_#issue_short_desc. Is really hepfull in medium teams with a lot of issues.

 

Where I work and generally I do mine this way:

ft-name-of-the-task-#story-id
It can either be a feature, bug or chore with that I just prefix with the type of task I'm working on.

 

Naming is hard, it's unsolved problem actually.
But we should follow a consistent principle, in my case, it's about do-something.

 
 

None of my branches live very long (and it's not how we track things back from JIRA tickets) so I tend to name them whatever will help me remember what they are for the few days they are alive :)

 

In gitlab it's basically reponame#42 so I guess you can derive from that?

 
 

Usually I use :

issue-number_small-description

In this way is quite simple to retrieve informations about the meaning of the branch.

code of conduct - report abuse