How to Rename Git Branch Locally and Remotely: A Step-by-Step Guide

We’ve all been there. You create a feature branch with a name like fix-bug-123, only to realize ten minutes later that the bug is actually a feature request, or worse, you simply made a typo. When I first started with version control, I thought I had to delete the branch and recreate it, which is a nightmare if you’ve already pushed commits.

Knowing how to rename git branch locally and remotely is a fundamental skill that keeps your repository clean and your team’s workflow organized. In this guide, I’ll walk you through the exact process I use in my daily development workflow to rename branches without losing a single commit.

Prerequisites

Before we dive into the commands, ensure you have the following:

• Git installed on your local machine.
• A repository cloned locally.
• Appropriate permissions to push changes to the remote repository (GitHub, GitLab, or Bitbucket).

Step 1: Rename the Branch Locally

The first part of the process happens entirely on your machine. Depending on whether you are currently on the branch you want to rename or on a different one, the command varies slightly.

Option A: Renaming the current branch

If you have the branch checked out, use the -m (move) flag:

git branch -m new-branch-name

Option B: Renaming a different branch

If you are on main and want to rename old-name to new-name without switching branches:

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

At this point, your local environment is updated, but the remote server still knows the old name. If you only worked locally, you’re done. But for most of us, the next step is critical.

Step 2: Update the Remote Repository

Git doesn’t have a single “rename remote branch” command. Instead, you have to push the new branch and then delete the old one. As shown in the terminal output in the image below, this is a two-step process.

Push the new branch and reset upstream

Push the locally renamed branch to the remote and set it to track the new name:

git push origin -u new-branch-name

Delete the old branch from the remote

Now, remove the outdated branch name from the server:

git push origin --delete old-branch-name

I’ve found that forgetting the --delete step is the most common cause of “ghost branches” in GitHub, which can confuse your teammates during PR reviews.

Pro Tips for Branch Management

Renaming branches is common, but maintaining a clean Git history is where the real productivity gains happen. Here are a few tips from my experience:

• Coordinate with your team: If other developers are working on the same branch, notify them before you rename it. They will need to run git fetch --all and switch to the new branch.
• Use a naming convention: To avoid renaming in the future, I use prefixes like feat/, fix/, and chore/.
• Clean up your stash: Before performing major branch operations, it’s a good habit to clear your workspace. Check out my git stash multiple changes guide to learn how to manage temporary work safely.

Troubleshooting Common Issues

Sometimes things don’t go as planned. Here are the most frequent hurdles I encounter:

“Branch is currently checked out” error

If you try to delete a branch locally that you are currently on, Git will stop you. Switch to main or develop first:

git checkout main
git branch -d old-branch-name

Merge Conflicts after Renaming

While renaming itself doesn’t cause conflicts, merging the renamed branch into another might. If you run into issues during the final merge, I highly recommend learning how to fix git merge conflicts in VS Code for a visual way to resolve them.

What’s Next?

Now that you know how to rename your branches, you might want to explore more advanced Git workflows. I suggest looking into Git Rebase to keep your commit history linear or exploring Git Hooks to automate branch naming rules for your entire team.

Ready to automate your workflow? Subscribe to the ajmani.dev newsletter for more deep dives into development productivity tools!