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\u2014especially on a shared, remote repository\u2014is 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.<\/p>\n\n\n\n
Here\u2019s the high-level summary of what you need to know.<\/p>\n\n\n\n
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.<\/p>\n\n\n\n
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.<\/p>\n\n\n\n
The command you need is git branch with the -m flag, which stands for “move.” Think of it as moving<\/em> the branch pointer from one name to another.<\/p>\n\n\n\n There are two ways to use it.<\/p>\n\n\n\n This is the most common use case. You are currently working on a branch, and you notice you made a typo.<\/p>\n\n\n\n First, check which branch you’re on with git status or git branch. feature\/main-nav<\/p>\n\n\n\n * feture\/login-page <– Oops, a typo!<\/p>\n\n\n\n main<\/p>\n\n\n\n You are on the branch you want to rename. Just provide the new name. Now, check your branches again. feature\/main-nav<\/p>\n\n\n\n * feature\/login-page <– Fixed!<\/p>\n\n\n\n main<\/p>\n\n\n\n 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.<\/p>\n\n\n\n Check your branches. feature\/main-nav<\/p>\n\n\n\n fix\/typo-header<\/p>\n\n\n\n * main<\/p>\n\n\n\n You want to rename fix\/typo-header to fix\/header-padding. You provide both<\/em> the old name and the new name. Check the result. feature\/main-nav<\/p>\n\n\n\n fix\/header-padding <– Fixed!<\/p>\n\n\n\n * main<\/p>\n\n\n\n What if you just want to change the capitalization? For example, renaming feature\/contact to feature\/Contact.<\/p>\n\n\n\n On operating systems like Linux, this is a normal rename, and git branch -m will work fine.<\/p>\n\n\n\n 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<\/em>. If you try it, you might get an error:<\/p>\n\n\n\n $ git branch -m feature\/contact feature\/Contact<\/p>\n\n\n\n fatal: A branch named ‘feature\/Contact’ already exists.<\/p>\n\n\n\n To solve this, you use the -M<\/strong> flag (a capital ‘M’). This tells Git to force<\/em> the rename, even if it thinks the name already exists.<\/p>\n\n\n\n $ git branch -M feature\/contact feature\/Contact<\/p>\n\n\n\n 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.<\/p>\n\n\n\n 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.<\/p>\n\n\n\n You cannot<\/strong> directly rename a remote branch.<\/p>\n\n\n\n Instead, the process is a “rename-push-delete” operation. You rename your local branch, push that new<\/em> branch to the remote (creating a new remote branch), and then delete<\/em> the old remote branch.<\/p>\n\n\n\n Let’s walk through it, step-by-step.<\/p>\n\n\n\n First, get your local repository in order. Make sure you have the latest changes from the remote (git fetch origin, git pull).<\/p>\n\n\n\n Then, check out the branch you want to rename and rename it locally using the command we just learned.<\/p>\n\n\n\n # Example: We want to rename ‘feature\/old-auth’ to ‘feature\/new-oauth2-flow’<\/p>\n\n\n\n # 1. Switch to the branch (if you’re not already on it)<\/p>\n\n\n\n $ git checkout feature\/old-auth<\/p>\n\n\n\n # 2. Rename it locally<\/p>\n\n\n\n $ git branch -m feature\/new-oauth2-flow<\/p>\n\n\n\n # 3. Your local branch is now renamed.<\/p>\n\n\n\n $ git branch<\/p>\n\n\n\n * feature\/new-oauth2-flow<\/p>\n\n\n\n main<\/p>\n\n\n\n At this point, your local branch is called feature\/new-oauth2-flow, but the remote repository (origin) only knows about the old<\/em> branch, origin\/feature\/old-auth. Your local branch is likely still “tracking” this old, soon-to-be-deleted remote branch.<\/p>\n\n\n\n Next, you need to push your newly named local branch to the remote. This will create a new branch on the remote<\/strong> with the new name.<\/p>\n\n\n\n This is the most important command in the process.<\/p>\n\n\n\n $ git push origin -u feature\/new-oauth2-flow<\/p>\n\n\n\n Let’s break down that command:<\/p>\n\n\n\n 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.<\/p>\n\n\n\n The output will look something like this:<\/p>\n\n\n\n Total 0 (delta 0), reused 0 (delta 0)<\/p>\n\n\n\n remote:<\/p>\n\n\n\n remote: To [https:\/\/github.com\/your-repo\/project.git](https:\/\/github.com\/your-repo\/project.git)<\/p>\n\n\n\n * [new branch] feature\/new-oauth2-flow -> feature\/new-oauth2-flow<\/p>\n\n\n\n Branch ‘feature\/new-oauth2-flow’ set up to track remote branch ‘feature\/new-oauth2-flow’ from ‘origin’.<\/p>\n\n\n\n Success. Now, if you check your remote repository on GitHub, you will see two<\/em> branches:<\/p>\n\n\n\n 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.<\/p>\n\n\n\n $ git push origin –delete feature\/old-auth<\/p>\n\n\n\n This command is clear and explicit. You are telling origin to –delete the branch named feature\/old-auth.<\/p>\n\n\n\n The output will be simple:<\/p>\n\n\n\n To [https:\/\/github.com\/your-repo\/project.git](https:\/\/github.com\/your-repo\/project.git)<\/p>\n\n\n\n – [deleted] feature\/old-auth<\/p>\n\n\n\n An important note:<\/strong> 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.<\/p>\n\n\n\n That’s the core workflow. Here it is in three lines:<\/p>\n\n\n\n # 1. Rename local branch<\/p>\n\n\n\n $ git branch -m <old-name> <new-name><\/p>\n\n\n\n # 2. Push new branch and set to track<\/p>\n\n\n\n $ git push origin -u <new-name><\/p>\n\n\n\n # 3. Delete old remote branch<\/p>\n\n\n\n $ git push origin –delete <old-name><\/p>\n\n\n\n You’ve run the three commands. The job is done, right?<\/p>\n\n\n\n Wrong. This is the part that separates professional developers from amateurs. The job isn’t finished until your team<\/em> and your tools<\/em> are updated.<\/p>\n\n\n\n If you followed Step 2 and used the -u flag, you’re all set. Your local branch is correctly tracking the new remote branch.<\/p>\n\n\n\n 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.<\/p>\n\n\n\n If you run git status, you might see a message like this:<\/p>\n\n\n\n $ git status<\/p>\n\n\n\n On branch feature\/new-oauth2-flow<\/p>\n\n\n\n Your branch is based on ‘origin\/feature\/old-auth’, but the upstream is gone.<\/p>\n\n\n\n (use “git branch –unset-upstream” to fixup)<\/p>\n\n\n\n Git is telling you that your local branch is still linked to a remote branch that doesn’t exist.<\/p>\n\n\n\n The Fix:<\/strong> You just need to tell your local branch to track the new remote branch.<\/p>\n\n\n\n $ git branch –set-upstream-to=origin\/feature\/new-oauth2-flow<\/p>\n\n\n\n (Note: If you are on the branch, you can omit the final <new-name> argument).<\/p>\n\n\n\n This is the most critical step<\/strong> in a team environment.<\/p>\n\n\n\n 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<\/em>. This is confusing and stops her workflow.<\/p>\n\n\n\n You must<\/em> communicate the change.<\/p>\n\n\n\n Give your teammates a set of commands they can copy and paste to update their local repositories.<\/p>\n\n\n\n # 1. Fetch all remote changes, and prune (clean up)<\/p>\n\n\n\n # stale references to deleted branches.<\/p>\n\n\n\n $ git fetch origin –prune<\/p>\n\n\n\n # 2. Switch to your local version of the old branch<\/p>\n\n\n\n $ git checkout <old-name><\/p>\n\n\n\n # 3. Rename your local branch to match the new one<\/p>\n\n\n\n $ git branch -m <new-name><\/p>\n\n\n\n # 4. Set your new local branch to track the new remote branch<\/p>\n\n\n\n $ git branch –set-upstream-to=origin\/<new-name><\/p>\n\n\n\n # 5. (Optional but good) Pull to make sure you’re fully in sync<\/p>\n\n\n\n $ git pull<\/p>\n\n\n\n So, for our example, Jane would run:<\/p>\n\n\n\n $git fetch origin –prune$ git checkout feature\/old-auth<\/p>\n\n\n\n $git branch -m feature\/new-oauth2-flow$ git branch –set-upstream-to=origin\/feature\/new-oauth2-flow<\/p>\n\n\n\n $ git pull<\/p>\n\n\n\n This simple act of communication saves hours of team-wide confusion.<\/p>\n\n\n\n Where else was that old branch name being used?<\/p>\n\n\n\n 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<\/a> website today is a tale of two toolsets that must work in perfect harmony.<\/p>\n\n\n\n This is the world we’ve been discussing. It’s where we developers live. We use Git to manage the “engine” of the site.<\/p>\n\n\n\n When we’re renaming a Git branch, as we’ve just covered, we are meticulously managing the code’s<\/em> history and evolution.<\/p>\n\n\n\n This is the other, equally important half of the equation: the site’s “body” and “voice.”<\/p>\n\n\n\n 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.<\/p>\n\n\n\n This is where a platform like Elementor<\/a> 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<\/a>, your focus is on user experience and brand, not on Git commands.<\/p>\n\n\n\n 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.<\/p>\n\n\n\n At the exact same time, a designer is using the Elementor WooCommerce Builder<\/a> to visually redesign that same<\/em> checkout page. They are adding new fields, changing the layout, and updating the branding.<\/p>\n\n\n\n The final deployment to the live site needs to include both<\/em> my Git push (the new code) and the designer’s work (which is saved in the WordPress database).<\/p>\n\n\n\n As web development expert Itamar Haim<\/strong> 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.”<\/p>\n\n\n\n This is why we’re seeing a major shift toward integrated platforms. A solution like Elementor Hosting<\/a>, for example, is designed to bridge this exact gap.<\/p>\n\n\n\n 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.<\/p>\n\n\n\n This creates a perfect workflow:<\/p>\n\n\n\nScenario 1: Renaming the Branch You Are Currently On<\/strong><\/h4>\n\n\n\n
$ git branch<\/p>\n\n\n\n\n
$ git branch -m feature\/login-page<\/p>\n\n\n\n\n
$ git branch<\/p>\n\n\n\n\n
Scenario 2: Renaming a <\/strong>Different<\/em><\/strong> Local Branch<\/strong><\/h4>\n\n\n\n
$ git branch<\/p>\n\n\n\n\n
$ git branch -m fix\/typo-header fix\/header-padding<\/p>\n\n\n\n\n
$ git branch<\/p>\n\n\n\n\n
What About Case Sensitivity? The <\/strong>-M<\/strong> Flag<\/strong><\/h3>\n\n\n\n
The Main Event: How to Rename a Remote Git Branch<\/strong><\/h2>\n\n\n\n
Step 1: Rename Your Local Branch<\/strong><\/h3>\n\n\n\n
Step 2: Push the <\/strong>New<\/em><\/strong> Branch to the Remote<\/strong><\/h3>\n\n\n\n
\n
\n
\n
Step 3: Delete the <\/strong>Old<\/em><\/strong> Branch from the Remote<\/strong><\/h3>\n\n\n\n
Summary: The 3-Step Remote Rename Process<\/strong><\/h3>\n\n\n\n
The Crucial “After-Party”: What to Do After Renaming a Remote Branch<\/strong><\/h2>\n\n\n\n
For You: Resetting Your Upstream Tracking (If Needed)<\/strong><\/h3>\n\n\n\n
For Your Teammates: Communicating the Change<\/strong><\/h3>\n\n\n\n
Your Communication Plan (Actionable Checklist)<\/strong><\/h4>\n\n\n\n
\n
“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<\/em> or wait until I’m done.”<\/li>\n\n\n\n
“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:”<\/li>\n<\/ol>\n\n\n\nThe Update “Recipe” for Your Teammates (Step-by-Step)<\/strong><\/h4>\n\n\n\n
For Your Tools: Updating CI\/CD and Integrations<\/strong><\/h3>\n\n\n\n
\n
\n
A Modern Web Creator’s Workflow: Where Git Meets Visual Design<\/strong><\/h2>\n\n\n\n
The Code Layer: Managed by Developers with Git<\/strong><\/h3>\n\n\n\n
\n
The Design & Content Layer: Managed by Creators with Visual Tools<\/strong><\/h3>\n\n\n\n
Syncing the Two Worlds: The Deployment Challenge<\/strong><\/h3>\n\n\n\n
How a Unified Platform Simplifies This<\/strong><\/h3>\n\n\n\n