How to Rename a Git Branch (Local and Remote)
To rename a Git branch, run git branch -m old-name new-name. If you are already on the branch, git branch -m new-name is enough. That only renames your local copy; to rename the branch on GitHub, GitLab or any other remote, push the new name with git push origin -u new-name and delete the old one with git push origin --delete old-name.
Git has no single "rename remote branch" command, because a remote branch is just a ref on another server. Renaming it always means creating the new name and removing the old one. The rest of this guide walks through each case and the clean-up that people usually forget: the upstream that still points at the old name, teammates' clones, and the default branch. Every git command below was run with Git 2.54 against a local bare repository acting as the remote.
Rename a local branch
The branch you are on
git branch -m new-name-m stands for move. Git renames the branch and its reflog, so your history and git reflog entries come along.
Any other branch
git branch -m old-name new-nameYou do not need to switch to the branch first. Slashes are fine, so git branch -m feature/login feature/auth-login works the same way.
When the new name already exists
Git refuses to overwrite an existing branch:
fatal: a branch named 'main' already existsgit branch -M old-name new-name (capital M) forces the rename and throws away the branch that had the new name. Only use it when you are sure that other branch is not needed.
Case-only renames on macOS and Windows
On case-insensitive file systems (the default on macOS and Windows), a rename that only changes capitalisation can fail with the same "already exists" error, because Git stores loose branch refs as files and fix-bug and Fix-Bug look like the same file. Use the force flag for case-only renames:
git branch -M fix-bug Fix-BugTo avoid the problem entirely, stick to lowercase branch names. The same idea applies to files: a consistent naming convention saves you from case collisions later.
Rename the branch on the remote
After a local rename, the remote still has the old branch, and your local branch is still tracking it. You can see that with git branch -vv:
* feature/auth-login 73df83c [origin/feature/login] fFix it in three steps.
- Push the new name and set it as the upstream:
git push origin -u new-name - Delete the old branch on the remote:
git push origin --delete old-name - Check the result with
git branch -vv; the brackets should now showorigin/new-name.
Put together, a full local-and-remote rename of the branch you are on looks like this:
git branch -m new-name
git push origin -u new-name
git push origin --delete old-nameThe -u (--set-upstream) flag matters. Without it, git pull and git push keep trying to use the old remote branch, and once you delete it, git status reports the upstream as gone.
git push origin :old-name is an older way of writing the delete. It does the same thing, but --delete is easier to read.
If the old branch has an open pull request
A pull request is tied to its branch names. If the renamed branch is the head (source) of an open pull request, deleting the old remote branch closes that PR on GitHub, and GitHub's own rename button closes it too. Plan to open a new PR from the new branch, or wait until the PR is merged before renaming. If the branch is the base (target) of open PRs, rename it through GitHub's web interface instead (covered below), which retargets those PRs automatically.
Update other clones after a rename
Everyone else who checked out the branch still has the old name locally, tracking a remote branch that no longer exists. Each teammate runs:
git fetch origin --prune
git branch -m old-name new-name
git branch -u origin/new-name new-name--prune removes the stale origin/old-name reference. Before they run the last two commands, git branch -vv shows the problem clearly:
* old-name 2666627 [origin/old-name: gone] initAfter them, the branch tracks origin/new-name and pull and push work again.
Rename a branch on GitHub
GitHub can rename a branch on the server for you, which is the better choice when other pull requests target the branch:
- Open the repository on GitHub.
- Open the branch dropdown in the file tree view and click View all branches.
- Next to the branch, open the more-options menu (the three dots) and click Rename branch.
- Type the new name and click Rename branch.
According to GitHub's documentation, renaming a branch this way also retargets open pull requests that use it as their base, updates draft releases and branch protection rules, and redirects web URLs that contain the old branch name. An open pull request whose head is the renamed branch is closed. The rename does not redirect raw file URLs or git pull of the old name, and GitHub Actions workflows that reference the old branch name do not follow the rename.
You need write access to rename most branches. Renaming the default branch, or a branch covered by branch protection or a repository ruleset, needs admin access.
If you prefer the terminal, the GitHub CLI can call the same rename endpoint:
gh api -X POST repos/OWNER/REPO/branches/old-name/rename -f new_name=new-nameThen update your own clone with the commands from the next section.
Rename the default branch (master to main)
Renaming the default branch is the case where the GitHub web UI really helps, because a manual push-and-delete breaks open pull requests and forces you to change the default branch setting yourself. Rename master (or whatever your default is) with the Rename branch steps above. GitHub then shows contributors a notice on the repository home page with the commands to update their clones, which are:
git branch -m master main
git fetch origin
git branch -u origin/main main
git remote set-head origin -aThe last command updates origin/HEAD, your clone's record of which branch is the remote's default. Optionally run git remote prune origin to remove the stale tracking ref.
After the rename, search your project for the old name: CI workflow triggers such as on: push: branches: [master], deploy scripts, badges, documentation links and any tool configured to watch a branch.
For new repositories, you can choose the starting branch name up front:
git init -b main
git config --global init.defaultBranch mainRename a branch on GitLab
GitLab's web interface has no rename button for branches, so you do it from the command line:
- Rename locally with
git branch -m old-name new-name. - Push the new name with
git push origin -u new-name. - If the old branch was the default, go to Settings > Repository, expand Branch defaults, pick the new branch and click Save changes. This needs the Maintainer or Owner role.
- If the old branch is protected, protect the new one and remove protection from the old one, otherwise the delete in the next step fails.
- Delete the old branch with
git push origin --delete old-name. - Retarget any open merge requests that pointed at the old branch.
GitLab's documentation for renaming a default branch follows the same order and adds one useful detail: GitLab remembers the previous default branch name, so file and directory links that used it redirect to the current default branch after the old branch is deleted.
Quick reference
| Task | Command |
|---|---|
| Rename the current branch | git branch -m new-name |
| Rename another branch | git branch -m old-name new-name |
| Force a rename (overwrites, case-only) | git branch -M old-name new-name |
| Push the new name and track it | git push origin -u new-name |
| Delete the old remote branch | git push origin --delete old-name |
| Fix tracking after someone else renamed | git fetch origin --prune then git branch -u origin/new-name |
| Refresh the remote default branch | git remote set-head origin -a |
Renaming a whole repository rather than a branch is a separate job; see how to rename a GitHub repository. If what you actually need is to rename files inside the repository, use git mv old new so Git records the rename, or see how to rename a file for every operating system.
Frequently Asked Questions
How do I rename a local Git branch?
Run git branch -m old-name new-name from anywhere in the repository, or git branch -m new-name if you are currently on that branch. This renames only your local copy; the remote branch and any upstream tracking stay unchanged until you push.
How do I rename a remote branch in Git?
Git cannot rename a branch on a remote directly. Rename it locally, push the new name with git push origin -u new-name, then delete the old one with git push origin --delete old-name. On GitHub you can also rename it in the web interface from the branches page, which retargets pull requests that use it as their base.
Does renaming a branch lose commits or history?
No. A branch is a pointer to a commit, and git branch -m moves that pointer to a new name together with its reflog. All commits stay exactly as they were. Deleting the old remote branch also loses nothing as long as the new branch was pushed first.
Why does git branch -m say the branch already exists?
Either a branch with the new name really exists, or you are changing only the capitalisation on a case-insensitive file system such as macOS or Windows. Use git branch -M to force the rename, but be aware it overwrites any existing branch with that name.
What should teammates do after a branch is renamed?
They should run git fetch origin --prune, rename their local branch with git branch -m old-name new-name, and point it at the new remote branch with git branch -u origin/new-name new-name. For a renamed default branch, git remote set-head origin -a also updates origin/HEAD.
Can I rename the main or master branch?
Yes. On GitHub, use Rename branch on the branches page; it updates the default branch, pull request bases and branch protection. On GitLab, push the renamed branch, change the default in Settings > Repository > Branch defaults, then delete the old branch. Afterwards, update CI and deploy configuration that names the old branch.
Related Posts
How to Rename a GitHub Repository (and What Breaks)
Rename a GitHub repository in Settings > General, then update your local remote with git remote set-url. What redirects, and what breaks: Pages and Actions.
AdvancedHow to Rename Columns in pandas (df.rename and 6 Other Ways)
Rename columns in pandas with df.rename(columns={...}), replace all names with df.columns, clean names with str methods, and avoid silent KeyErrors and inplace.
AdvancedHow to Rename a Column in SQL (PostgreSQL, MySQL, SQL Server, SQLite, Oracle)
Rename a column in SQL with ALTER TABLE ... RENAME COLUMN, or sp_rename in SQL Server. Exact syntax for every major database, plus what breaks in views.
Ready to organize your files?
Try AI renaming right away. No sign-up needed until you download.
Try It Free