How to Rename an Existing Branch in Git?

Renaming a branch in Git can be necessary when you need to update branch names to reflect changes in project requirements, correct typos, or align with new naming conventions.

This blog walks you through the process of renaming a branch locally and on a remote repository.

Why Rename a Git Branch?

Renaming branches can help:

• Improve clarity and readability of branch names.
• Reflect changes in project scope or purpose.
• Fix typos or outdated naming conventions.

For example, renaming feature-login to feature-authentication provides a clearer description of the branch’s purpose.

---

Prerequisites

Before renaming a branch:

1. Ensure you have Git installed and configured on your system.
2. Navigate to the repository containing the branch you want to rename.
3. Ensure your local repository is up to date with the remote using:

   git fetch

---

Step 1: Rename a Local Branch

1.1 Renaming the Current Branch

If you are on the branch you want to rename:

1. Use the following command to rename it:

   git branch -m new-branch-name

For example:

   git branch -m feature-authentication

The -m option stands for “move” and renames the branch without changing its history.

---

1.2 Renaming Another Branch

If the branch you want to rename is not currently checked out:

1. Switch to any other branch:

   git checkout main

2. Rename the target branch:

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

For example:

   git branch -m feature-login feature-authentication

---

Step 2: Push the Renamed Branch to Remote

Renaming a branch locally does not automatically update the branch name on the remote repository. You must explicitly push the new branch name and delete the old one.

2.1 Push the New Branch Name

Push the renamed branch to the remote repository:

git push origin new-branch-name

For example:

git push origin feature-authentication

---

2.2 Delete the Old Branch Name

After pushing the new branch, delete the old branch from the remote repository to avoid confusion:

git push origin --delete old-branch-name

For example:

git push origin --delete feature-login

---

Step 3: Update Branch Tracking

If the renamed branch is set to track a remote branch, you’ll need to update its tracking configuration.

1. Set the upstream branch for the new branch name:

   git branch --set-upstream-to=origin/new-branch-name

For example:

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

2. Verify the tracking configuration:

   git status

---

Common Scenarios and Solutions

1. Renaming a Protected Branch (e.g., main)

If you’re renaming a protected branch like main, ensure you have administrative rights for the remote repository. Update any workflows, CI/CD pipelines, or collaborators relying on the branch name.

After renaming:

• Notify your team about the change.
• Update default branch settings in GitHub or GitLab.

---

2. Collaborators Using the Old Branch

Inform your team members about the renaming. They need to fetch the changes and update their local branches:

1. Fetch the updated branch list:

   git fetch origin

2. Check out the renamed branch:

   git checkout new-branch-name

3. Delete the old branch locally:

   git branch -d old-branch-name

---

3. Verifying the Branch Rename

To ensure the renaming was successful:

• List all local branches:

  git branch

• List all remote branches:

  git branch -r

Verify that the old branch name no longer appears in the list.

---

Conclusion

Renaming a Git branch is a straightforward process that can help improve organization and clarity in your version control workflow. By following the steps outlined above, you can seamlessly rename branches locally and remotely while ensuring collaborators remain in sync with the changes. Clear communication with your team and updating relevant workflows will ensure a smooth transition.