Git Delete Branch How-To, for Both Local and Remote

Efficient branch management is essential for using Git to its fullest potential. This post is all about the Git delete branch operation. You’ll learn how to delete branches, both locally and in your remote repositories, and whether it’s possible to recover a deleted branch. Most importantly, you’ll learn what branches are under the hood to have a more solid understanding of what happens when you delete them.

This tutorial assumes you have Git installed and know your way around the command line. Also, make sure you have a GitHub account and are logged in.

If you just want to learn the correct incantation to delete branches in Git, we’ll start by offering the TL;DR version.

To delete a local branch in Git, you simply run:

git branch -d <branch-name>

If the branch contains unmerged changes, though, Git will refuse to delete it. If you’re sure you want to do it, you’ll have to force the deletion by replacing the -d parameter with an uppercase D:

git branch -D <branch-name>

You don’t use the git branch command to delete a remote branch. You use git push, even if that sounds weird. Here’s how you do it:

git push --delete <remote name> <branch name>

It’s like you’re pushing—sending—the order to delete the branch to the remote repository.

With that out of the way, we’ll now explore the deletion of branches in Git in some more depth.

Let’s start by examining what branches are in Git and what’s happening when you delete them.

Branching in Git is dead simple. Branches are named, movable references to commits. Imagine you create a repository and add three commits:

Now you create a new branch called “exp.” The branch currently points to the same commit, so the scenario looks like this:

You switch to the new branch and add two more commits to it. This is what your repo looks like now:

So, what would happen if you deleted the exp branch?

When you delete a branch in Git, you don’t delete the commits themselves. That’s right: The commits are still there, and you might be able to recover them.

When you delete a branch, what happens depends on whether the branch was already merged. Let’s look at two scenarios.

Go back and take a look at the last diagram. As you can see, the main branch is behind exp. In this situation, merging is just a matter of moving the main reference forward until it catches up to exp. Let’s do that:

At this point, if we delete the exp branch, nothing changes. The commits were already integrated into the original branch:

Now let’s explore the scenario where the branch contains unmerged changes. Take a look at the diagram the depicts the moment after you’ve added the new commits to exp but haven’t yet merged them back to main:

If you go now and get rid of the exp branch, your repo will look like this:

As you can see, the commits are still there. But unless you have the hash of the last commit, you won’t be able to reach them. Why?

A commit has a reference to its parent—or parents—but not to its children. From the commit that main points to, you can only move backward, so there’s no way for you to reach the commits formerly pointed to by exp.

What if you delete a branch with unmerged commits by mistake? Are those changes lost for good? Not yet. There’s a way to recover them if you act quickly. More on that later.

Let’s see an example. 

Start by creating a repository and adding a commit to it:

mkdir demo

cd demo

git init

echo hello world > file.txt

git add file.txt

git commit -m “Add first file”

Now you can create a second branch. Let’s call it new:

git branch new

At this point, you could switch to the new branch, add some commits to it, then go back and merge it into main. The results would be the same, though. Let’s delete it right away:

git branch -d new

After running the command, Git will let you know the branch was successfully deleted. It will also display the hash of the commit pointed to by the branch:

Deleted branch new (was c9bd965).

Now let’s try to delete a branch with unmerged changes. Create a new branch and switch to it:

git switch -c newer

While in this branch, add some commits:

echo hello world > file2 && git add . && git commit -m "Add file2"

echo hello world > file3 && git add . && git commit -m "Add file3"

Go back to the original branch:

git switch main

And try to delete newer:

git branch -d newer

It won’t work. Git will show you this message:

error: The branch ‘newer’ is not fully merged.

If you are sure you want to delete it, run 'git branch -D newer.’

The message is unmistakable: if you’re sure of what you’re doing, run the command with the -D parameter:

git branch -D newer

You’ll often need to delete a branch not only locally but also remotely. To do that, you use the following command:

git push <remote_name> --delete <branch_name>.

Let’s look at an example. Start by creating a new repository on GitHub. After you’re done, you’ll create the local repo. Using the command line, create a new folder, access it, and start a new repo with one commit:

mkdir delete-remote-branch

cd delete-remote-branch

git init

git commit --allow-empty -m “Initial commit”

Now you can use the following commands to add the remote repository on GitHub as a remote for the local one (make sure you replace the actual URL with your own):

git remote add origin https://github.com/carlosschults/upgraded-eureka.git

git branch -M main

git push -u origin main

Now let’s create a new branch, switch to it, and add a new commit:

git switch -c hotfix

echo hi > readme.md && git add readme.md && git commit -m “Add README file”

Finally, you can push your new branch to GitHub:

git push -u origin hotfix

You’ll see a result like this:

Go back to GitHub, and you’ll see your new branch there:

OK. Now you’re ready to delete the branch remotely. As you’ve seen, the command to do that is git push --delete <remote name> <branch name>. The name of the remote is origin—which is the convention for the “default” remote repository—and the name of the branch is hotfix. So, run the following:

git push --delete origin hotfix

You’ll see a message showing that Git deleted the branch remotely:

To https://github.com/carlosschults/upgraded-eureka.git

 - [deleted]         hotfix

The branch still exists locally, though. Since it has unmerged changes, you can delete it quickly using git branch -D hotfix after switching back to main.

It’s possible to delete branches on GitHub using the interface. You can choose to delete a branch when you merge a pull request. For instance:

You can also simply delete the branch at any time. To do that, repeat the operations from the last section to create a new local branch and push it to GitHub.

Then go back to your repo main page on GitHub, click on the button with the main branch name, and you’ll see this suspended menu:

Click on View all branches, like in the image above, and you’ll be taken to a page where you can see the list of all branches.

To delete the new-feature branch, just click on the trash can icon next to its name. After deleting the branch, it will still be listed for a short while, and you’ll be able to recover it by clicking on the Restore button:

Is it possible to recover local deleted branches in Git? Well, sort of. As you’ve seen, branches are simply references that point to a commit. What you want to do is make that commit reachable again. For that, you’ll need its identifier.

As you’ve seen, when you delete a branch, Git displays the hash of the commit the branch pointed to. If you write that down, you can later use it to access that commit and create a new branch from that point:

git checkout <HASH YOU WROTE DOWN>

git branch <NAME FOR THE BRANCH>

What if you didn’t write it down? There’s still hope for you in the name of a command called reflog.

In a nutshell, git reflog allows you to see the reference logs. At its most basic form, you can use it to see the list of commits that the HEAD reference pointed to over time.

As an example, let’s delete a branch locally:

git branch -D new

Now, suppose I made a terrible mistake and the branch wasn’t supposed to be deleted. I can use the git reflog command:

Having recovered the commit hash, I can then do (remember your actual hash number will be different):

git checkout 984a656

git branch <BRANCH NAME>

Finally, a caveat: git reflog will only save you if the HEAD reference has pointed to the commit you want to recover. You might have scenarios where the desired commit isn’t actually in the reflog, so there will be no way for you to recover its hash.

Before wrapping up, there’s a final question we need to answer: When is it OK to delete branches in Git?

In general, it’s safe to delete branches after they’ve been merged. It might be OK to delete unmerged branches—for instance, after an experiment that went nowhere. You must be aware of the consequences, though: The commits might become unreachable.

Before parting ways, here’s a final thought: Just because you can, doesn’t mean you should. Sure, Git’s powerful branching capabilities might feel fantastic, but using a branching strategy that relies too much on branches—particularly long-lived ones—can get you into trouble.

An alternative is to use a workflow that doesn’t rely on branching—for example, trunk-based development. That, along with a mechanism such as feature flagging, allows teams to go fast, keeping things simple and facilitating CI and CD.

This post was written by Carlos Schults. Carlos is a consultant and software engineer with experience in desktop, web and mobile development. Though his primary language is C#, he has experience with a number of languages and platforms. His main interests include automated testing, version control and code quality.