I use Git for version control. My workflow is simple; create branch from the main branch, make changes on the new branch, commit the changes and merge the changes to the main branch. I have aliased the
git command to
g and combine the commands in a single line in the form
g checkout master;g merge branch-name; and it works.
It was therefore a surprise when I ran
g checkout master;g merge add_progress;g push;g checkout add_progress and Git responded with merge: add_progress - not something we can merge. Being a moderate git user, my first thought was I had used a restricted word in the branch name. Could I have typed the branch name wrongly? I rechecked the branch name and re-ran the command–same result.
Before searching the cause of the error, I replaced the branch name with the commit ID for the merge command. That worked without raising the error. So, what was wrong with my branch name? Does Git have any restrictions on branch names?
It Could Be a Silly Typo
Turns out, the error can arise from a typo in the branch name. Taking a deeper look on my Git command, I realized I had typed an underscore (_) for the branch name (
add_progress) instead of a dash (
add-progress), damn it!
I could not figure out why the Git team decided against a simplified error like merge: <branch_name> - invalid branch name. This begged the question, are there any restrictions or guidelines on branch naming?
Git Branch Naming Conventions
While conventions are good for consistency, no single common convention exists for branch naming. Different teams adopt different styles for naming their Git branches.
Some teams prefer prefixing branch names with (first and last names followed by a forward and branch description separated by hyphens)[https://dev.to/g_abud/advanced-git-reference-1o9j].
Others break down features into subtasks and name branches based on feature-subtasks. This would have a
billing-module have branches names such as
Change types as a prefix for naming branches (
fix/twitter-feed/number-of-tweets) is adopted by other teams. Using this style and separating the change type and feature with a slash (/) makes Git create separate folders in
git/refs/heads/ directory of your repository.
BEM (Block Element Modifier) is another convention used in naming Git branches. This style takes
reason__details--tag format. Reason is the change type, details provide a short description of the change while the tag is optional. When the tag is available, it may refer to an external tracker or other extra details.
Branch Naming Restrictions
begin with a dot (
.) or end with the sequence
have two consecutive dots
have ASCII control characters, space, tilde (
~), caret (
^), or colon (
have question-mark (
?), asterisk (
*), or open bracket (
begin or end with a slash (
/) or contain multiple consecutive slashes
end with a dot (
contain a sequence (
Git ignores a backslash (
\) in a name. For example
g checkout -b po\le will create a branch named
An opening bracket
( in a name produces an incomplete command prompt (
>). You have to press Ctrl+C to revert to your normal terminal prompt. Maybe the
( has a special meaning to Git.
Every cloud has a silver lining. Without the error, I would not have taken the effort to learn how others handle Git branching conventions and naming.