How to Rename a Local and Remote Git Branch

A bad branch name follows you everywhere: pull requests, CI logs, review comments, and release notes. When you need to rename a local and remote Git branch, the safe path is still simple: rename it locally, push the new name, delete the old remote ref, and prune stale tracking data. That is enough for typo fixes, better feature names, and the usual master-to-main cleanup without touching commit history.

Git itself only renames the local branch. There is no hidden “rename remote branch” command waiting behind another flag, so the remote side changes only after you push the replacement ref and remove the old one. The sections below show the exact commands, the output worth checking, and the cleanup other clones need after the rename.

Protected branches, default branch settings, and open pull requests can change the safest rename path. GitHub documents a branch rename flow in the web UI, while Bitbucket Cloud documents the rename as local Git commands plus a repository-settings cleanup. Either way, existing clones still need to fetch and prune after the remote name changes.

Understand the Git Branch Rename Workflow

To rename a local and remote Git branch, rename the branch in your clone, push the new branch name to the remote, delete the old remote ref, and prune stale references in any clone that still remembers the old name. Here is the full workflow with a realistic branch rename:

git branch -m feature/login-screen feature/oauth-login
git push -u origin feature/oauth-login
git push origin --delete feature/login-screen
git fetch --prune origin

Git Branch Rename Syntax

The git branch -m command renames a local branch and keeps its reflog. Use the lowercase -m flag for a normal rename and the uppercase -M flag only when you intentionally want to overwrite an existing target branch name.

git branch -m new-branch
git branch -m old-branch new-branch
git branch -M old-branch new-branch

If you want the exact option reference, the official git-branch manual page and git-push manual page spell out the rename, upstream, and delete flags used throughout this guide.

Git Branch Rename Quick Reference

Task	Command	What It Does
Check the current branch name	git branch --show-current	Prints only the branch you currently have checked out.
Rename the current local branch	git branch -m feature/oauth-login	Renames the branch you are already on.
Rename a different local branch	git branch -m feature/login-screen feature/oauth-login	Renames another local branch without switching to it.
Push the renamed branch	git push -u origin feature/oauth-login	Creates the new remote branch and sets upstream tracking.
Delete the old remote ref	git push origin --delete feature/login-screen	Removes the outdated branch ref from the remote.
Prune stale remote refs	git fetch --prune origin	Cleans cached tracking names that no longer exist on the remote.

Install Git If the Git Command Is Missing

Git already ships with many developer-focused systems, but minimal servers, stripped-down containers, and fresh desktop installs can still return git: command not found. If that happens, install Git with the package manager your distro already uses, then rerun the version check.

Install Git on Debian and Ubuntu

sudo apt update && sudo apt install git

Install Git on Fedora, RHEL, Rocky Linux, and AlmaLinux

sudo dnf install git

Install Git on Arch Linux

sudo pacman -S git

Install Git on openSUSE

sudo zypper install git

Verify that the Git command is now available:

git --version

git version 2.x.x

If you want a distro-specific walkthrough or a newer packaged Git build, use the guides to Install Git on Ubuntu, Install Git on Debian, Install Git on Fedora, Install Git on Linux Mint, Install Git on Arch Linux, or Install Git on Rocky Linux.

Rename a Local Git Branch

Start by confirming the branch you want to rename and the remote that branch eventually pushes to. That removes guesswork before you change the local name.

Check the Current Git Branch and Remote

If you only need the current branch name, git branch --show-current is the cleanest check.

git branch --show-current

feature/login-screen

Then confirm the remote you plan to update. Most repositories use origin, but forks and multi-remote workflows often use names such as upstream or company.

git remote -v

origin  git@github.com:example/project.git (fetch)
origin  git@github.com:example/project.git (push)

If your remote uses HTTPS instead of SSH, the branch rename commands stay the same. Only the authentication prompt changes.

Rename the Current Git Branch

If you are already on the branch you want to rename, pass only the new branch name to git branch -m.

git branch -m feature/oauth-login

The rename succeeds silently. Verify the local result with git branch -vv.

git branch -vv

* feature/oauth-login 0a41636 [origin/feature/login-screen] Add OAuth callback handler

The local rename is complete, but the upstream still points at origin/feature/login-screen. That old upstream name is normal until you push the renamed branch to the remote.

Rename a Different Local Git Branch Without Switching

If you want to stay on your current branch and rename another one, provide both the old and new branch names.

git branch -m feature/login-screen feature/oauth-login

This is useful when you are on main but need to clean up a feature branch name before opening a pull request or asking a teammate to review it.

Force a Git Branch Rename When the Target Name Exists

If the new branch name already exists locally, Git refuses the rename and prints an error.

fatal: a branch named 'feature/oauth-login' already exists

The next command overwrites the branch that already owns the target name. Compare both branches first so you do not hide commits that only exist on the current feature/oauth-login branch.

Preview the recent history on both branches before forcing the rename:

git log --oneline --decorate --graph --max-count=5 feature/login-screen feature/oauth-login

If the overwrite is intentional, use the uppercase -M flag.

git branch -M feature/login-screen feature/oauth-login

Rename a Local and Remote Git Branch

Local renames only update your clone. To rename a local and remote Git branch, you still need to publish the new branch name to the remote, remove the old remote name, and prune stale tracking references.

Deleting the old remote ref affects everyone using that remote. Before you run the delete command, update default branch settings, branch protection rules, CI triggers, and open pull requests that still reference the old name.

Push the Renamed Git Branch and Set Upstream

Push the new branch name with -u so your local branch starts tracking the renamed remote branch immediately.

git push -u origin feature/oauth-login

To github.com:example/project.git
 * [new branch]      feature/oauth-login -> feature/oauth-login
branch 'feature/oauth-login' set up to track 'origin/feature/oauth-login'.

Verify the upstream target again after the push:

git branch -vv

* feature/oauth-login 0a41636 [origin/feature/oauth-login] Add OAuth callback handler

Delete the Old Remote Git Branch Name

Once the new remote branch exists and upstream tracking points to it, delete the old remote ref.

git push origin --delete feature/login-screen

To github.com:example/project.git
 - [deleted]         feature/login-screen

The --delete flag removes the old ref from the remote. It does not delete your local branch, and it does not rewrite commits that are still reachable through the renamed branch.

Prune Stale Remote-Tracking Git Branches

Every existing clone can cache the old remote-tracking branch name until it prunes stale refs. In the clone that performed the rename, git fetch --prune origin may print nothing because its tracking data is already current. Other clones usually see output like this:

git fetch --prune origin

From github.com:example/project
 - [deleted]         (none)     -> origin/feature/login-screen
 * [new branch]      feature/oauth-login -> origin/feature/oauth-login

That output confirms Git dropped the stale remote-tracking name and discovered the new one. Pruning only cleans your local tracking data; it does not delete anything else on the server.

Verify the Git Branch Rename on the Remote

If you want a direct remote-side check, list only remote heads. The old branch name should be gone.

git ls-remote --heads origin

0a41636a89df09093c2af66f7b86dd86fb4158cb	refs/heads/feature/oauth-login

For a local verification pass, list both local and remote-tracking branches. The old name should be gone from both views.

git branch -a

* feature/oauth-login
  main
  remotes/origin/HEAD -> origin/main
  remotes/origin/feature/oauth-login
  remotes/origin/main

Handle Advanced Git Branch Rename Workflows

Most of the time you are done once the remote ref is cleaned up. The extra work starts when the branch is default, protected, or already checked out in someone else’s clone.

Update Other Clones After a Git Branch Rename

If another clone still has the old branch checked out, fetch the remote changes, rename the local branch, and point it at the new upstream branch.

git fetch --prune origin
git branch -m feature/login-screen feature/oauth-login
git branch --set-upstream-to=origin/feature/oauth-login feature/oauth-login

branch 'feature/oauth-login' set up to track 'origin/feature/oauth-login'.

If the old local branch is no longer needed and the clone never had local work on it, creating a fresh tracking branch is also fine.

git fetch --prune origin
git switch -c feature/oauth-login --track origin/feature/oauth-login

Rename the Default Git Branch from master to main

The command sequence is the same for a default branch rename, but hosting-provider settings matter more because many remotes refuse to delete the current default branch.

git branch -m master main
git push -u origin main

Before deleting master, change the repository default branch in GitHub, GitLab, or Bitbucket, then update branch protection rules, deployment jobs, and documentation that still references the old branch name.

git push origin --delete master

Rename a Git Branch When the Remote Is Not origin

The commands do not change when the remote has a different name. Replace origin with the actual remote shown by git remote -v.

git push -u upstream feature/oauth-login
git push upstream --delete feature/login-screen
git fetch --prune upstream

Troubleshoot Common Git Branch Rename Errors

Git Says You Are Not in a Repository

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

This happens when you run the rename commands outside the repository directory. Move into the correct project first, then verify Git sees the repository root.

cd ~/projects/example-repo
git rev-parse --show-toplevel

/home/josh/projects/example-repo

If Git prints the repository path, rerun the branch rename commands from there.

Git Says the New Branch Name Already Exists

fatal: a branch named 'feature/oauth-login' already exists

The target name is already taken by another local branch. First confirm that branch really is the one you want to replace.

git branch --list "feature/oauth-login"

  feature/oauth-login

If the rename should overwrite that branch name, rerun the command with -M. Otherwise, choose a different new branch name.

git branch -M feature/login-screen feature/oauth-login

Git Cannot Find the Branch Name You Want to Rename

fatal: no branch named 'feature/login-screen'

This usually means the branch name is misspelled or the branch only exists as a remote-tracking ref in your clone. List every local and remote-tracking branch first so you can see what Git actually knows about.

git branch -a

  main
  remotes/origin/feature/login-screen
  remotes/origin/main

If the branch exists only on the remote, create a local tracking branch first and then rename it.

git switch -c feature/login-screen --track origin/feature/login-screen
git branch -m feature/oauth-login

Git Says 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/feature/oauth-login feature/oauth-login

This appears when the renamed local branch is not tracking any remote branch yet. Point the branch at the renamed upstream branch, then verify the tracking relationship.

git branch --set-upstream-to=origin/feature/oauth-login feature/oauth-login
git branch -vv

branch 'feature/oauth-login' set up to track 'origin/feature/oauth-login'.
* feature/oauth-login 0a41636 [origin/feature/oauth-login] Add OAuth callback handler

Git Refuses to Delete the Current Remote Branch

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

The remote still treats the old branch as its default branch. Push the new branch first, change the default branch in your hosting provider, update any protection rules, and then retry the delete command.

git push -u origin main
git push origin --delete master

Verify the remote now exposes only the new default branch name.

git ls-remote --heads origin

0a41636a89df09093c2af66f7b86dd86fb4158cb	refs/heads/main

Git Reports Permission Denied or Authentication Failed

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

This usually means you are pushing to the wrong remote, your SSH key is not loaded, or your HTTPS credentials no longer have write access. Confirm the remote URL first, then refresh the credential method that remote uses.

git remote -v

origin  git@github.com:example/project.git (fetch)
origin  git@github.com:example/project.git (push)

After you fix the permission issue, retry the push and confirm Git sets the upstream branch normally.

git push -u origin feature/oauth-login

Frequently Asked Questions About Git Branch Renames

Git Branch Rename Conclusion

Once you remember the sequence, rename locally, push the new ref, delete the old one, and prune stale tracking names, the job becomes boring in the best way. The history does not move; only the branch label does. If you are cleaning up related Git mistakes next, see undo the last Git commit or clear Git cache.