git: how to rename a branch (both local and remote)?

How to Rename a Git Branch (Local and Remote)

Learn the essential Git commands to safely and effectively rename both your local and remote branches, ensuring a clean and consistent repository history.

Renaming a Git branch is a common task, whether you're tidying up your repository, correcting a typo, or aligning with new naming conventions. While renaming a local branch is straightforward, renaming a remote branch requires a few extra steps to ensure consistency across all collaborators. This guide will walk you through the process for both scenarios, providing clear commands and best practices.

Understanding the Renaming Process

Before diving into the commands, it's helpful to understand the sequence of operations involved. Renaming a local branch is a client-side operation. However, Git doesn't have a direct 'rename remote branch' command. Instead, you effectively delete the old remote branch and push the new local branch with the desired name. This ensures that the remote repository reflects your changes correctly.

flowchart TD
    A[Start] --> B{Checkout Old Branch};
    B --> C[Rename Local Branch];
    C --> D[Delete Old Remote Branch];
    D --> E[Push New Local Branch];
    E --> F[Reset Upstream (Optional)];
    F --> G[Notify Team];
    G --> H[End];

Flowchart of the Git branch renaming process

Renaming a Local Git Branch

Renaming a local branch is the simplest part of the process. You can do this whether you are currently on the branch you want to rename or on a different branch. It's generally safer to switch to a different branch before renaming the target branch, but Git allows renaming the current branch as well.

1. Step 1: Switch to a different branch (optional but recommended)

It's good practice to switch to a different branch (e.g., main or develop) before renaming the branch you intend to change. This avoids potential issues if you're actively working on the branch being renamed.

2. Step 2: Rename the local branch

Use the git branch -m command to rename your local branch. The -m flag stands for 'move' or 'rename'.

# If you are currently on the branch you want to rename:
git branch -m <new-branch-name>

# If you are on a different branch:
git branch -m <old-branch-name> <new-branch-name>

Commands to rename a local Git branch

Renaming a Remote Git Branch

Renaming a remote branch involves a few more steps because Git doesn't have a direct command for it. You'll essentially delete the old remote branch and then push your newly renamed local branch to the remote, establishing it as the new remote branch.

1. Step 1: Ensure your local branch is renamed

Make sure you have already renamed your local branch using the steps outlined above. Let's assume your local branch is now named feature/new-name.

2. Step 2: Delete the old branch from the remote

You need to delete the old branch from the remote repository. The git push origin --delete command is used for this.

3. Step 3: Push the new local branch to the remote

Now, push your newly renamed local branch to the remote. This will create a new branch on the remote with the desired name.

4. Step 4: Reset the upstream branch (important!)

After pushing the new branch, your local branch is not yet tracking the new remote branch. You need to set the upstream for your local branch to track the new remote branch. This ensures that git pull and git push work correctly without specifying the remote and branch name every time.

5. Step 5: Inform your team

This is a crucial step! Since you've changed a remote branch, other collaborators will still have the old branch name locally. They need to update their local repositories.

# Assuming your old branch was 'feature/old-name' and new is 'feature/new-name'

# 1. Delete the old remote branch
git push origin --delete feature/old-name

# 2. Push the new local branch to remote
git push origin -u feature/new-name

# The '-u' flag sets the upstream tracking for the new branch.
# Alternatively, if you're already on the new branch:
git push --set-upstream origin feature/new-name

Commands to rename a remote Git branch

What Your Team Needs to Do

When a remote branch is renamed, your team members need to perform a few steps to update their local repositories and avoid working on stale branches. This typically involves fetching the latest changes, deleting their local copy of the old branch, and checking out the new branch.

# 1. Fetch all remote changes (including deleted branches)
git fetch origin --prune

# '--prune' removes any remote-tracking references that no longer exist on the remote.

# 2. Delete their local copy of the old branch (if they had it)
git branch -d feature/old-name

# If they were working on it, they might need '-D' (force delete):
git branch -D feature/old-name

# 3. Checkout the new branch
git checkout feature/new-name

Commands for team members to update their local repositories after a remote branch rename