How to Rename a Branch in Git

Git is an open-source distributed version control system that helps developers track changes, manage code history, and work together efficiently. One of Git's core features is branching, which allows you to create isolated environments for new features, bug fixes, or experiments without impacting the main codebase. As development progresses, it's common to rename branches to reflect updated feature scopes or to follow consistent naming conventions. For instance, changing a branch name from bugfix/login to fix/login-auth can improve clarity and project organization.

This article explains how to rename a Git branch locally and remotely, including how to do it without performing a git checkout.

The Short Answer Version

If you're familiar with Git and just need quick reference commands:

# Rename the current branch
$ git branch -m <new_branch_name>

# Rename a different local branch
$ git branch -m <old_branch_name> <new_branch_name>

# Push the new branch and delete the old one from remote
$ git push origin :<old_branch_name> <new_branch_name>

# Set the upstream tracking for the renamed branch
$ git push --set-upstream origin <new_branch_name>

Rename a Local Git Branch

A local Git branch exists only on your system and is not shared with any remote repository. Renaming a local branch improves clarity, maintains naming consistency, and aligns with updated naming conventions as a project evolves.

Command Syntax (Local)

The basic syntax for renaming a local branch is:

git branch [OPTIONS] [BRANCH NAMES]

In the above command syntax:

• git branch: Manages branch operations
• [OPTIONS]:
  • -m: Renames the branch. Fails if <new_branch_name> already exists. Safe mode to prevent accidental overwrites.
  • -M: Force renames the branch even if <new_branch_name> already exists. Overwrites the existing branch name without prompting.
• [BRANCH NAMES]: Specifies the existing and/or new branch names involved in the rename operation.

Command Demonstration (Local)

Follow the steps below to rename a local Git branch:

1. Run the following command inside a Git-initialized directory to list all the local branches.

   console Copy

   $ git branch
   

   Your output should be similar to the one below:

     feature-auth
     feature-2fa
   * main

   The asterisk * marks the active branch in your repository.

2. Switch to the branch you want to rename.

   console Copy

   $ git checkout feature-auth
   

3. Rename the branch using the -m option.

   console Copy

   $ git branch -m feature-login
   

   This renames feature-auth to feature-login. The -m flag stands for "move" and will fail if the new name already exists.

4. Verify that the branch has been renamed.

   console Copy

   $ git branch
   

   Your output should be similar to the one below:

   * feature-login
     feature-2fa
     main

Rename a Remote Git branch

A remote Git branch refers to a branch hosted on a remote repository such as GitHub. Git does not allow direct renaming of remote branches. Instead, you must rename the branch locally, push the new branch to the remote, and delete the old one.

Command Syntax (Remote)

The syntax for renaming a remote branch is:

git push [REMOTE] :[OLD BRANCH NAME] [NEW BRANCH NAME]

In the above command syntax:

• git push: Pushes changes to a remote repository.
• [REMOTE]: The name of the remote repository (commonly origin).
• :[OLD BRANCH NAME]: Deletes the old branch name from the remote.
• [NEW BRANCH NAME]: Pushes the renamed local branch to the remote.

Command Demonstration (Remote)

Follow the steps below to rename a remote Git branch.

1. Run the following command to list all the local branches.

   console Copy

   $ git branch
   

   Your output should be similar to the one below:

   * feature-login
     feature-2fa
     main

   The asterisk * marks the active branch is feature-2fa.

2. Switch to the branch you want to rename.

   console Copy

   $ git checkout feature-2fa
   

3. Rename the local branch using the -m flag.

   console Copy

   $ git branch -m feature-mfa
   

4. Push the renamed branch to the remote and delete the old branch using the below command.

   console Copy

   $ git push origin :feature-2fa feature-mfa
   

   This pushes the feature-mfa and deletes the feature-2fa from the remote repository.

5. Set the upstream for the renamed local branch.

   console Copy

   $ git push -u origin feature-mfa
   

   The -u flag sets the upstream tracking branch so future git push and git pull commands will default to origin/feature-mfa.

6. Verify that the branch was renamed on the remote.

   console Copy

   $ git branch -r
   

   This lists all remote branches. The feature-2fa should be gone, and feature-mfa should appear.

Rename a Git Branch Without Git Checkout

You can rename a local Git branch directly without switching to it with git branch -m, which is useful for renaming branches other than the one actively checked out.

Command Syntax

The syntax for renaming a local branch without using git checkout is:

git branch -m [OLD BRANCH NAME] [NEW BRANCH NAME]

In the above command syntax:

• git branch: Manages branch operations.
• -m: Renames the branch. Fails if the new name already exists.
• [OLD BRANCH NAME]: The name of the branch to rename.
• [NEW BRANCH NAME]: The desired new name for the branch.

Command Demonstration

Follow the steps below to rename a local Git branch without switching to it.

1. Run the following command to list all the local branches.

   console Copy

   $ git branch
   

2. Run the following command to rename the target branch.

   console Copy

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

3. Push the renamed branch to the remote and delete the old one.

   console Copy

   $ git push origin :old-branch-name new-branch-name
   

4. Set the upstream tracking reference for the new branch.

   console Copy

   $ git push -u origin new-branch-name
   

5. Verify the change by listing remote branches.

   console Copy

   $ git branch -r
   

   The old branch name should no longer appear in the list, and the new one should be present.

Conclusion

You have successfully renamed Git branches locally and remotely using safe, structured commands. Whether renaming your active branch or another without switching, you applied the correct syntax to update branch names cleanly. On the remote side, you pushed renamed branches, removed outdated references, and set upstream tracking to keep synchronization. These steps ensured better project clarity, consistent naming, and a more maintainable Git workflow. For more information on git branches, visit the official Git documentation.