How to Delete Remote Git Branch

Deleting branches in Git is easy when it's a local branch:

git branch -d <branch-name>

But it's not the same case if you want to delete a remote branch.

Let me show the steps for deleting a remote Git branch.

Show remote branches

To see all the branches in a remote Git repository, you can use the -a flag like so:

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

This is the output of running git branch -a in a cloned repository of dust.

Let's break this down...

• remotes means a repository on a remote server (like GitLab, Gitea or GitHub)
• origin is an alias on your system for the remote repository
• HEAD is the default branch that gets cloned if you do not explicitly specify a branch

So, in the 4th line, remotes/origin/HEAD -> origin/master, means that the 'default' remote repository is the master branch.

And the last two lines mean that there are two branches in the remote repository, which are master and test-lhb.

Another way to see information about remote repositories is to use the git remote command as given below.

$ git remote show origin
* remote origin
  Fetch URL: [email protected]:atheistd/linuxhandbook.git
  Push  URL: [email protected]:atheistd/linuxhandbook.git
  HEAD branch: master
  Remote branches:
    master   tracked
    test-lhb tracked
  Local branches configured for 'git pull':
    master   merges with remote master
    test-lhb merges with remote test-lhb
  Local refs configured for 'git push':
    master   pushes to master   (up to date)
    test-lhb pushes to test-lhb (up to date)

This gives you an even verbose output. To use git remote over git branch depends on your preference and use case.

Deleting remote git branch

The -d (or -D for a forced delete) flag is used with git branch command to delete a local branch.

But, to delete a branch from a remote repository, the git branch command will not work.

To delete a remote Git branch, use the git push command with the following syntax:

$ git push origin --delete test-lhb
To github.com:atheistd/linuxhandbook.git
 - [deleted]         test-lhb

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

Look closely. Running the git push command to delete the remote Git branch did not remove our local branch.

Deleting the HEAD branch

The HEAD branch is an alias for the default branch. In most repositories, it is set to the master branch or to the main branch.

Let's try deleting the main remote branch...

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

$ git push origin --delete master
To github.com:atheistd/linuxhandbook.git
 ! [remote rejected] master (refusing to delete the current branch: refs/heads/master)
error: failed to push some refs to 'github.com:atheistd/linuxhandbook.git'

Since we tried deleting the master branch, it gave us an error and did not delete the remote Git branch.

Now you know how to delete a remote Git branch and also that Git will prevent you from deleting the HEAD if it points to your master or main branch.