Git delete branch - Are you doing it correctly?

There can be a couple of scenarios wherein you would wish to delete branch. Following are some of the possible scenarios:

  1. Delete git branch locally
  2. Delete git branch remotely
  3. Delete git branch both locally and globally
  4. Perform git merge and Delete git branch

We will cover all these scenarios individually with the best recommendation to do this the right way.

Advertisement

 

Prepare Environment

I have setup my repository git_examples using GitLab.

Following is my git version:

deepak@ubuntu:~/git_examples$ git --version
git version 2.32.0

I will clone my repository from gitlab to my local workstation:

deepak@ubuntu:~/git_examples$ git clone git@gitlab.com:golinuxcloud/git_examples.git

 

Git delete branch locally

If your branch is only available on your local workstation repository then you must follow this section. Currently I have following branch in the local repository of my workstation:

deepak@ubuntu:~/git_examples$ git branch
  issue-5632
  issue-6291
  issue-9538
* main
  my-feature-branch

To check the list of remote branches (i.e. branch which are available on the remote gitlab server):

deepak@ubuntu:~/git_examples$ git branch --remotes
  origin/HEAD -> origin/main
  origin/main
  origin/my-feature-branch

So the following branch are only present on my local workstation only but not on the remote:

Advertisement
  issue-5632
  issue-6291
  issue-9538

Since these branches are not available on remote, so I just need to delete them locally.

 

Scenario-1: Fix error: Cannot delete branch 'XXX' checked out at 'YYY'

To delete a branch locally use the following command syntax:

git branch --delete|-d <local_branch_name>

First step, make sure you are not part of the branch which you wish to delete or else you will get this error:

deepak@ubuntu:~/git_examples$ git switch issue-6291
Switched to branch 'issue-6291'

deepak@ubuntu:~/git_examples$ git branch --delete issue-6291
error: Cannot delete branch 'issue-6291' checked out at '/home/deepak/git_examples'

As you can see, I switched to issue-6291 branch and then trying to delete the same branch leads to an ERROR.

So to delete the branch, you must checkout as a different branch first.

deepak@ubuntu:~/git_examples$ git switch main
Switched to branch 'main'
Your branch is ahead of 'origin/main' by 2 commits.
  (use "git push" to publish your local commits)

Check your current branch:

deepak@ubuntu:~/git_examples$ git branch
  issue-5632
  issue-6291
  issue-9538
* main
  my-feature-branch

Now try to delete your branch:

deepak@ubuntu:~/git_examples$ git branch --delete issue-6291
Deleted branch issue-6291 (was e126b0b).

 

Scenario-2: Fix error: The branch 'XXX' is not fully merged.

Let us try to delete another of our local branch:

Advertisement
deepak@ubuntu:~/git_examples$ git branch --delete issue-5632
error: The branch 'issue-5632' is not fully merged.

If you are sure you want to delete it, run 'git branch -D issue-5632'. This error is caused because we have some un-merged changes in branch issue-5632 due to which the branch delete has failed.

In such case either you can delete the branch forcefully or merge the changes and then perform the delete operation.

 

Solution-1: Perform merge and delete git branch

I will push these changes to a new branch issue-5632 on the remote gitlab server.

deepak@ubuntu:~/git_examples$ git push origin issue-5632
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (4/4), 319 bytes | 159.00 KiB/s, done.
Total 4 (delta 1), reused 0 (delta 0), pack-reused 0
remote:
remote: To create a merge request for issue-5632, visit:
remote:   https://gitlab.com/golinuxcloud/git_examples/-/merge_requests/new?merge_request%5Bsource_branch%5D=issue-5632
remote:
To gitlab.com:golinuxcloud/git_examples.git
 * [new branch]      issue-5632 -> issue-5632

This will create a merge request with main branch and will also create a new branch on the remote server.

To merge this into main branch, switch to main branch:

deepak@ubuntu:~/git_examples$ git switch main
Switched to branch 'main'
Your branch is ahead of 'origin/main' by 2 commits.
  (use "git push" to publish your local commits)

Check your current branch

deepak@ubuntu:~/git_examples$ git branch
  issue-5632
  issue-9538
* main
  my-feature-branch

Merge issue-5632 branch into main

deepak@ubuntu:~/git_examples$ git merge issue-5632
Updating e126b0b..cf00196
Fast-forward
 test-5632/patch-1 | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 test-5632/patch-1

Verify the git log to confirm the merge:

deepak@ubuntu:~/git_examples$ git log --oneline
cf00196 (HEAD -> main, origin/issue-5632, issue-5632) Added patch-1
e126b0b (origin/my-feature-branch, my-feature-branch, issue-9538) Adding new group
5e04f57 Created new script to add groups
1b6369c (origin/main, origin/HEAD) Added create_users.sh script
6297a37 Updated script2.sh in main branch
...

Now you can go ahead and delete the local branch:

deepak@ubuntu:~/git_examples$ git branch --delete issue-5632
Deleted branch issue-5632 (was cf00196).
NOTE:

At this stage we have created a branch issue-5632 on the remote gitlab server as well which will still be present and need to be handled separately. We will cover this in next section of this article.

 

Solution-2: Forcefully delete local branch

If you do not wish to merge your changes, then you can forcefully delete the branch locally using --delete --force or -D:

So you can use:

git branch --delete --force <branch_to_be_deleted>

OR

git branch -D <branch_to_be_deleted>

 

Git delete branch remotely

To delete a branch from the remote, use any of the following syntax:

git push origin --delete <branch>   # Git version 1.7.0 or newer
git push origin -d <branch>         # Shorter version (Git 1.7.0 or newer)
git push origin :<branch>           # Git versions older than 1.7.0

Following are the list of remotely available branches on my gitlab server:

deepak@ubuntu:~/git_examples$ git branch --remotes
  origin/HEAD -> origin/main
  origin/issue-5632
  origin/main
  origin/my-feature-branch

These are the list of locally available branch:

deepak@ubuntu:~/git_examples$ git branch
* issue-9538
  main
  my-feature-branch

 

Scenario-1: When branch is available only on the remote (not locally)

Since, issue-5632 branch is available only on the remote server as we have already deleted it on the local repo. To delete this branch also from the remote we will use:

deepak@ubuntu:~/git_examples$ git push origin --delete issue-5632
To gitlab.com:golinuxcloud/git_examples.git
 - [deleted]         issue-5632

Verify the list of branch on the remote to make sure your branch was deleted successfully:

deepak@ubuntu:~/git_examples$ git branch --remotes
  origin/HEAD -> origin/main
  origin/main
  origin/my-feature-branch

 

Scenario-2: When there are un-merged changes locally

I have pushed issue-9538 to the remote gitlab server, so now this branch is also available on the remote:

deepak@ubuntu:~/git_examples$ git branch --remotes
  origin/HEAD -> origin/main
  origin/issue-9538
  origin/main
  origin/my-feature-branch

I will commit some changes into this branch, but will not merge it with main branch:

deepak@ubuntu:~/git_examples$ git branch
* issue-9538
  main
  my-feature-branch

deepak@ubuntu:~/git_examples$ git add bugs/patch-9538

deepak@ubuntu:~/git_examples$ git commit -m "added patch for #9538" -a
[issue-9538 d850184] added patch for #9538
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 bugs/patch-9538

Let's try to delete this branch on the remote repo server:

deepak@ubuntu:~/git_examples$ git push origin --delete issue-9538
To gitlab.com:golinuxcloud/git_examples.git
 - [deleted]         issue-9538

So, even though I was in issue-9538 branch and there were un-merged changes, but still the remote branch was successfully deleted. So these factors do not matter if we wish to delete remote branch.

With this step, the remote branch has been deleted but the local branch is still there along with the un-merged changes:

deepak@ubuntu:~/git_examples$ git branch
* issue-9538
  main
  my-feature-branch

So we must delete this branch locally as explained in section one of this article.

 

Delete git branch both locally and remotely

We have covered this topic separately, now lets understand the flow which should be followed when trying to delete a branch from both local and remote git server.

In my case my-feature-branch is available on both local and remote git server:

deepak@ubuntu:~/git_examples$ git branch
* issue-9538
  main
  my-feature-branch

 

Step-1: Switch to alternate branch

Make sure you are on a different branch and not in the one you plan to delete. To switch your branch you can use:

git checkout <different_branch>

OR

git switch <different_branch>

Since we are already on a different branch, we will ignore this step.

 

Step-2: Delete branch on the remote

Next we will delete the branch on the remote server first:

deepak@ubuntu:~/git_examples$ git push origin --delete my-feature-branch
To gitlab.com:golinuxcloud/git_examples.git
 - [deleted]         my-feature-branch

As you can verify, now my-feature-branch is deleted from remote but is still available locally:

deepak@ubuntu:~/git_examples$ git branch --all
* issue-9538
  main
  my-feature-branch
  remotes/origin/HEAD -> origin/main
  remotes/origin/main

 

Step-3: Delete branch locally

Now we can delete our branch locally. Since the remote branch is already deleted, we can safely use --delete --force or -D to perform a force delete of the git branch:

deepak@ubuntu:~/git_examples$ git branch --delete --force my-feature-branch
Deleted branch my-feature-branch (was e126b0b).

Verify the list of branch:

deepak@ubuntu:~/git_examples$ git branch --all
* issue-9538
  main
  remotes/origin/HEAD -> origin/main
  remotes/origin/main

 

Step-4: Pruning the obsolete local remote-tracking branch

Note that deleting X remote branch from the command line using a git push will also remove the local remote-tracking branch origin/X, so it is necessary to prune the obsolete remote-tracking branch with git fetch --prune or git fetch -p.

deepak@ubuntu:~/git_examples$ git switch main
Switched to branch 'main'

Perform a fetch on other machines after deleting remote branch, to remove obsolete tracking branches.

deepak@ubuntu:~/git_examples$ git fetch --all --prune
Fetching origin

 

Summary

In this article we discussed in depth about different commands using which you can delete git branch both locally and remotely. You can safely remove a branch with git branch -d yourbranch. If it contains unmerged changes (ie, you would lose commits by deleting the branch), git will tell you and won't delete it.

To delete a remote branch, use git push origin :mybranch, assuming your remote name is origin and the remote branch you want do delete is named mybranch.

 

Further Readings

git branch

Didn't find what you were looking for? Perform a quick search across GoLinuxCloud

If my articles on GoLinuxCloud has helped you, kindly consider buying me a coffee as a token of appreciation.

Buy GoLinuxCloud a Coffee

For any other feedbacks or questions you can either use the comments section or contact me form.

Thank You for your support!!

Leave a Comment