It may seem like a trivial task, but renaming a branch is a common and crucial operation. You might need to fix a simple typo, or you might need to update a branch name to reflect a change in project direction or to fit new team-wide naming conventions. Knowing how to do this correctly—especially on a shared, remote repository—is a fundamental skill that separates a junior developer from a seasoned professional. It’s not just about running a command. It’s about maintaining a clean, collaborative, and understandable project history for your entire team.

Key Takeaways

Here’s the high-level summary of what you need to know.

  • Renaming a local branch is a simple, one-line command: git branch -m <old-name> <new-name>. If you’re on the branch, you can just use git branch -m <new-name>.
  • Renaming a remote branch is a multi-step process. You cannot directly rename a remote branch. You must:
    1. Rename your local branch first.
    2. Push the new local branch to the remote: git push origin -u <new-name>.
    3. Delete the old branch from the remote: git push origin –delete <old-name>.
  • Communication is critical. Before renaming a shared remote branch, you must communicate with your team. Renaming a remote branch will require action from every teammate who has a local copy of that branch.
  • Update everything. After a remote rename, you must update your local tracking setup. Your teammates must update theirs. You must also check any CI/CD pipelines, GitHub Actions, or project management tickets that might have been pointing to the old branch name.

Why Branch Naming Matters in a Professional Workflow

Before we dive into the “how,” let’s establish the “why.” In a professional environment, branch names are not just for you. They are a core part of your team’s communication.

  • Clarity and Readability: A branch name is a signpost. It tells a story. A branch named my-stuff or updates is useless. A branch named feature/user-auth-oauth2 or fix/ticket-123-contact-form-validation tells your project manager and teammates exactly what is happening in that line of development.
  • Team Collaboration: When your whole team uses a predictable naming convention (e.g., feature/, fix/, chore/, release/), anyone can look at the list of active branches and understand the project’s status at a glance.
  • Automation & CI/CD: This is a big one. Modern development relies on Continuous Integration and Continuous Deployment (CI/CD). Tools like GitHub Actions, GitLab CI, and Jenkins are often configured to trigger builds, tests, or deployments based on branch name patterns. For example, a rule might automatically deploy any branch starting with release/ to a staging server. A typo or a non-conforming name (relase/v1.2) breaks that entire automation chain.
  • Project Housekeeping: A repository full of poorly named, old, or ambiguous branches is like a messy workshop. You can’t find your tools, and it’s dangerous to work in. Periodically cleaning up branches and ensuring they are named well makes all future work faster and more efficient.

How to Rename a Local Git Branch: The Step-by-Step Guide

Let’s start with the simplest scenario. You have a branch on your local machine, and you want to rename it. It has not been pushed to a remote repository, or you only want to change the local name for now.

The Core Command: git branch -m

The command you need is git branch with the -m flag, which stands for “move.” Think of it as moving the branch pointer from one name to another.

There are two ways to use it.

Scenario 1: Renaming the Branch You Are Currently On

This is the most common use case. You are currently working on a branch, and you notice you made a typo.

First, check which branch you’re on with git status or git branch.
$ git branch

  feature/main-nav

* feture/login-page  <– Oops, a typo!

  main

You are on the branch you want to rename. Just provide the new name.
$ git branch -m feature/login-page

Now, check your branches again.
$ git branch

  feature/main-nav

* feature/login-page  <– Fixed!

  main

  1. It’s that simple. Git assumes you want to rename the branch you are currently on.

Scenario 2: Renaming a Different Local Branch

You can also rename a branch from anywhere else. For instance, let’s say you are on the main branch, but you see a typo in another branch.

Check your branches.
$ git branch

  feature/main-nav

  fix/typo-header

* main

You want to rename fix/typo-header to fix/header-padding. You provide both the old name and the new name.
$ git branch -m fix/typo-header fix/header-padding

Check the result.
$ git branch

  feature/main-nav

  fix/header-padding  <– Fixed!

* main

What About Case Sensitivity? The -M Flag

What if you just want to change the capitalization? For example, renaming feature/contact to feature/Contact.

On operating systems like Linux, this is a normal rename, and git branch -m will work fine.

However, on case-insensitive file systems (which are the default for macOS and Windows), Git might get confused. It sees feature/contact and feature/Contact as the same file path. If you try it, you might get an error:

$ git branch -m feature/contact feature/Contact

fatal: A branch named ‘feature/Contact’ already exists.

To solve this, you use the -M flag (a capital ‘M’). This tells Git to force the rename, even if it thinks the name already exists.

$ git branch -M feature/contact feature/Contact

Think of -m as “move” and -M as “force-move.” You should generally avoid case-only renames if you can. They can cause a lot of confusion for teammates, especially in a mixed-OS environment.

The Main Event: How to Rename a Remote Git Branch

This is the operation that requires real care. When your branch exists on a shared remote repository (like GitHub, GitLab, or Bitbucket), you are not just renaming a file on your computer. You are coordinating a change that affects everyone on your team who uses that branch.

You cannot directly rename a remote branch.

Instead, the process is a “rename-push-delete” operation. You rename your local branch, push that new branch to the remote (creating a new remote branch), and then delete the old remote branch.

Let’s walk through it, step-by-step.

Step 1: Rename Your Local Branch

First, get your local repository in order. Make sure you have the latest changes from the remote (git fetch origin, git pull).

Then, check out the branch you want to rename and rename it locally using the command we just learned.

# Example: We want to rename ‘feature/old-auth’ to ‘feature/new-oauth2-flow’

# 1. Switch to the branch (if you’re not already on it)

$ git checkout feature/old-auth

# 2. Rename it locally

$ git branch -m feature/new-oauth2-flow

# 3. Your local branch is now renamed.

$ git branch

* feature/new-oauth2-flow

  main

At this point, your local branch is called feature/new-oauth2-flow, but the remote repository (origin) only knows about the old branch, origin/feature/old-auth. Your local branch is likely still “tracking” this old, soon-to-be-deleted remote branch.

Step 2: Push the New Branch to the Remote

Next, you need to push your newly named local branch to the remote. This will create a new branch on the remote with the new name.

This is the most important command in the process.

$ git push origin -u feature/new-oauth2-flow

Let’s break down that command:

  • git push origin: Standard command to push to your remote named origin.
  • feature/new-oauth2-flow: The name of your new local branch.
  • -u (or –set-upstream): This is the critical part. This flag does two things in one:
    1. It pushes your branch.
    2. It sets your local branch (feature/new-oauth2-flow) to track the new remote branch (origin/feature/new-oauth2-flow) that you are creating in the process.

This linkage is essential. It tells Git that from now on, when you are on feature/new-oauth2-flow, any git pull or git push commands should automatically go to and from origin/feature/new-oauth2-flow.

The output will look something like this:

Total 0 (delta 0), reused 0 (delta 0)

remote:

remote: To [https://github.com/your-repo/project.git](https://github.com/your-repo/project.git)

 * [new branch]      feature/new-oauth2-flow -> feature/new-oauth2-flow

Branch ‘feature/new-oauth2-flow’ set up to track remote branch ‘feature/new-oauth2-flow’ from ‘origin’.

Success. Now, if you check your remote repository on GitHub, you will see two branches:

  1. feature/old-auth
  2. feature/new-oauth2-flow

Step 3: Delete the Old Branch from the Remote

Your work isn’t done. You now have two branches on the remote, which is confusing and messy. The final step is to clean up by deleting the old, unwanted branch from the remote.

$ git push origin –delete feature/old-auth

This command is clear and explicit. You are telling origin to –delete the branch named feature/old-auth.

The output will be simple:

To [https://github.com/your-repo/project.git](https://github.com/your-repo/project.git)

 – [deleted]         feature/old-auth

An important note: You may see an older, less-intuitive syntax online: git push origin :feature/old-auth. This “colon” syntax works, but it is much harder to read and remember. The –delete flag was added specifically to make this operation safer and more understandable. Always use –delete.

Summary: The 3-Step Remote Rename Process

That’s the core workflow. Here it is in three lines:

# 1. Rename local branch

$ git branch -m <old-name> <new-name>

# 2. Push new branch and set to track

$ git push origin -u <new-name>

# 3. Delete old remote branch

$ git push origin –delete <old-name>

The Crucial “After-Party”: What to Do After Renaming a Remote Branch

You’ve run the three commands. The job is done, right?

Wrong. This is the part that separates professional developers from amateurs. The job isn’t finished until your team and your tools are updated.

For You: Resetting Your Upstream Tracking (If Needed)

If you followed Step 2 and used the -u flag, you’re all set. Your local branch is correctly tracking the new remote branch.

But what if you forgot? Or what if you renamed the branch in the GitHub UI? Your local branch might still be “tracking” the old, deleted remote branch.

If you run git status, you might see a message like this:

$ git status

On branch feature/new-oauth2-flow

Your branch is based on ‘origin/feature/old-auth’, but the upstream is gone.

  (use “git branch –unset-upstream” to fixup)

Git is telling you that your local branch is still linked to a remote branch that doesn’t exist.

The Fix: You just need to tell your local branch to track the new remote branch.

$ git branch –set-upstream-to=origin/feature/new-oauth2-flow

(Note: If you are on the branch, you can omit the final <new-name> argument).

For Your Teammates: Communicating the Change

This is the most critical step in a team environment.

Think about it: Your teammate, “Jane,” has a local copy of feature/old-auth. She does some work and runs git push. Her command will fail because origin/feature/old-auth no longer exists. This is confusing and stops her workflow.

You must communicate the change.

Your Communication Plan (Actionable Checklist)

  1. Notify: Post in your team’s Slack or Teams channel before you rename:
    “Hey team, I’m renaming the remote branch feature/old-auth to feature/new-oauth2-flow to match the new spec. This will happen in the next 5 minutes. Please save and push any work on that branch now or wait until I’m done.”
  2. Execute: Perform your 3-step rename (rename local, push new, delete old).
  3. Announce: Post again with a “recipe” for your team:
    “The branch rename is complete. feature/old-auth is now feature/new-oauth2-flow. If you have a local copy of the old branch, please run the following commands to get in sync:”

The Update “Recipe” for Your Teammates (Step-by-Step)

Give your teammates a set of commands they can copy and paste to update their local repositories.

# 1. Fetch all remote changes, and prune (clean up)

#    stale references to deleted branches.

$ git fetch origin –prune

# 2. Switch to your local version of the old branch

$ git checkout <old-name>

# 3. Rename your local branch to match the new one

$ git branch -m <new-name>

# 4. Set your new local branch to track the new remote branch

$ git branch –set-upstream-to=origin/<new-name>

# 5. (Optional but good) Pull to make sure you’re fully in sync

$ git pull

So, for our example, Jane would run:

$git fetch origin –prune$ git checkout feature/old-auth

$git branch -m feature/new-oauth2-flow$ git branch –set-upstream-to=origin/feature/new-oauth2-flow

$ git pull

This simple act of communication saves hours of team-wide confusion.

For Your Tools: Updating CI/CD and Integrations

Where else was that old branch name being used?

  • GitHub/GitLab: Check for any open Pull Requests (PRs) or Merge Requests (MRs). The good news is that most modern platforms, especially GitHub, are smart about this. When you push the new branch and delete the old one, any open PRs targeting the old branch are automatically updated to point to the new branch. You should still refresh the PR page to verify this, but it’s usually seamless.
  • CI/CD Pipelines: This is where things can break. Check your configuration files.
    • In a .github/workflows/main.yml (GitHub Actions) file, do you have rules like on: push: branches: [ feature/old-auth ]?
    • In a .gitlab-ci.yml file, are there rules like if: $CI_COMMIT_BRANCH == “feature/old-auth”?
    • In a Jenkinsfile, are there triggers watching that specific branch? All of these must be updated to reflect the <new-name>, or your automated builds and tests will fail to run.
  • Project Management: Do you have Jira, Trello, or Asana tickets that link to the branch? Update those links to avoid 404s and maintain your project’s paper trail.

A Modern Web Creator’s Workflow: Where Git Meets Visual Design

As a web development expert who has been in this field for a long time, I’ve seen workflows evolve dramatically. Building a professional WordPress website today is a tale of two toolsets that must work in perfect harmony.

The Code Layer: Managed by Developers with Git

This is the world we’ve been discussing. It’s where we developers live. We use Git to manage the “engine” of the site.

  • We write custom plugin logic.
  • We modify our theme’s functions.php file.
  • We manage complex backend integrations or API connections.
  • We handle site performance and security at the code level.

When we’re renaming a Git branch, as we’ve just covered, we are meticulously managing the code’s history and evolution.

The Design & Content Layer: Managed by Creators with Visual Tools

This is the other, equally important half of the equation: the site’s “body” and “voice.”

This layer is where designers, marketers, and clients build layouts, write blog posts, and create conversion-focused landing pages. They are not using Git. They are using a visual, intuitive, drag-and-drop interface.

This is where a platform like Elementor becomes the central hub for the creative team. It empowers creators to build stunning, “pixel-perfect” designs and manage content directly on the page. As a designer, your focus is on user experience and brand, not on Git commands.

Syncing the Two Worlds: The Deployment Challenge

Here’s where it all comes together. A developer (me) might be working on a Git branch called feature/new-woo-checkout. My goal is to add new backend logic for a custom payment gateway.

At the exact same time, a designer is using the Elementor WooCommerce Builder to visually redesign that same checkout page. They are adding new fields, changing the layout, and updating the branding.

The final deployment to the live site needs to include both my Git push (the new code) and the designer’s work (which is saved in the WordPress database).

As web development expert Itamar Haim often states, “A modern workflow isn’t just about code or just about design. It’s about how seamlessly you can merge the two. Your Git strategy must support your visual builder, and your visual builder must be robust enough for your developers.”

How a Unified Platform Simplifies This

This is why we’re seeing a major shift toward integrated platforms. A solution like Elementor Hosting, for example, is designed to bridge this exact gap.

It provides a high-performance environment that is deeply optimized for the Elementor builder and WordPress. But crucially for developers, it also provides professional-grade tools like SSH access, database access, and often Git integration or one-click staging environments.

This creates a perfect workflow:

  1. I push my Git branch (feature/new-woo-checkout) to our staging site.
  2. The designer logs into the same staging site and uses Elementor Pro to apply their new visual design.
  3. We can now test the full, combined experience—my backend code and their frontend design—in a safe, live environment.
  4. Once approved, we push both to production.

This unified approach connects the developer’s Git-based world with the designer’s visual, Elementor-based world, eliminating the classic “it-works-on-my-machine” problem.

Common Pitfalls and Troubleshooting

Even with a perfect plan, you can run into snags. Here are some common issues and how to fix them.

“I renamed the branch, but git status still shows the old tracking.”

  • Problem: You forgot the -u flag when you pushed, or you renamed the branch in the web UI. Your local branch is still tracking the old, deleted remote branch.

Solution: Manually set the upstream tracking.
$ git branch –set-upstream-to=origin/<new-name>

“My teammate tried to push to the old branch and got an error.”

  • Problem: They see an error like (push declined) src refspec <old-name> does not match any. They haven’t updated their local setup.
  • Solution: Send them the “Recipe for Teammates” from the section above. They need to fetch, rename their local branch, and reset their upstream.

“What if I renamed the master or main branch?”

This is a much bigger, more delicate operation. You follow the same 3-step process (rename local main to production, push new production, delete old main), but you have one extra, critical step:

You must go into your remote repository’s settings (e.g., on GitHub: Settings > Branches).

You need to change the “Default Branch” from main to production.

This is critical because:

  • It tells the remote which branch origin/HEAD points to.
  • All new git clone commands will automatically check out this new default branch.
  • All new Pull Requests will target this branch by default.
  • All your branch protection rules and security policies were likely tied to the old name and must be migrated to the new one.

This is a high-stakes change. Communicate it widely, and be prepared to help your team update. For a guided walkthrough, this is a great resource:

Conclusion: Branch Renaming as a Professional Habit

We’ve covered a lot of ground. Renaming a local Git branch is trivial. Renaming a remote branch is a process that is as much about clear communication as it is about commands.

A clean Git history, populated with clearly and accurately named branches, is a hallmark of a professional developer and a high-functioning team. It’s a small, disciplined habit that pays huge dividends in project clarity and team efficiency.

This discipline is a small part of the larger craft of building and maintaining a professional web project. In the modern landscape, that craft means mastering both the “engine” (our code, managed with Git) and the “body” (the visual design and content, often managed with platforms like Elementor). The true professional is the one who can build the bridge between these two worlds and make them work as one.

Frequently Asked Questions (FAQ) About Renaming Git Branches

1. Q: What’s the shortest command to rename my current local branch? A: git branch -m <new-name>. Git assumes you want to rename the branch you’re currently on.

2. Q: I tried git branch -m new-name and it said “fatal: A branch named ‘new-name’ already exists.” What do I do? A: This means you (or a teammate) already created a branch with that exact name. You have two options: 1) If the other branch is old and unneeded, delete it first with git branch -d new-name. 2. Pick a different, unique name for your rename.

3. Q: What is the difference between git branch -m and git branch -M? A: -m stands for “move.” -M is a “force move.” You typically only need -M in two cases: 1. You are on a case-insensitive system (macOS/Windows) and your rename is only a change in capitalization (e.g., bugfix to Bugfix). 2. The new name you want to use already exists, and you want to forcibly overwrite that other branch (this is dangerous and usually a mistake).

4. Q: Will renaming a remote branch break my team’s work? A: It absolutely can if you don’t communicate. Anyone with a local copy of the old branch will be out of sync. Their next git push or git pull on that branch will fail. You must notify them and provide instructions (like the “recipe” in this article) for them to update their local repositories.

5. Q: What happens to my GitHub Pull Request if I rename the branch? A: On modern platforms like GitHub, the PR is automatically updated. If you push your new branch and delete the old one, the open Pull Request will be seamlessly retargeted to your new branch. You should still refresh the page to verify, but it’s generally not a problem.

6. Q: Why can’t I just rename the branch on the GitHub/GitLab website? A: You can, and it’s actually a very safe way to do it! Most modern web UIs now support this. If you rename the branch on GitHub’s website (via the “branches” page), it will even give you the exact commands you and your team need to run locally to sync up. This is an excellent, user-friendly option.

7. Q: I renamed the remote branch, but my old branch is still showing up when I type git branch -a. Why? A: Your local repository is holding onto a “remote-tracking” branch (e.g., remotes/origin/old-name) that is now “stale” or “orphaned.” It’s just a local reference. You can clean up all stale references from your local machine by running git remote prune origin or git fetch –prune.

8. Q: Is it safe to rename the master or main branch? A: It’s a high-impact operation but safe if done carefully. You must follow the 3-step rename process (rename local, push new, delete old) and then—this is the critical part—immediately go into your repository’s settings on GitHub/GitLab and set the new branch as the “Default Branch.” This is essential for all CI/CD, security policies, and new clones.

9. Q: What’s the command to delete the old remote branch again? A: The modern, clear, and recommended command is git push origin –delete <old-name>.

10. Q: Does this process affect my commit history? A: No, not at all. Renaming a branch does not change, edit, or rewrite any of your commits. A branch is just a lightweight, movable pointer (like a sticky note) that points to the last commit in that line of work. Renaming it just writes a new name on the sticky note. Your commit history is 100% safe.