Delete a Git Branch Locally and Remotely

Last updated: February 6, 2024

1. Overview

Git has been widely used as the version control system in the industry. Further, Git branches are a part of our everyday development process.

In this tutorial, we’ll explore how to delete Git branches.

2. Preparation of the Git Repository

To easier address how to delete a Git branch, let’s first prepare a Git repository as an example.

First, let’s clone the myRepo repository (https://github.com/sk1418/myRepo) from GitHub for testing:

$ git clone [email protected]:sk1418/myRepo.git
Cloning into 'myRepo'...
...
remote: Total 6 (delta 0), reused 3 (delta 0), pack-reused 0
Receiving objects: 100% (6/6), done

Second, let’s enter the local myRepo directory and check the branches:

$ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master

As we can see from the output above, currently, we have only one master branch in the myRepo repository. Also, the master branch is myRepo‘s default branch.

Next, let’s create some branches and show how to delete a branch locally and remotely. In this tutorial, we’ll focus on deleting branches in the command line.

3. Deleting a Local Branch

Let’s first have a look at deleting a local branch.

Git’s git branch command has two options for deleting a local branch: -d and -D.

Next, let’s take a closer look at them and understand the difference between these two options through an example.

3.1. Deleting a Local Branch With the -d Option

First, let’s try to create a local branch:

$ git checkout -b feature
Switched to a new branch 'feature'

Next, let’s delete the feature branch using the -d option:

$ git branch -d feature
error: Cannot delete branch 'feature' checked out at '/tmp/test/myRepo'

Oops, as we can see, we’ve got an error message. This is because we’re currently on the feature branch:

$ git branch
* feature
  master

In other words, we cannot delete a currently checked-out branch. So, let’s switch to the master branch and fire the command again:

$ git checkout master
Switched to branch 'master'
Your branch is up to date with 'origin/master'.
$ git branch -d feature
Deleted branch feature (was 3aac499)

$ git branch -a
* master
remotes/origin/HEAD -> origin/master
remotes/origin/master

As we can see, we’ve deleted the local feature branch successfully.

3.2. Deleting a Local Branch With the -D Option

First, let’s create the feature branch again. But this time, we’re going to make some changes and commit it:

$ git checkout -b feature
Switched to a new branch 'feature'

# ... modify the README.md file ...
$ echo "new feature" >> README.md
$ git status
On branch feature
Changes not staged for commit:
...
	modified:   README.md

no changes added to commit (use "git add" and/or "git commit -a")

$ git ci -am'add "feature" to the readme'
[feature 4a87db9] add "feature" to the readme
 1 file changed, 1 insertion(+)

Now, Git will refuse to delete the feature branch if we still use the -d option:

$ git checkout master
Switched to branch 'master'
Your branch is up to date with 'origin/master'.

$ git branch -d feature
error: The branch 'feature' is not fully merged.
If you are sure you want to delete it, run 'git branch -D feature'.

This is because the to-be-deleted branch (feature) is ahead of the default branch (master):

$ git log --graph --abbrev-commit 
* commit 4a87db9 (HEAD -> feature)
| Author: ...
| Date:   ...| 
|     add "feature" to the readme
| 
* commit 3aac499 (origin/master, origin/HEAD, master)
| Author: ...
| Date:   ...| 
|     the first commit
| 
* commit e1ccb56
  Author: ...
  Date:   ...  
      Initial commit

There are two ways to solve the problem. First, we can merge the feature branch into master and then execute “git branch -d feature” again.

However, if we want to discard the unmerged commits, as the error message suggested, we can run “git branch -D feature” to execute a force deletion:

$ git branch -D feature
Deleted branch feature (was 4a87db9)

$ git branch -a
* master
remotes/origin/HEAD -> origin/master
remotes/origin/master.

3.3. git branch -d/-D Won’t Delete the Remote Branch

So far, we’ve deleted a local branch using git branch with the -d and -D options. It’s worth mentioning that no matter whether we delete with -d or -D, this command will only remove the local branch. No remote branch will be deleted, even if the deleted local branch is tracking a remote branch.

Next, let’s understand this through an example. Again, let’s create a feature branch, make some changes, and push the commit to the remote repository:

$ git checkout -b feature
Switched to a new branch 'feature'

# add a new file
$ echo "a wonderful new file" > wonderful.txt

$ git add . && git ci -am'add wonderful.txt'
[feature 2dd012d] add wonderful.txt
 1 file changed, 1 insertion(+)
 create mode 100644 wonderful.txt
$ git push
...
To github.com:sk1418/myRepo.git
 * [new branch]      feature -> feature

As the output above shows, we’ve created a new file, wonderful.txt, on the feature branch and pushed the commit to the remote repository.

Therefore, the local feature branch is tracking the remote feature branch:

$ git remote show origin | grep feature
    feature tracked
    feature pushes to feature (up to date)

Since we haven’t merged feature into master, let’s delete the local feature branch with the -D option:

$ git checkout master
Switched to branch 'master'
Your branch is up to date with 'origin/master'.

$ git branch -D feature
Deleted branch feature (was 2dd012d).

$ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/feature
  remotes/origin/master

As we can see in the output of the command git branch -a, the local feature branch is gone. But the /remotes/origin/feature branch is not removed.

Now, if we check out the feature branch again, the changes we’ve made are still there:

$ git checkout feature
Switched to branch 'feature'
Your branch is up to date with 'origin/feature'.
$ cat wonderful.txt 
a wonderful new file

Next, let’s see how to remove a remote branch.

4. Deleting a Remote Branch

We can use the command git push origin :<branchName> to remove a remote branch if our Git version is before 1.7.0. However, this command doesn’t look like a deletion operation. Therefore, since version 1.7.0, Git has introduced the git push origin -d <branchName> command to delete a remote branch. Apparently, this command is easier to understand and memorize than the older version.

Just now, we’ve deleted the local branch feature, and we’ve seen that the remote feature branch is still there. So now, let’s use the mentioned command to remove the remote feature branch.

Before we delete the remote feature, let’s first create a local feature branch to track the remote one. This is because we want to check if removing a remote branch will impact the tracking of local branches:

$ git checkout feature 
branch 'feature' set up to track 'origin/feature'.
Switched to a new branch 'feature'
$ git branch -a
* feature
  master
  remotes/origin/HEAD -> origin/master
  remotes/origin/feature
  remotes/origin/master

So, now we have the local and remote feature branches. Further, we’re currently on the local feature branch.

Next, let’s remove the remote feature branch:

$ git push origin -d feature
To github.com:sk1418/myRepo.git
 - [deleted]         feature
$ git branch -a
* feature
  master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master

As we can see, after we execute the git push -d feature command, the remote feature branch has been deleted. However, the local feature branch is still there. That is to say, deleting a remote branch won’t impact the local tracking branches. Therefore, if we launch git push now, the local feature branch will be pushed to remote again.

Moreover, unlike the local branch deletion, we can delete a remote branch no matter which local branch we’re currently working on. In the example above, we’re on the local feature branch, but we can still remove the remote feature branch without any problem.

5. Conclusion

In this article, we’ve explored how to delete Git’s local and remote branches using commands.

Let’s summarize them quickly:

  • Delete a local branch: git branch -d/-D <branchName> (the -D option is for force deletion)
  • Delete a remote branch: git push origin -d <branchName> or git push origin :<branchName>

Also, we’ve understood that removing a branch on a local or remote will not impact the branches on the other side.

Comments are open for 30 days after publishing a post. For any issues past this date, use the Contact form on the site.