How to Rename a Branch in Git?

Renaming a branch in Git is a common task when working on collaborative projects or refactoring codebases. Whether you’re renaming a local branch or a remote branch on GitHub, GitLab, or other repositories, Git provides simple and flexible ways to do so.

In this blog, we’ll cover why you might want to rename a branch, followed by detailed instructions on how to rename both local and remote branches.

Why Rename a Branch in Git?

There are several reasons you might need to rename a Git branch:

• Consistency: To maintain a consistent naming convention across all branches.
• Clarity: A descriptive branch name (like feature/user-auth) helps convey its purpose and content more effectively.
• Project Evolution: As projects evolve, branch names sometimes need to change to reflect new features or reorganized code.
• Inclusive Language: For example, renaming the master branch to main has become a common practice to promote more inclusive language.

Step 1: Check the Current Branch

Before renaming, confirm the name of the branch you’re currently on, especially if you want to rename your current branch.

git branch

The output will show a list of branches, with the current branch marked by an asterisk (*). Ensure you’re on the branch you intend to rename.

Step 2: Renaming a Local Branch

There are two scenarios for renaming a branch locally: renaming the branch you’re currently on or renaming a different branch.

Renaming the Current Branch

If you want to rename the branch you’re currently working on:

git branch -m new-branch-name

Here:

• -m stands for “move,” which renames the branch.
• new-branch-name is the name you want to give the branch.

Renaming a Different Local Branch

To rename a branch that you’re not currently on, use the following command:

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

In this command:

• old-branch-name is the name of the branch you want to rename.
• new-branch-name is the new name for the branch.

After running this command, verify the change by listing all branches:

git branch

Step 3: Pushing the Renamed Branch to a Remote Repository

Once you’ve renamed a local branch, you may need to push this change to a remote repository, such as GitHub or GitLab.

1. Delete the Old Branch on the Remote Repository (Optional):
   If the remote branch already exists with the old name, delete it to prevent confusion.

   git push origin --delete old-branch-name

This command deletes the old-branch-name branch on the remote repository (origin is the default name for the remote repository).

2. Push the Renamed Branch to the Remote Repository:

   git push origin new-branch-name

Here, new-branch-name is the name of the branch you just renamed. This command pushes the renamed branch to the remote repository.

3. Set the Upstream Tracking Branch: After pushing, set the upstream branch so future commands like git pull and git push work without specifying the branch name each time:

   git push --set-upstream origin new-branch-name

This command links the local branch new-branch-name with the remote branch new-branch-name.

Step 4: Inform Collaborators (If Applicable)

If you’re working on a shared project, make sure to notify your collaborators about the branch name change. They’ll need to fetch the updated branch names on their local repositories.

Collaborators can fetch and delete the old branch with the following commands:

git fetch --prune
git branch -d old-branch-name  # For branches that have been removed from the remote

Step 5: Deleting the Old Branch Locally (Optional)

After successfully renaming and pushing the new branch to the remote, you can delete the old branch from your local repository (if it still exists) with:

git branch -d old-branch-name

Use -D (uppercase D) instead of -d to force-delete a branch that hasn’t been fully merged, but exercise caution to avoid losing important changes.

Example Workflow: Renaming master to main

Here’s an example of renaming the default master branch to main:

1. Switch to the master branch:

   git checkout master

2. Rename the branch:

   git branch -m main

3. Push the new main branch to the remote:

   git push origin main

4. Set the upstream tracking for main:

   git push --set-upstream origin main

5. Optionally, delete the old master branch from the remote:

   git push origin --delete master

6. On GitHub, set main as the default branch in your repository settings, and delete master if no longer needed.

Troubleshooting Common Issues

• Error: Could not rename branch: Make sure you’re not on the branch you’re trying to rename, or use git branch -m to rename the current branch.
• Branch deletion fails: Ensure the branch is fully merged before deleting, or use -D to force-delete.
• Conflicting Upstream Branch: Use --set-upstream to establish a new tracking relationship between the renamed local branch and the remote branch.

Final Thoughts

Renaming a branch in Git is straightforward and helps maintain clear, consistent, and descriptive branch names as projects evolve. By following these steps, you can rename local and remote branches effectively, enhancing collaboration and organization within your repositories.