How to Rename Git Branch (Local & Remote) with Examples

Renaming branches is a common Git operation used when correcting naming mistakes, following team naming conventions, or migrating repositories from master to main. In this guide, you will learn how to rename Git branches locally and remotely, update upstream tracking, and rename branches on platforms such as GitHub and GitLab. The examples below demonstrate practical workflows using the git branch -m command to safely rename Git branches without affecting commit history.

Git Rename Branch Quick Cheat Sheet

Common Git branch rename commands

Local vs remote branch rename reference table

Renaming a branch locally does not automatically update the remote repository. The following table shows the common workflow used to rename a branch in both local and remote repositories.

Quick workflow to rename branch safely

The safest workflow to rename a Git branch locally and remotely is:

git branch -m new-branch-name
git push origin new-branch-name
git push origin --delete old-branch-name
git push -u origin new-branch-name

This ensures that the renamed branch exists on the remote repository and that your local branch is properly configured to track the remote branch.

Git Rename Branch Command Syntax

Rename current branch syntax

Git provides simple syntax for renaming branches using the git branch command. The -m option (move) renames the branch reference without affecting commit history.

If you are currently on the branch that you want to rename, you can run:

git branch -m <new-branch-name>

Example:

git branch -m feature-login

This command renames the currently active branch to feature-login.

Rename another branch syntax

If the branch you want to rename is not currently checked out, specify both the old and new branch names:

git branch -m <old-branch-name> <new-branch-name>

Example:

git branch -m test-branch feature-login

This renames the branch test-branch to feature-login without switching to it.

Important git branch options (-m vs -M)

The git branch command supports several options when renaming branches.

Example using force rename:

git branch -M new-branch-name

Use -M carefully because it will overwrite an existing branch with the same name.

Rename Current Git Branch

When working on a branch, you may realize that the branch name does not match the intended feature, bug fix, or development task. Git allows you to rename the active branch easily.

Check the current branch name

Before renaming the branch, confirm which branch is currently active.

git branch

Example output:

* test-branch
  main

The asterisk (*) indicates the current active branch.

You can also verify using:

git status

Example output:

On branch test-branch

Rename the active branch

To rename the current branch, run:

git branch -m feature-login

This changes the branch name from test-branch to feature-login.

Verify branch rename in repository

After renaming the branch, verify the update using:

git branch

Example output:

* feature-login
  main

The branch has now been successfully renamed in your local repository.

Rename Another Local Branch

Sometimes you may want to rename a branch that is not currently checked out. Git allows renaming any local branch by specifying both the old and new branch names.

List all branches in the repository

First check the list of available branches in the repository.

git branch

Example output:

main
feature-login
test-branch

Assume you want to rename test-branch.

Rename branch without switching

You can rename the branch directly without switching to it.

git branch -m test-branch feature-authentication

This command changes the branch name from test-branch to feature-authentication.

Confirm updated branch names

Verify the branch rename using:

git branch

Example output:

main
feature-login
feature-authentication

The branch name has now been successfully updated.

Rename Git Branch Locally and Remotely

Renaming a branch locally does not automatically rename it on the remote repository. You must push the renamed branch and remove the old branch from the remote.

Rename the branch locally

Rename the local branch first:

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

Example:

git branch -m feature-old feature-login

Push renamed branch to remote

Push the new branch name to the remote repository.

git push origin feature-login

Delete old remote branch

Remove the old branch reference from the remote repository.

git push origin --delete feature-old

Set upstream tracking branch

Set the upstream branch so future git push and git pull commands work correctly.

git push -u origin feature-login

Now the local branch tracks the remote branch with the new name.

Rename Remote Git Branch Only

Git does not provide a direct command to rename a remote branch. Instead, you create a new branch with the desired name and remove the old one.

Understanding how Git handles remote branch rename

In Git, remote branch renaming is essentially performed by:

1. Creating a new branch
2. Deleting the old branch

This ensures repository history remains unchanged.

Create a new remote branch with the new name

Push the renamed branch to the remote repository:

git push origin new-branch-name

Remove the old remote branch reference

Delete the old branch name from the remote repository.

git push origin --delete old-branch-name

After this step, the remote repository will only contain the renamed branch.

Rename Git Branch in GitHub

GitHub allows you to rename branches directly using the web interface. This is useful when managing repositories collaboratively.

Rename branch using GitHub UI

Steps:

1. Open the repository on GitHub
2. Navigate to the Branches section
3. Locate the branch you want to rename
4. Click the edit (pencil) icon
5. Enter the new branch name and confirm

GitHub automatically updates pull requests and references when branches are renamed through the UI.

Update local repository after GitHub rename

After renaming a branch in GitHub, update your local repository.

git fetch origin

Then rename your local branch:

git branch -m old-name new-name

Fix upstream tracking after GitHub rename

Update the upstream branch reference.

git branch -u origin/new-name

This ensures your local branch tracks the correct remote branch.

Rename Git Branch in GitLab

GitLab also allows branch renaming through its web interface, similar to GitHub.

Rename branch using GitLab web interface

Steps:

1. Open your project in GitLab
2. Navigate to Repository → Branches
3. Locate the branch you want to rename
4. Click the rename option
5. Enter the new branch name

GitLab updates merge requests referencing the renamed branch automatically.

Update local clone after GitLab branch rename

After renaming the branch in GitLab, fetch the latest updates.

git fetch origin

Rename your local branch:

git branch -m old-name new-name

Fix remote tracking references

Update upstream tracking so the branch follows the correct remote branch.

git branch -u origin/new-name

Rename Default Branch (master to main)

Many repositories have migrated from the master branch to main to follow modern naming conventions. Platforms such as GitHub and GitLab now use main as the default branch name to promote inclusive terminology and standardize repository structure.

Rename default branch locally

Switch to the master branch and rename it.

git checkout master
git branch -m master main

Update default branch on GitHub or GitLab

Push the new branch name to the remote repository.

git push -u origin main

After confirming everything works correctly, delete the old branch from the remote repository.

git push origin --delete master

You may also need to update the default branch setting in your Git hosting platform.

Rename Branch in Shared Repository

When working in a shared Git repository, renaming a branch requires coordination with other developers. Since multiple team members may have cloned the repository, changing the branch name can impact pull requests, local clones, and CI/CD workflows.

Notify team members about branch rename

If a branch is renamed, inform team members so they can update their local repositories.

Example notification:

Branch "feature-login" has been renamed to "feature-authentication"

Other developers should update their local branches using:

git fetch origin
git branch -m old-name new-name
git branch -u origin/new-name

Update pull requests referencing old branch

If the branch is used in open pull requests:

• Update the pull request source or target branch if needed
• Verify that the renamed branch still appears correctly
• Ensure reviewers are aware of the branch rename

Most platforms like GitHub and GitLab automatically update pull requests when a branch is renamed using their UI.

Update CI/CD pipelines referencing branch names

Some pipelines reference specific branch names directly.

Check pipeline configuration files such as:

• GitHub Actions workflows
• GitLab CI pipelines
• Jenkins pipelines

Example pipeline configuration:

branches:
  - feature-login

After renaming the branch, update the configuration:

branches:
  - feature-authentication

This ensures automation continues to run correctly.

Change Branch Upstream Tracking

After renaming a branch, the upstream tracking reference may need to be updated. Upstream branches allow Git to determine which remote branch should be used during git push or git pull.

Check upstream tracking configuration

Use the following command to view branch tracking information:

git branch -vv

Example output:

* feature-login 91c4b3a [origin/feature-login] Add login feature
  main          a34f2c1 [origin/main] Update README

The value inside brackets shows the remote branch being tracked.

Set new upstream branch after rename

If the upstream reference is broken or outdated, update it using:

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

Alternatively:

git branch -u origin/feature-login

Verify tracking configuration

Verify the upstream configuration again:

git branch -vv

The local branch should now correctly track the renamed remote branch.

Rename Branch After It Was Pushed

A common situation occurs when a branch has already been pushed to a remote repository but needs to be renamed afterward.

Rename branch that already exists on remote

First rename the branch locally:

git branch -m old-name new-name

Push the renamed branch to the remote repository:

git push origin new-name

Delete the old branch from the remote repository:

git push origin --delete old-name

Force rename when branch name already exists

If the new branch name already exists locally, Git may return an error:

fatal: A branch named 'new-name' already exists

To force rename the branch, use:

git branch -M new-name

Use this option carefully because it overwrites the existing branch reference.

Avoid breaking remote references

Before deleting the old branch:

• Ensure the renamed branch is pushed successfully
• Confirm CI/CD pipelines work correctly
• Check that pull requests are updated

This prevents disruption in collaborative environments.

Rename Branch With Uncommitted Changes

You can rename a branch even if you have uncommitted changes in your working directory.

Verify working directory before renaming

Check the repository status:

git status

Example output:

On branch feature-login
Changes not staged for commit:
  modified: login.js

Git allows renaming the branch without affecting these changes.

Rename branch safely without losing changes

Rename the branch as usual:

git branch -m feature-authentication

Verify the branch rename:

git branch

Your uncommitted changes will remain intact after renaming the branch.

Rename Branch Using Git Switch Workflow

The git switch command is commonly used to change branches, but branch renaming is still performed using git branch -m.

Switch to target branch

First switch to the branch you want to rename:

git switch feature-login

Rename branch using git branch -m

Rename the branch using the -m option:

git branch -m feature-authentication

Verify active branch

Confirm the rename using:

git branch

Example output:

* feature-authentication
  main

The branch name has now been updated successfully.

Summary

In this guide, we explored how to rename Git branches locally and remotely using different workflows and scenarios. Renaming branches is useful when correcting naming mistakes, adopting new naming conventions, or reorganizing development workflows.

The tutorial covered several important cases including renaming the current branch, renaming another local branch, updating remote branches, migrating from master to main, fixing upstream tracking, and handling branch renames in shared repositories.

Understanding these workflows ensures that Git branch renaming is performed safely without affecting commit history or breaking collaboration across teams and CI/CD pipelines.

Official Documentation

You can learn more about Git branch management and branch renaming from the official Git documentation:

• Git Branch Documentation
• Git Switch Documentation
• Git Checkout Documentation