Git - Not Something We Can Merge

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: - 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 billing-module-setup, billing-ui-changes and billing-database-migration.

Change types as a prefix for naming branches (new-feature/twitter-feed, refactor/homepage/carousel, 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

Restrictions on naming branches borrows from restrictions in reference names. Names cannot:

1. begin with a dot (.) or end with the sequence .lock.

2. have two consecutive dots .. anywhere.

3. have ASCII control characters, space, tilde (~), caret (^), or colon (:) anywhere.

4. have question-mark (?), asterisk (*), or open bracket ([) anywhere.

5. begin or end with a slash (/) or contain multiple consecutive slashes

6. end with a dot (.).

7. contain a sequence (@{).

Git ignores a backslash (\) in a name. For example g checkout -b po\le will create a branch named pole.

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.

Additional Resources

• Git Branch Naming Convention
• Git Style Guide
• How to organize your git branches
• Understanding the GitHub flow
• Git Branch Naming Conventions