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

   Explain Code

   Powered by Vultr AgentBeta

   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

   Explain Code

   Powered by Vultr AgentBeta

3. Rename the branch using the -m option.

   CONSOLE

   Copy

   $ git branch -m feature-login

   Explain Code

   Powered by Vultr AgentBeta

   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

   Explain Code

   Powered by Vultr AgentBeta

   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

   Explain Code

   Powered by Vultr AgentBeta

   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

   Explain Code

   Powered by Vultr AgentBeta

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

   CONSOLE

   Copy

   $ git branch -m feature-mfa

   Explain Code

   Powered by Vultr AgentBeta

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

   Explain Code

   Powered by Vultr AgentBeta

   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

   Explain Code

   Powered by Vultr AgentBeta

   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

   Explain Code

   Powered by Vultr AgentBeta

   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

   Explain Code

   Powered by Vultr AgentBeta

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

   CONSOLE

   Copy

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

   Explain Code

   Powered by Vultr AgentBeta

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

   CONSOLE

   Copy

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

   Explain Code

   Powered by Vultr AgentBeta

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

   CONSOLE

   Copy

   $ git push -u origin new-branch-name

   Explain Code

   Powered by Vultr AgentBeta

5. Verify the change by listing remote branches.

   CONSOLE

   Copy

   $ git branch -r

   Explain Code

   Powered by Vultr AgentBeta

   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.