Git Error if the Branch Name Contains '/'

Description

You may encounter a cannot lock ref error when performing a Git operation. This error can commonly occur when using a branch name containing a / character. The error message would be similar to: error: cannot lock ref 'refs/heads/foo/bar': 'refs/heads/foo' exists; cannot create 'refs/heads/foo/bar'.

Environment

Impacted offerings:

• GitLab.com
• GitLab Dedicated

• GitLab Self-Managed

   

Cause

There are some naming limitations due to how Git stores references in the repository. If you working with a branch named foo, it will be stored in the repository as:

refs
└── heads
    └── foo

However, with a branch named foo/bar, it will be stored as:

refs
└── heads
    └── foo
        └── bar

Based on this example, it's now easier to understand the error message. Git cannot create 'refs/heads/foo/bar' because 'refs/heads/foo' exists.

Solution

Review the branches of your repository to identify a naming collision which can cause this error. It may be preferred to avoid using the / character so that this failure cannot occur.