How To Rename a Local and Remote Git Branch

Renaming a Git branch keeps your repository organized and your team aligned. Common scenarios include fixing a typo in a branch name, migrating from master to main to match modern conventions, or updating a branch name to better reflect its purpose after requirements change. Whatever the reason, the process follows a consistent pattern: rename locally, push the new name, delete the old remote branch, and clean up stale references.

Git can rename a branch locally with a single command, but remotes do not have a built-in “rename” operation. Instead, you push the newly named branch, delete the old remote branch, and then prune stale tracking references. By the end of this guide, you will have renamed both your local and remote branches while keeping upstream tracking intact, and your teammates will know exactly how to update their clones.

Protected branches, open pull requests, or default branch status can block remote deletion on some hosting providers. GitHub, GitLab, and Bitbucket all offer branch rename features in their web interfaces that handle these edge cases automatically. When available, use the provider’s rename feature first, then update local clones using the steps in the “Update Other Clones After the Rename” section below.

Most systems include Git by default, but minimal server images and fresh desktop installations may not. If git --version returns command not found, install Git first using the guide for your distribution:

• Install Git on Ubuntu
• Install Git on Debian
• Install Git on Fedora
• Install Git on Linux Mint

Confirm Your Branch and Remote Before Renaming

Before making changes, confirm which branch you are on and which remote you will update. Many repositories use origin as the default remote name, but multi-remote setups or forks may use different names like upstream or a custom identifier.

Start inside your repository directory and list your local branches:

git branch

The asterisk marks your current branch:

  main
* old-branch
  feature-x

Next, check your configured remotes:

git remote -v

This shows the fetch and push URLs for each remote:

origin  git@github.com:username/repository.git (fetch)
origin  git@github.com:username/repository.git (push)

If you work with HTTPS remotes, the URL will show https://github.com/... instead. Either format works identically for branch operations.

Rename a Local Branch

Git provides the -m flag (short for --move) to rename branches. You can rename either the branch you are currently on or a different branch without switching to it first.

Rename the Current Branch

If you are already on the branch you want to rename, use git branch -m with just the new name:

git branch -m new-branch

This command produces no output on success. Verify the rename by listing branches again:

git branch

  main
* new-branch
  feature-x

The asterisk now appears next to new-branch, confirming the rename succeeded.

Rename a Different Branch Without Switching

To rename a branch you are not currently on, provide both the old and new names:

git branch -m old-branch new-branch

This approach saves time when you need to rename a branch but want to stay on your current working branch. Renaming only changes the branch reference itself; it does not touch the working directory or any uncommitted changes you may have.

Git 2.23 and later include git switch as a clearer alternative to git checkout for branch operations. If your Git version supports it, use git switch old-branch instead of git checkout old-branch when you need to change branches before renaming. On older systems, git checkout remains fully functional for this purpose.

Force Rename to Overwrite an Existing Branch

If a branch with the new name already exists, Git will refuse the rename with an error:

fatal: a branch named 'new-branch' already exists

When you intentionally want to overwrite the existing branch reference, use the uppercase -M flag, which is shorthand for --move --force:

git branch -M old-branch new-branch

This replaces the existing new-branch with old-branch under the new name. Use this option carefully, as it permanently redirects the branch reference and any commits unique to the original new-branch may become orphaned if they were not merged elsewhere.

Verify Upstream Tracking After Renaming

After renaming locally, check what remote branch your local branch tracks. A local rename does not automatically update the upstream configuration, which can cause confusion when pushing or pulling.

git branch -vv

Immediately after a local rename, the output still shows the old remote branch name:

* new-branch 5dacda1 [origin/old-branch] Initial commit

The [origin/old-branch] portion indicates your local new-branch is still tracking a remote branch called old-branch. The next section shows how to push the new name and update this tracking configuration.

Rename a Remote Branch

Git remotes do not support renaming branches directly. Instead, you push the newly named local branch, set it as the upstream, delete the old remote branch name, and prune stale references. Here is the complete workflow using origin as the remote name:

# If not already on the branch, switch to it first
git switch old-branch

# Rename the local branch
git branch -m new-branch

# Push the new branch name and set upstream tracking
git push -u origin new-branch

# Delete the old remote branch
git push origin --delete old-branch

# Clean up stale remote-tracking references
git fetch --prune origin

Each step serves a specific purpose. The following sections explain what happens at each stage and show the expected output.

Push the New Branch and Set Upstream

After renaming locally, push the new branch name to the remote. The -u flag (short for --set-upstream) configures your local branch to track the new remote branch for future git pull and git push operations:

git push -u origin new-branch

Expected output:

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Writing objects: 100% (3/3), 250 bytes | 250.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To github.com:username/repository.git
 * [new branch]      new-branch -> new-branch
branch 'new-branch' set up to track 'origin/new-branch'.

The final line confirms that your local branch now tracks the new remote branch. Verify this with:

git branch -vv

* new-branch 5dacda1 [origin/new-branch] Initial commit

The tracking reference now shows [origin/new-branch] instead of the old name.

Delete the Old Remote Branch

With the new branch pushed and tracking configured, delete the old remote branch name:

git push origin --delete old-branch

Expected output:

To github.com:username/repository.git
 - [deleted]         old-branch

At this point, the remote repository only has the new branch name. However, your local clone may still show a stale remote-tracking reference (origin/old-branch) until you prune it in the next step.

Prune Stale Remote-Tracking References

The git fetch --prune command removes local remote-tracking branches that no longer exist on the remote. Since you just deleted old-branch on the remote, prune cleans up your local reference:

git fetch --prune origin

If you deleted the remote branch yourself in the same session, Git may not show any prune output because your local tracking state is already current. However, when other clones run this command after you complete the rename, they will see output like:

From github.com:username/repository
 - [deleted]         (none)     -> origin/old-branch
 * [new branch]      new-branch -> origin/new-branch

This output confirms that Git pruned the stale reference and now shows the new branch.

Verify the Final State

After completing all steps, confirm that your local and remote branches are in sync. List all branches including remote-tracking branches:

git branch -a

Expected output showing the rename is complete:

  main
* new-branch
  feature-x
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/new-branch
  remotes/origin/feature-x

Notice that remotes/origin/old-branch no longer appears. The rename is complete on both your local clone and the remote.

Update Other Clones After the Rename

Teammates and CI systems with existing clones still have the old branch name in their local repositories. To synchronize, they need to fetch the changes and either rename their local branch or create a fresh checkout from the new remote branch.

Option 1: Rename the Local Branch to Match

This approach preserves any local commits and reflog history under the new name. Teammates should run:

git fetch --prune origin
git branch -m old-branch new-branch
git branch --set-upstream-to=origin/new-branch new-branch

Expected output from the upstream command:

branch 'new-branch' set up to track 'origin/new-branch'.

They can verify the tracking configuration with git branch -vv as shown earlier.

Option 2: Check Out the New Branch Fresh

If teammates do not need to preserve local work from the old branch, they can check out the new branch directly:

git fetch --prune origin
git switch -c new-branch origin/new-branch

This creates a local new-branch tracking origin/new-branch. If the old local branch still exists and is fully merged, they can delete it:

git branch -d old-branch

Git refuses to delete an unmerged branch with -d. If they are certain the branch is no longer needed and want to force deletion, use -D instead.

Troubleshooting

fatal: not a git repository

fatal: not a git repository (or any of the parent directories): .git

This error means you are not inside a Git repository. To fix it, change into the directory containing your repository (look for a .git folder) and run the commands again:

cd ~/projects/my-repository
git branch

fatal: a branch named ‘new-branch’ already exists

fatal: a branch named 'new-branch' already exists

Another branch already uses the name you want. You have three options:

• Choose a different new name
• Delete or rename the existing branch first
• Use git branch -M to force the rename and overwrite the existing branch

If you choose to force rename, first verify that overwriting the existing branch will not lose important work:

git log new-branch --oneline -5

error: pathspec ‘old-branch’ did not match any file(s) known to git

error: pathspec 'old-branch' did not match any file(s) known to git

This usually means the branch name is misspelled or the branch only exists on the remote (not locally). List all branches to find the correct name:

git branch -a

If the branch only exists on the remote, create a local tracking branch first:

git switch -c old-branch origin/old-branch

Then proceed with the rename.

There is no tracking information for the current branch

There is no tracking information for the current branch.
Please specify which branch you want to merge with.
See git-pull(1) for details.

    git pull <remote> <branch>

If you wish to set tracking information for this branch you can do so with:

    git branch --set-upstream-to=origin/<branch> new-branch

This message appears when your local branch is not tracking any remote branch. Set the upstream with one of these commands:

# Option 1: Push and set upstream in one step
git push -u origin new-branch

# Option 2: Set upstream without pushing
git branch --set-upstream-to=origin/new-branch new-branch

remote: error: refusing to delete the current branch

remote: error: refusing to delete the current branch: refs/heads/old-branch
To github.com:username/repository.git
 ! [remote rejected] old-branch (deletion of the current branch prohibited)
error: failed to push some refs to 'github.com:username/repository.git'

The remote repository has old-branch set as its default branch, and most hosting providers prohibit deleting the default branch. To fix this:

1. Push the new branch name first: git push -u origin new-branch
2. Log into your hosting provider (GitHub, GitLab, Bitbucket) and change the default branch to new-branch in repository settings
3. Update any branch protection rules to use the new name
4. Then delete the old branch: git push origin --delete old-branch

remote: Permission denied or authentication failed

remote: Permission to username/repository.git denied to your-username.
fatal: unable to access 'https://github.com/username/repository.git/': The requested URL returned error: 403

You do not have push access to the remote repository, or your credentials have expired. Check that:

• You are using the correct remote URL (your fork vs the upstream repository)
• Your SSH key is added to your account and loaded in your SSH agent
• Your personal access token or password has not expired (for HTTPS remotes)
• The branch is not protected with rules that restrict your access

Verify your remote URL with git remote -v and ensure you are pushing to a repository where you have write access.

Additional Considerations

After completing the branch rename, update any external references to the old branch name:

• Default branch changes: If you renamed the default branch (such as master to main), update your hosting provider’s default branch setting and any branch protection rules before deleting the old name.
• CI/CD pipelines: Update build triggers, deployment scripts, and workflow files that reference the old branch name. Check .github/workflows/, .gitlab-ci.yml, Jenkinsfile, and similar configuration files.
• Documentation and README files: Replace any references to the old branch in clone commands, badges, or build instructions.
• Multiple remotes or worktrees: If your remote is not named origin or you use multiple remotes, substitute the correct remote name in each command. Update each worktree separately if you use git worktree.

Conclusion

Renaming a Git branch follows a specific sequence: rename locally, push the new name with upstream tracking, delete the old remote name, and prune stale references. With these steps complete, both your local clone and the remote repository reflect the new branch name, and your team can update their clones to match.

For more Git workflow guides, see how to undo the last Git commit and commands to clear Git cache. For complete reference documentation, consult the official git-branch and git-push manual pages.