I've been using a local git repository interacting with my group's CVS repository for several months, now. I've made an almost neurotic number of branches, most of which have thankfully merged back into my trunk. But naming is starting to become an issue. If I have a task easily named with a simple label, but I accomplish it in three stages which each include their own branch and merge situation, then I can repeat the branch name each time, but that makes the history a little confusing. If I get more specific in the names, with a separate description for each stage, then the branch names start to get long and unwieldy.
I did learn looking through old threads here that I could start naming branches with a / in the name, i.e., topic/task, or something like that. I may start doing that and seeing if it helps keep things better organized.
What are some best practices for naming git branches?
Edit: Nobody has actually suggested any naming conventions. I do delete branches when I'm done with them. I just happen to have several around due to management constantly adjusting my priorities. :) As an example of why I might need more than one branch on a task, suppose I need to commit the first discrete milestone in the task to the group's CVS repository. At that point, due to my imperfect interaction with CVS, I would perform that commit and then kill that branch. (I've seen too much weirdness interacting with CVS if I try to continue to use the same branch at that point.)
This question is related to
git
naming-conventions
branch
The answer is
My personal preference is to delete the branch name after I’m done with a topic branch.
Instead of trying to use the branch name to explain the meaning of the branch, I start the subject line of the commit message in the first commit on that branch with “Branch:” and include further explanations in the body of the message if the subject does not give me enough space.
The branch name in my use is purely a handle for referring to a topic branch while working on it. Once work on the topic branch has concluded, I get rid of the branch name, sometimes tagging the commit for later reference.
That makes the output of git branch more useful as well: it only lists long-lived branches and active topic branches, not all branches ever.
A successful Git branching model by Vincent Driessen has good suggestions. A picture is below. If this branching model appeals to you consider the flow extension to git. Others have commented about flow
Driessen's model includes
A master branch, used only for release. Typical name
master.A "develop" branch off of that branch. That's the one used for most main-line work. Commonly named
develop.Multiple feature branches off of the develop branch. Name based on the name of the feature. These will be merged back into develop, not into the master or release branches.
Release branch to hold candidate releases, with only bug fixes and no new features. Typical name
rc1.1.
Hotfixes are short-lived branches for changes that come from master and will go into master without development branch being involved.
I've mixed and matched from different schemes I've seen and based on the tooling I'm using.
So my completed branch name would be:
name/feature/issue-tracker-number/short-description
which would translate to:
mike/blogs/RSSI-12/logo-fix
The parts are separated by forward slashes because those get interpreted as folders in SourceTree for easy organization. We use Jira for our issue tracking so including the number makes it easier to look up in the system. Including that number also makes it searchable when trying to find that issue inside Github when trying to submit a pull request.
A successful Git branching model by Vincent Driessen has good suggestions. A picture is below. If this branching model appeals to you consider the flow extension to git. Others have commented about flow
Driessen's model includes
A master branch, used only for release. Typical name
master.A "develop" branch off of that branch. That's the one used for most main-line work. Commonly named
develop.Multiple feature branches off of the develop branch. Name based on the name of the feature. These will be merged back into develop, not into the master or release branches.
Release branch to hold candidate releases, with only bug fixes and no new features. Typical name
rc1.1.
Hotfixes are short-lived branches for changes that come from master and will go into master without development branch being involved.
Note, as illustrated in the commit e703d7 or commit b6c2a0d (March 2014), now part of Git 2.0, you will find another naming convention (that you can apply to branches).
"When you need to use space, use dash" is a strange way to say that you must not use a space.
Because it is more common for the command line descriptions to use dashed-multi-words, you do not even want to use spaces in these places.
A branch name cannot have space (see "Which characters are illegal within a branch name?" and git check-ref-format man page).
So for every branch name that would be represented by a multi-word expression, using a '-' (dash) as a separator is a good idea.
Following up on farktronix's suggestion, we have been using Jira ticket numbers for similar in mercurial, and I'm planning to continue using them for git branches. But I think the ticket number itself is probably unique enough. While it might be helpful to have a descriptive word in the branch name as farktronix noted, if you are switching between branches often enough, you probably want less to type. Then if you need to know the branch name, look in Jira for the associated keywords in the ticket if you don't know it. In addition, you should include the ticket number in each comment.
If your branch represents a version, it appears that the common convention is to use x.x.x (example: "1.0.0") format for branch names and vx.x.x (example "v1.0.0") for tag names (to avoid conflict). See also: is-there-an-standard-naming-convention-for-git-tags
Why does it take three branches/merges for every task? Can you explain more about that?
If you use a bug tracking system you can use the bug number as part of the branch name. This will keep the branch names unique, and you can prefix them with a short and descriptive word or two to keep them human readable, like "ResizeWindow-43523". It also helps make things easier when you go to clean up branches, since you can look up the associated bug. This is how I usually name my branches.
Since these branches are eventually getting merged back into master, you should be safe deleting them after you merge. Unless you're merging with --squash, the entire history of the branch will still exist should you ever need it.
I've mixed and matched from different schemes I've seen and based on the tooling I'm using.
So my completed branch name would be:
name/feature/issue-tracker-number/short-description
which would translate to:
mike/blogs/RSSI-12/logo-fix
The parts are separated by forward slashes because those get interpreted as folders in SourceTree for easy organization. We use Jira for our issue tracking so including the number makes it easier to look up in the system. Including that number also makes it searchable when trying to find that issue inside Github when trying to submit a pull request.
Why does it take three branches/merges for every task? Can you explain more about that?
If you use a bug tracking system you can use the bug number as part of the branch name. This will keep the branch names unique, and you can prefix them with a short and descriptive word or two to keep them human readable, like "ResizeWindow-43523". It also helps make things easier when you go to clean up branches, since you can look up the associated bug. This is how I usually name my branches.
Since these branches are eventually getting merged back into master, you should be safe deleting them after you merge. Unless you're merging with --squash, the entire history of the branch will still exist should you ever need it.
Note, as illustrated in the commit e703d7 or commit b6c2a0d (March 2014), now part of Git 2.0, you will find another naming convention (that you can apply to branches).
"When you need to use space, use dash" is a strange way to say that you must not use a space.
Because it is more common for the command line descriptions to use dashed-multi-words, you do not even want to use spaces in these places.
A branch name cannot have space (see "Which characters are illegal within a branch name?" and git check-ref-format man page).
So for every branch name that would be represented by a multi-word expression, using a '-' (dash) as a separator is a good idea.
Why does it take three branches/merges for every task? Can you explain more about that?
If you use a bug tracking system you can use the bug number as part of the branch name. This will keep the branch names unique, and you can prefix them with a short and descriptive word or two to keep them human readable, like "ResizeWindow-43523". It also helps make things easier when you go to clean up branches, since you can look up the associated bug. This is how I usually name my branches.
Since these branches are eventually getting merged back into master, you should be safe deleting them after you merge. Unless you're merging with --squash, the entire history of the branch will still exist should you ever need it.
My personal preference is to delete the branch name after I’m done with a topic branch.
Instead of trying to use the branch name to explain the meaning of the branch, I start the subject line of the commit message in the first commit on that branch with “Branch:” and include further explanations in the body of the message if the subject does not give me enough space.
The branch name in my use is purely a handle for referring to a topic branch while working on it. Once work on the topic branch has concluded, I get rid of the branch name, sometimes tagging the commit for later reference.
That makes the output of git branch more useful as well: it only lists long-lived branches and active topic branches, not all branches ever.
Following up on farktronix's suggestion, we have been using Jira ticket numbers for similar in mercurial, and I'm planning to continue using them for git branches. But I think the ticket number itself is probably unique enough. While it might be helpful to have a descriptive word in the branch name as farktronix noted, if you are switching between branches often enough, you probably want less to type. Then if you need to know the branch name, look in Jira for the associated keywords in the ticket if you don't know it. In addition, you should include the ticket number in each comment.
If your branch represents a version, it appears that the common convention is to use x.x.x (example: "1.0.0") format for branch names and vx.x.x (example "v1.0.0") for tag names (to avoid conflict). See also: is-there-an-standard-naming-convention-for-git-tags
My personal preference is to delete the branch name after I’m done with a topic branch.
Instead of trying to use the branch name to explain the meaning of the branch, I start the subject line of the commit message in the first commit on that branch with “Branch:” and include further explanations in the body of the message if the subject does not give me enough space.
The branch name in my use is purely a handle for referring to a topic branch while working on it. Once work on the topic branch has concluded, I get rid of the branch name, sometimes tagging the commit for later reference.
That makes the output of git branch more useful as well: it only lists long-lived branches and active topic branches, not all branches ever.
Here are some branch naming conventions that I use and the reasons for them
Branch naming conventions
- Use grouping tokens (words) at the beginning of your branch names.
- Define and use short lead tokens to differentiate branches in a way that is meaningful to your workflow.
- Use slashes to separate parts of your branch names.
- Do not use bare numbers as leading parts.
- Avoid long descriptive names for long-lived branches.
Group tokens
Use "grouping" tokens in front of your branch names.
group1/foo
group2/foo
group1/bar
group2/bar
group3/bar
group1/baz
The groups can be named whatever you like to match your workflow. I like to use short nouns for mine. Read on for more clarity.
Short well-defined tokens
Choose short tokens so they do not add too much noise to every one of your branch names. I use these:
wip Works in progress; stuff I know won't be finished soon
feat Feature I'm adding or expanding
bug Bug fix or experiment
junk Throwaway branch created to experiment
Each of these tokens can be used to tell you to which part of your workflow each branch belongs.
It sounds like you have multiple branches for different cycles of a change. I do not know what your cycles are, but let's assume they are 'new', 'testing' and 'verified'. You can name your branches with abbreviated versions of these tags, always spelled the same way, to both group them and to remind you which stage you're in.
new/frabnotz
new/foo
new/bar
test/foo
test/frabnotz
ver/foo
You can quickly tell which branches have reached each different stage, and you can group them together easily using Git's pattern matching options.
$ git branch --list "test/*"
test/foo
test/frabnotz
$ git branch --list "*/foo"
new/foo
test/foo
ver/foo
$ gitk --branches="*/foo"
Use slashes to separate parts
You may use most any delimiter you like in branch names, but I find slashes to be the most flexible. You might prefer to use dashes or dots. But slashes let you do some branch renaming when pushing or fetching to/from a remote.
$ git push origin 'refs/heads/feature/*:refs/heads/phord/feat/*'
$ git push origin 'refs/heads/bug/*:refs/heads/review/bugfix/*'
For me, slashes also work better for tab expansion (command completion) in my shell. The way I have it configured I can search for branches with different sub-parts by typing the first characters of the part and pressing the TAB key. Zsh then gives me a list of branches which match the part of the token I have typed. This works for preceding tokens as well as embedded ones.
$ git checkout new<TAB>
Menu: new/frabnotz new/foo new/bar
$ git checkout foo<TAB>
Menu: new/foo test/foo ver/foo
(Zshell is very configurable about command completion and I could also configure it to handle dashes, underscores or dots the same way. But I choose not to.)
It also lets you search for branches in many git commands, like this:
git branch --list "feature/*"
git log --graph --oneline --decorate --branches="feature/*"
gitk --branches="feature/*"
Caveat: As Slipp points out in the comments, slashes can cause problems. Because branches are implemented as paths, you cannot have a branch named "foo" and another branch named "foo/bar". This can be confusing for new users.
Do not use bare numbers
Do not use use bare numbers (or hex numbers) as part of your branch naming scheme. Inside tab-expansion of a reference name, git may decide that a number is part of a sha-1 instead of a branch name. For example, my issue tracker names bugs with decimal numbers. I name my related branches CRnnnnn rather than just nnnnn to avoid confusion.
$ git checkout CR15032<TAB>
Menu: fix/CR15032 test/CR15032
If I tried to expand just 15032, git would be unsure whether I wanted to search SHA-1's or branch names, and my choices would be somewhat limited.
Avoid long descriptive names
Long branch names can be very helpful when you are looking at a list of branches. But it can get in the way when looking at decorated one-line logs as the branch names can eat up most of the single line and abbreviate the visible part of the log.
On the other hand long branch names can be more helpful in "merge commits" if you do not habitually rewrite them by hand. The default merge commit message is Merge branch 'branch-name'. You may find it more helpful to have merge messages show up as Merge branch 'fix/CR15032/crash-when-unformatted-disk-inserted' instead of just Merge branch 'fix/CR15032'.
Why does it take three branches/merges for every task? Can you explain more about that?
If you use a bug tracking system you can use the bug number as part of the branch name. This will keep the branch names unique, and you can prefix them with a short and descriptive word or two to keep them human readable, like "ResizeWindow-43523". It also helps make things easier when you go to clean up branches, since you can look up the associated bug. This is how I usually name my branches.
Since these branches are eventually getting merged back into master, you should be safe deleting them after you merge. Unless you're merging with --squash, the entire history of the branch will still exist should you ever need it.
Here are some branch naming conventions that I use and the reasons for them
Branch naming conventions
- Use grouping tokens (words) at the beginning of your branch names.
- Define and use short lead tokens to differentiate branches in a way that is meaningful to your workflow.
- Use slashes to separate parts of your branch names.
- Do not use bare numbers as leading parts.
- Avoid long descriptive names for long-lived branches.
Group tokens
Use "grouping" tokens in front of your branch names.
group1/foo
group2/foo
group1/bar
group2/bar
group3/bar
group1/baz
The groups can be named whatever you like to match your workflow. I like to use short nouns for mine. Read on for more clarity.
Short well-defined tokens
Choose short tokens so they do not add too much noise to every one of your branch names. I use these:
wip Works in progress; stuff I know won't be finished soon
feat Feature I'm adding or expanding
bug Bug fix or experiment
junk Throwaway branch created to experiment
Each of these tokens can be used to tell you to which part of your workflow each branch belongs.
It sounds like you have multiple branches for different cycles of a change. I do not know what your cycles are, but let's assume they are 'new', 'testing' and 'verified'. You can name your branches with abbreviated versions of these tags, always spelled the same way, to both group them and to remind you which stage you're in.
new/frabnotz
new/foo
new/bar
test/foo
test/frabnotz
ver/foo
You can quickly tell which branches have reached each different stage, and you can group them together easily using Git's pattern matching options.
$ git branch --list "test/*"
test/foo
test/frabnotz
$ git branch --list "*/foo"
new/foo
test/foo
ver/foo
$ gitk --branches="*/foo"
Use slashes to separate parts
You may use most any delimiter you like in branch names, but I find slashes to be the most flexible. You might prefer to use dashes or dots. But slashes let you do some branch renaming when pushing or fetching to/from a remote.
$ git push origin 'refs/heads/feature/*:refs/heads/phord/feat/*'
$ git push origin 'refs/heads/bug/*:refs/heads/review/bugfix/*'
For me, slashes also work better for tab expansion (command completion) in my shell. The way I have it configured I can search for branches with different sub-parts by typing the first characters of the part and pressing the TAB key. Zsh then gives me a list of branches which match the part of the token I have typed. This works for preceding tokens as well as embedded ones.
$ git checkout new<TAB>
Menu: new/frabnotz new/foo new/bar
$ git checkout foo<TAB>
Menu: new/foo test/foo ver/foo
(Zshell is very configurable about command completion and I could also configure it to handle dashes, underscores or dots the same way. But I choose not to.)
It also lets you search for branches in many git commands, like this:
git branch --list "feature/*"
git log --graph --oneline --decorate --branches="feature/*"
gitk --branches="feature/*"
Caveat: As Slipp points out in the comments, slashes can cause problems. Because branches are implemented as paths, you cannot have a branch named "foo" and another branch named "foo/bar". This can be confusing for new users.
Do not use bare numbers
Do not use use bare numbers (or hex numbers) as part of your branch naming scheme. Inside tab-expansion of a reference name, git may decide that a number is part of a sha-1 instead of a branch name. For example, my issue tracker names bugs with decimal numbers. I name my related branches CRnnnnn rather than just nnnnn to avoid confusion.
$ git checkout CR15032<TAB>
Menu: fix/CR15032 test/CR15032
If I tried to expand just 15032, git would be unsure whether I wanted to search SHA-1's or branch names, and my choices would be somewhat limited.
Avoid long descriptive names
Long branch names can be very helpful when you are looking at a list of branches. But it can get in the way when looking at decorated one-line logs as the branch names can eat up most of the single line and abbreviate the visible part of the log.
On the other hand long branch names can be more helpful in "merge commits" if you do not habitually rewrite them by hand. The default merge commit message is Merge branch 'branch-name'. You may find it more helpful to have merge messages show up as Merge branch 'fix/CR15032/crash-when-unformatted-disk-inserted' instead of just Merge branch 'fix/CR15032'.
Source: Stackoverflow.com