Articles

How to Rename a Branch in Git Locally and Remotely

Learn how to rename a branch in Git locally and remotely with our step-by-step guide for seamless branch management.

Need to rename a Git branch? You can rename local branches with git branch -m new-name, but remote branches require a few extra steps. We’ll show you both methods with examples.

At a glance: Branch renaming commands

Task Command
Rename current branch git branch -m new-name
Rename specific branch git branch -m old-name new-name
Delete remote branch git push origin --delete branch-name
Push renamed branch git push origin new-name
Set upstream tracking git push --set-upstream origin new-name

In this guide, we’ll walk through the complete process for renaming branches in Git locally and remotely, plus best practices to avoid common issues.

Related Course

Learn Git: Introduction

Learn how to track changes in your code and switch between different versions with Git, an open-source version control system.Try it for free

What is a branch in Git?

In Git, a branch is a lightweight, movable pointer to a commit. Branches allow us to develop features, fix bugs, or do experiments with new ideas in isolation from the main codebase. By default, every Git repository has a main or master branch, but we often create new branches to keep our work organized and collaborative.

Branches are fundamental to workflows like Git Flow, GitHub Flow, and trunk-based development. They enable parallel development, team collaboration, and safe integration. Proper branch naming and management play a critical role in maintaining code quality and clarity across projects.

Now that we understand what Git branches are and why they matter, let’s explore when it makes sense to rename them.

When to rename a branch in Git

There are several scenarios when renaming a Git branch makes sense:

  • Unclear names: Branches like test123, temp-branch, or my-stuff don’t tell us what they do
  • Changed purpose: We started with bugfix-header but ended up adding new features too
  • New conventions: Moving from loginFeature to feature/user-login for better organization
  • Outdated terms: Replacing master with main or removing deprecated terminology

With the common scenarios covered, let’s move on to learning how to rename a branch in Git locally.

How to rename a local Git branch

Renaming a local branch in Git is a quick and easy process, but it’s important to understand the commands and implications to avoid issues with version control or remote repositories. Let’s walk through the steps in detail.

Step 1: Identify the current branch

Before we proceed, we need to know whether we’re currently on the branch we want to rename or not. To list all the local branches in the repository and see the current branch, run this command in the terminal: 

git branch

Here is the output in our case: 

* demo 
  main

The asterisk (*) symbol before demo indicates that we’re currently on the demo branch.

Step 2: Rename the branch

If we want to rename the demo branch, we can run this command: 

git branch -m fix

The git branch command with the -m flag allows us to rename a branch. Here, we’ve used this command to rename the demo branch to fix.

However, we may want to perform this operation while we’re on some other branch. In that case, we can run this command instead: 

git branch -m demo fix

Step 3: Verify the operation

To ensure the operation is successful, we can run this command again: 

git branch

Here is the output in our case: 

* fix 
  main

As we can see, we’ve successfully renamed the demo branch to fix.

Next, let’s understand how to rename a remote branch in Git.

How to rename a remote Git branch

Renaming a remote branch in Git takes a few more steps, but it’s manageable. Let’s go through them one by one.

Step 1: Rename the local branch

Let’s assume that a local branch bugfix is tracking the branch bugfix in the remote repository origin. Here, we want to change the name of the remote branch bugfix to feature.

If we’re on the bugfix branch, we can run this command: 

git branch -m feature

If we’re not on the bugfix branch, we can run this command instead: 

git branch -m bugfix feature

Step 2: Delete the remote branch

In the next step, we’ll need to remove the branch bugfix from origin: 

git push origin --delete bugfix

Step 3: Push the newly renamed branch

Navigate to the newly renamed local branch feature (if we aren’t already there) and push it to origin: 

git push origin feature

Step 4: Reset the upstream tracking

Link the renamed branch to the newly pushed remote branch: 

git push --set-upstream origin feature

This ensures proper tracking between our local and remote repositories.

Since we’re done learning how to rename a branch in Git locally and remotely, let’s talk about some best practices that will keep our workflow smooth and organized.

Best practices for renaming Git branches

Apply these best practices to ensure smooth collaboration and avoid disruption:

  • Notify your team before renaming shared branches.
  • Update open pull requests or merge requests accordingly.
  • Use clear, descriptive names that reflect the branch’s purpose.
  • Avoid frequent renaming to minimize confusion.

By adhering to these best practices, we can maintain a clean and cohesive workflow.

Conclusion

In this tutorial, we covered what Git branches are, why they’re important, and some common scenarios where we should rename them. Then, we learned how to rename Git branches locally and remotely. Finally, we went through some best practices that will help us rename them efficiently.

Git branches empower us to work efficiently and collaboratively. Renaming them — when done thoughtfully — keeps our workflows organized and our codebase professional. By mastering branch management, we can build more maintainable and scalable projects.

If you want to learn more about Git branching and collaboration, check out the Learn Git: Branching and Collaboration course on Codecademy.

Frequently asked questions

1. How do I create a new branch locally and push to remote?

Use the following commands: 

git checkout -b new-branch-name 
git push -u origin new-branch-name

This creates a new branch locally and pushes it to the remote origin with tracking enabled.

To unlink a local branch from its remote counterpart, remove the upstream configuration while on the branch: 

git branch --unset-upstream

You can also edit .git/config manually, but the above command is safer.

3. Will renaming a branch affect my commit history?

No, renaming a branch does not change the commit history. The commits stay intact; only the branch label is updated.

4. Is it safe to rename the main or master branch?

Yes, but with caution. These are default branches in many setups, and renaming them may affect deployment pipelines or integrations. Ensure all team members are informed, and any CI/CD tools are updated.

5. What’s the difference between git branch -m and git branch -M?

  • git branch -m won’t overwrite an existing branch with the same name.
  • git branch -M forces the rename even if the target name already exists.
Codecademy Team

'The Codecademy Team, composed of experienced educators and tech experts, is dedicated to making tech skills accessible to all. We empower learners worldwide with expert-reviewed content that develops and enhances the technical skills needed to advance and succeed in their careers.'

Meet the full team

Related articles

Learn more on Codecademy

Contents