Introduction

Renaming a Git branch is simple locally, but if the branch also exists on a remote, you need to update both your local name and the remote tracking setup. The exact commands depend on whether you are currently on that branch and whether other people already use it.

Rename the Local Branch

If you are currently checked out on the branch you want to rename, use:

git branch -m new-branch-name

Example:

git switch feature/old-name
git branch -m feature/better-name

If you are not currently on that branch, provide both the old and new names:

git branch -m old-branch-name new-branch-name

This changes only the local branch name. Nothing has happened on the remote yet.

Update the Remote Branch Name

Git does not have a true “rename remote branch” command. The normal process is:

1. push the new branch name
2. delete the old remote branch name
3. set upstream tracking for the renamed local branch

Example:

git push origin -u feature/better-name
git push origin --delete feature/old-name

The first command creates the new remote branch and sets it as the upstream branch for the current local branch. The second command removes the old remote branch name.

A Full Example

Suppose you accidentally created feature/login-pagee and want feature/login-page.

1git switch feature/login-pagee
2git branch -m feature/login-page
3git push origin -u feature/login-page
4git push origin --delete feature/login-pagee

After that, your local branch is renamed, the remote has the corrected name, and your local branch tracks the new remote branch.

What Teammates Need to Do

If other people already fetched the old branch name, they need to update their local setup. A common sequence is:

1git fetch origin --prune
2git branch -m feature/old-name feature/better-name
3git branch --unset-upstream
4git branch -u origin/feature/better-name

Sometimes it is simpler for teammates to delete the old local branch and check out the new remote branch again, especially if they do not have local-only commits.

Renaming the Default Branch

If the branch is the repository’s default branch, there is one extra step outside Git itself: update the default branch setting in your hosting platform, such as GitHub, GitLab, or Bitbucket.

A typical flow is:

1. rename locally
2. push the new branch
3. change the default branch in the hosting UI
4. delete the old branch after confirming integrations are updated

This matters because pull requests, CI settings, protected branch rules, and deployment jobs may still point at the old default branch name.

Check Tracking After the Rename

To confirm the local branch tracks the right remote branch:

git branch -vv

That command shows your local branches and their upstream mappings. It is a good sanity check after any rename.

What Not to Do

A common misconception is that renaming the local branch automatically renames the remote branch. It does not. The remote still has the old name until you push the new one and remove the old one.

Another mistake is deleting the old remote branch before pushing the new one. That can make recovery annoying, especially if the branch name is shared across a team.

Also be careful with open pull requests. Some hosting platforms handle branch renames gracefully, but not every workflow, script, or CI job updates automatically.

Common Pitfalls

The biggest pitfall is forgetting the upstream tracking setup. After a local rename, git push may fail or target the wrong remote branch until you set the new upstream correctly.

Another issue is stale references on other machines. Teammates may keep seeing the old branch until they fetch with pruning or manually clean up references.

People also often rename a branch on the remote hosting UI and forget that their local clone still has the old name. Git on your machine does not automatically mirror that rename.

Finally, if the renamed branch is protected or used by CI, review repository settings after the change. The Git commands may succeed while the surrounding tooling still points at the old name.

Summary

• Use git branch -m to rename the local branch.
• Push the new branch name and delete the old remote name to complete the rename remotely.
• Set or verify upstream tracking after the change.
• Coordinate with teammates if the branch was already shared.
• Renaming a default branch also requires updates in the remote hosting platform and CI configuration.