When creating a new branch in Git using git branch <branch-name> or git checkout -b <branch-name>, you might encounter the error: fatal: A branch named '<branch-name>' already exists.

This is a straightforward message from Git indicating that you are trying to create a branch with a name that is already in use in your local repository. This guide will show you how to handle this situation.

Why This Error Occurs

Git requires every branch in a repository to have a unique name. You cannot have two local branches with the exact same name. This error simply enforces that rule.

The most common reasons for encountering this are:

  1. You forgot that you had already created a branch with that name.
  2. You are collaborating with others and pulled a branch from the remote repository that has the same name you now want to use.
  3. A simple typo, where you intended to type a different name.

How to Resolve the “Branch Already Exists” Error

You have a few options, depending on what you want to achieve.

Option 1: Choose a Different Branch Name

The simplest solution is to pick a name that isn’t already taken. If the name itself isn’t important, just try again with a new one.

# This failed
git checkout -b feature/login

# Try a more specific name
git checkout -b feature/login-v2

Option 2: Check Out the Existing Branch

If you see this error, you might realize you don’t need a new branch after all. You just want to switch to the existing one. In that case, use git checkout without the -b flag.

# Instead of creating a new one...
git checkout -b my-feature

# ...just switch to the existing one
git checkout my-feature

To see a list of all your local branches and verify their names, you can always use:

git branch

Option 3: Delete the Old Branch

If the existing branch is old, outdated, or no longer needed, you can delete it and then create your new branch with the same name.

Warning: Deleting a branch can lead to data loss if the commits on that branch have not been merged elsewhere. Make sure you no longer need the changes on the old branch.

  1. Delete the local branch: The -d flag deletes a branch only if it has been fully merged. For a safer option, use this first. 
    git branch -d old-feature

    If you are sure you want to delete the branch even if it’s not merged, use the -D flag (force delete).

    git branch -D old-feature
  2. Create your new branch: Now that the old name is free, you can create your new branch. 
    git checkout -b old-feature

Option 4: Reset an Existing Branch to a New Starting Point

Sometimes, you don’t want to delete a branch but rather “restart” it from a different commit. For example, you want feature/login to start from the latest main branch. You can do this with the --force option of git checkout or by resetting it.

Using checkout (simpler): If you want to start a new feature/login from your current HEAD and discard the old one:

git checkout -B feature/login

The -B flag is a convenient shortcut that tells Git to create the branch if it doesn’t exist, or reset it to the current commit if it does.

Using reset (more explicit):

# Switch to the branch you want to reset
git checkout feature/login

# Reset it to the latest commit from 'main'
git reset --hard main

# Now your 'feature/login' branch is identical to 'main'

Conclusion

The “fatal: A branch named ‘…’ already exists” error is a simple safeguard in Git. When you see it, take a moment to check your local branches with git branch. From there, you can decide whether to use a different name, switch to the existing branch, or delete/reset the old one to make way for the new.

Leave a comment

You may also enjoy