
Git Branch Naming Conventions - sanketsaurav
https://deepsource.io/blog/git-branch-naming-conventions/
======
TomasEkeli
I've seen projects outlive multiple issue-tracking systems.

Nothing inherently wrong with having the number in the branch or commit-
message, but please make sure the rest of the name/message stands on its own.

~~~
kevincox
If you are lucky you can import old issues with the same IDs. If not then

This is why I generally prefer using the full issue URL in comments, but that
is unwieldy for branch names.

~~~
Arelius
Sure, but sometimes the old issues and the old server just gets lost in the
transition. I'm not sure full URLs really help because it's unlikely to have
both issue trackers continuing to run. I think the parent's point to add some
detail is valuable.

"Fix for PJ-1029: Screen flicker on GTX1070 while jumping off cliff"

------
craigmcnamara
I disagree with naming conventions for branches. Just give it a name, I like
to have have a bit of fun sometimes. For example: 'org-mode', 'more-org-mode'
and 'org-mode-3-still-org-moding' are 3 real branches I recently shipped. All
the naming convention does is make another pointless argument. As long as the
name is more descriptive than 'my-branch' I'm fine with it. Argue over
something less pointless.

~~~
abhorrence
I fall somewhere in between. I don't mind if the names are random and fun. But
I do like: \- avoiding the use of slashes (because with enough folks working
on the same repo, you can get some crazy conflicts) \- prefixing with some
sort of "handle" (e.g. your initials) to help avoid branch name conflicts

~~~
battery_cowboy
I made it a policy to only use a-z, 0-9, and _ in any branch, file, folder, or
any other 'names' in the cli. Basically anything I'd type in the cli as an
identifier/name. I find it prevents weird issues with characters when
scripting and such, since the rest of the shiftable symbols on the 1-0 row (*,
&, etc.) tend to cause issues when used too much in names because they're also
used as operators and stuff. I think I started doing that with Windows
filenames, since it has so many limits, and it crossed over into my Linux cli
workflow.

------
amarraja
Just want to throw a small one in there: branch names are all lower case.

Prevents strange issues when you use a case insensitive file system like on
OSX or Windows

~~~
Spivak
Save yourself the headache and just make your project directories case
sensitive.

fsutil.exe file setCaseSensitiveInfo "C:\path\to\dir" enable

~~~
kaens
can't do on osx without reformat if i'm recalling correctly

~~~
taivokasper
APFS filesystem has volumes that share shape with Macintosh HD. You can create
a separate encrypted case sensitive volume called Development

~~~
httpsterio
that's like using a nuke to hammer a nail.

~~~
wwright
It really isn’t. APFS has excellent support for logical volumes, and it’s
barely any harder than creating a new folder.

(Each volume can also use an extra encryption layer if you want, which can be
super useful.)

------
dirtydroog
A handy thing about jira is that the ticket picks up the commit automatically,
so anyone viewing that ticket can go straight to the changes if the branch
begins with the ticket id.

I don't what the definition of a 'feature' is. Is it a task or something
bigger than a task?

I'm not a huge fan of overly verbose commit messages. They can make the job of
compiling release notes annoying.

~~~
jfkebwjsbx
> I'm not a huge fan of overly verbose commit messages. They can make the job
> of compiling release notes annoying.

Commit messages have little to do with releases or release notes. I'd argue
either your commits or your release notes are most likely wrong in some way if
you are doing that.

~~~
dirtydroog
We release our code as a debian package that stored in jfrog and then used to
build GCP images for each release.

[https://manpages.debian.org/testing/git-buildpackage/gbp-
dch...](https://manpages.debian.org/testing/git-buildpackage/gbp-
dch.1.en.html)

------
alkonaut
I'll add some more I find useful:

1\. Use All lower case. It's impossible to be consistent with any other case
(except all upper case). This is _important_. Git does NOT like case
insensitive file systems, and people having two branches with a segment with
different case causes problems.

2\. Use path segments to group branches. Categories can be versions or a
specific team or user e.g. version/v1.0 or topic/desktop/123-add-printing-
support or /topic/jimbob/123-add-printing-support Many systems will display
these segments in a tree structure so you can quickly navigate all branches of
a specific kind e.g. all your ongoing work separate from 20 version
maintenance branches.

3\. When making branches to cherry pick hotfixes to a different branch,
include the new target branch in the branch name to avoid confusion. E.g.
topic/123-fix-blank-password-always-accepted and topic/blank-passsword-always-
accepted-on-version-v1.0

~~~
halostatue
I discourage people from using path parts, because git actually treats it like
a path—and I’ve seen some conflicts with this. Better to just use hyphens as
separators and forget that you can use slashes at all.

Totally agree on all lower case.

~~~
FalconSensei
Yeah, I've had problems by using '/' on branch names. When you have something
like origin/jira/PROJ1-123/DoThisThing, some commands don't like.

If there's no good reason to do that, just don't.

~~~
Ayesh
I'm starting to like slashes in branch names. They are so easy to visually
grasp a list of branches.

Do you recall any of the problems you had? I'm frequently using
checkout/rebase/merge workflow and never had any problems. But I always felt I
am not using all features got had to offer.

~~~
halostatue
I had a recent situation where someone had created a branch called
`something/some-reason` and I had a branch called `something` that already
existed locally. I was unable to check out `something/some-reason` because
`something` already existed as a file.

Slashes in branch names are BAD ideas and should be avoided.

------
tga
As a side note, I always found it annoying to use “feature/123” instead of
“features/123“. Just like in REST APIs, the slash brings to mind a collection
or a file system directory, both of which should be pluralized.

~~~
leksak
I like fix/ refact/ feat/ special/ docs/ as pre-fixes and would not like to
pluralise any of them.

~~~
taftster
Why do you like these prefixes? Honest question.

My thoughts are: They don't really add any value to the branch nor do they
inform the developer. Identifying a bug fix, a new feature, or a document
branch doesn't change the way you treat the branch in any way, nor would it
necessarily prioritize the branch.

If you are drowning branches (like dozens or hundreds) and need to categorize
them like this, it's somewhat a "code smell" reflecting the development
process. Having too many things open and not closing them is not the greatest
strategy.

Anyway, honestly interested in your opinion and why you find those prefixes
useful. They seem to me to be some holdout from early blog postings
recommending this approach, but turn out to not really add any value.

~~~
FalconSensei
Agree with you. Branches are branches, they have code. That's it.

We review tickets / pull requests. Tickets should already be prioritized, be
tagged as task/improvement/fix, and pull requests are displayed in order of
creation. No need to worry about branch names. Just use either the ticket
code, or the title (or code-title)

------
Congeec
gitlab is already doing this. The default branch name when you click `Create
Merge Request` is issue_id-issue_title, like "477-update-readme-md"

~~~
sytse
Yep, and the default is now to both create a branch and a merge request
[https://www.dropbox.com/s/hgcwyifxkc6jrxh/Screenshot%202020-...](https://www.dropbox.com/s/hgcwyifxkc6jrxh/Screenshot%202020-05-01%2014.06.59.png?dl=0)

~~~
sytse
Docs for this are on
[https://docs.gitlab.com/ee/user/project/issues/issue_data_an...](https://docs.gitlab.com/ee/user/project/issues/issue_data_and_actions.html#create-
merge-request)

------
rhplus
I like throw an alias and date stamp in their too:

    
    
        <alias>/<yyyyMMdd>_some_short_description
        <alias>/<yyyyMMdd>_<task-id>_some_short_description
    

as it makes cleaning up old branches (both local and remote) just a little bit
easier. Author left the team? Delete. Untouched from 6 months back? Delete.

~~~
war1025
> it makes cleaning up old branches (both local and remote) just a little bit
> easier

Slightly different from what you are referring to, but I have the following
aliases that are super useful for cleaning up dead branches locally. They make
running `git branch` actually return a reasonable list of branches rather than
every branch I ever checked out in the past eight years.

    
    
       listdead = "!sh -c \"git branch -vv | grep ': gone]' | awk '{print \\$1}'\""
       prunedead = "!sh -c \"git branch -vv | grep ': gone]' | awk '{print \\$1}' | xargs git branch -D\""
    
    

So I will run `git listdead` after I merge something and pull the latest
`master`. Then it will usually show the branches that I have merged recently.

Then I run `git prunedead` and it goes through and actually deletes them.

I've never run into a case where branches I didn't want removed were in the
dead list, but I usually run `listdead` first just in case.

I think I swiped these from a StackOverflow answer at some point. Don't
remember.

~~~
Buttons840
My approach:

    
    
        refage = ! git for-each-ref --format='%(committerdate:relative),%(authorname),%(refname)' --sort -committerdate | column -t -s ','
    

This will list all refs (including tags, so you might want to grep the
output), their relative ages, and who the last commit author was, and then
formats it nicely. This makes it easy to see how many branches there and how
old they are, as well as who to contact to request deletion.

~~~
Buttons840
The above line is a git alias. I failed to mentioned that.

------
wirrbel
[https://trunkbaseddevelopment.com/](https://trunkbaseddevelopment.com/)

------
jzer0cool
Personally I like the `ft/...` format using "/" for divider. However, it does
not play with other software especially when the url is involved (e.g. the
branch name collides with url path). This issue fits loosely similar problem
to file naming to avoid problems (e.g. avoid " " (space), "-" (dash), or use
of any weird characters as part of filename. This is the reason why you may
find a lot of files named with "_" (underscore), especially in place of a
space.

This raises the question of using "-" or "_" for divider. Keep in mind there
are words that may have "-" (e.g "self-expression"). And as far as I know
there are no words that have "_".

In summary: And so I have decided on using "_" as my divider and plays well
with other integrated tooling for future robustness.

------
fullstackchris
A bit late to the party but I'm going to suggest something entirely different.

At my shop we often use a setup comprising simply of a develop branch, a
staging (test) branch, and of course master (as the live productive branch),
and we have build processes for both staging and master, which may differ
slightly based on the test vs. live environment.

We only use separate branches for possible new breaking features that could
cause hold ups in this chain. Otherwise, the work flow is develop on develop
(obviously :) ), test on staging, and merge to master once all tests pass.

Indeed, we're a small shop, but I can't help but recommend having these three
key branches. Even at a larger organization I could see this working, only
maybe having more separate feature branches as branched off from the develop
branch.

~~~
stult
Do you do code reviews on committing to develop? Other companies/organizations
generally have develop for work in between releases and merge into develop
from feature/bug fix branches (primarily owned by one individual) with pull
requests. The PR provides an opportunity for team code review and feedback
before merging into the shared develop branch. That also allows developers to
commit and push unfinished work to their own branches, so that it is backed up
on their remote repository rather than just their own laptop. Otherwise if
they pushed straight to develop, they'd constantly be breaking that shared
branch with non-functional, partially complete code.

------
FalconSensei
> For example, there could be multiple branches needed to work on one issue,
> possibly by different people.

I would say that in a case like this, probably you need to break that issue
into smaller tasks? Otherwise, how you keep track if the ticket is ready for
review, which parts are completed, etc?

------
DavidVoid
I like the <feature/featurename> naming scheme because in some Git software
(at least in Visual Studio) all of the branches starting with <feature/> will
show up in a collapsable folder named _feature_ in the interface.

~~~
urxvtcd
My team found slashes to be annoying though, they are illegal in docker tag
and DNS names. Tagging images with branch names and creating instances with
branch as subdomain is kinda convenient.

------
chadlavi
underscores or GTFO, so you can double-click to select the full branch name!

we also tend to prepend with our initials just in case someone else also has a
branch related to that issue and they give it a similar descriptive slug

------
Lio
I like to separate the issue tracker number from the rest of the branch name
using a / where the rest is separated by either a - or _

That allows easy ticket number extract using grep.

------
atonalfreerider
Another tip to add to point 2: keep the scope of each branch limited so that
the resulting name can be short. E.g. a branch with feature1, feature2, and
fix3 should be 3 separate branches. Combining too many things into one branch
is a common mistake, and a side-effect is that it's impossible to come up with
a short name for the branch.

------
TomK32
I use the same convention but whatever you do, be consistent even if you don't
intend to push a branch to a remote.

------
weeksie
Good advice. I usually like to put the ticket number at the end just because
it makes autocomplete a little easier.

------
ragona
Wait, are you telling me that

    
    
        git branch -b ohnowhathaveidone
    

isn't right??

~~~
bregma
That's correct. It should be

    
    
        git checkout -b ohnowhathaveidone

~~~
ragona
Oh no, right you are.

------
finnthehuman
if you need a branch naming scheme, then you probably have too many public
branches.

~~~
war1025
Everyone that uses branches regularly probably has a naming convention they
use. This is just an article saying how the author does theirs. It seems
reasonable to me.

I usually just do names like `dev/short_description`, but that is still a
naming convention.

~~~
finnthehuman
Sure, I have a branch naming scheme for my repos. But nobody else has to know
it because those branches don't leave my system. Branches published waiting
for code review are shortlived enough even if someone notices the branch name
in the review tool, they're likely not going to use it for anything.

Unless there are many long-lived, public, collaborative branches there's
little need for careful and deliberate naming convention across a team. And if
you have enough of those kind of branches, I contend that you're not merging
enough.

~~~
NateEag
From painful experience, I can say that leaving a branch that lasts longer
than a day only on your machine is begging to lose work.

Unless your machine is automatically backed up every hour, in which case
ignore me.

That has not been the case in most of my jobs, but pushing my WIP branch to a
remote every hour or two achieves that goal in practice (as long as I don't
have anything important that's not in a repo).

------
einpoklum
If this can make HN, here's my news item:

"Walking conventions:

1\. Stand.

2\. Move right foot ahead.

3\. Move left foot to match.

That's it. You can also do it the other way around, but be consistent."

