How to Delete a Git Branch Locally and Remotely

Introduction to Git Branches

Git is a powerful version control system that enables developers to track changes in their codebase efficiently. Git branches are separate lines of development that diverge from the main codebase, enabling developers to work on features or fixes without affecting the main codebase.

There are two types of branches in Git: local branches and remote branches. Local branches only exist on our local machine, whereas remote branches exist on a remote repository hosted on a Git hosting platform, such as GitHub, GitLab, or Bitbucket.

Sometimes, we may no longer need certain branches in a repository. Deleting these branches can help keep the repository organized and uncluttered. Think of deleting a branch, like cleaning up old documents from your desk. It keeps things organized and makes it easier to focus on what’s important.

In this article, we’ll discuss how to delete a branch in Git, covering both local and remote branch deletion. Whether you need to delete locally or remove branches from your remote repository, we’ll guide you through each step.

Let’s first look at the process of deleting a branch locally in Git.

How to Delete a Branch Locally in Git

When we need to delete a Git branch locally, we have several options available. The most common commands for Git branch deletion are git branch -d and git branch -D. Let’s explore how to use these commands effectively.

To delete a local branch in Git, we use the git branch -d command. This command deletes the specified branch on our local machine. Here’s the syntax for it:

git branch -d <branch_name>

Here, branch-name is the name of the branch that we want to delete.

Since the -d flag is the shortened form of the --delete flag, the syntax can be alternatively written as:

git branch --delete <branch_name>

One thing to note is that the git branch -d command prevents us from deleting a local branch if it has unmerged changes, i.e., commits that don’t exist on the default branch (main, master, etc.).

If we want to force delete a local branch in Git, regardless of whether it has unmerged changes or not, we can use the git branch -D command. Since this command removes the branch completely, we must ensure that we no longer need the branch before performing the operation:

git branch -D <branch_name>

Now, follow the steps mentioned to understand how to delete a local branch using the git branch -d command.

Firstly, fork or make a personal copy of the docs repository:

Ensure that you uncheck the Copy the main branch only option to include all the remote branches from the repository, not just the main (default) branch in the forked repository. Unchecking this option ensures all remote branches are available in the forked repository to demonstrate remote branch deletion in Git:

Then, go to the forked docs repository, click on the Code dropdown, and copy the link to the repository:

After that, open the terminal on your computer and utilize the git clone command to clone the forked repository:

git clone https://github.com/<username>/forked_repository_name.git

Once cloned, navigate to the cloned repository:

cd docs

Now, before we learn how to delete a local branch, we need to create one first in the cloned repository. So, let’s create a branch named test1 using the git branch command in the terminal:

git branch test1

Next, we can delete the newly created test1 branch using the git branch -d command. This command is a shorthand for the git branch --delete:

git branch -d test1

Alternatively, we can use the following command:

git branch --delete test1

After we successfully delete the branch, we will receive the following output:

Deleted branch test1

Since there are no commits in the test1 branch that are not in the default (main) branch, the branch is successfully deleted.

However, the operation would have failed if there were unique commits in the test1 branch. In that case, we can force a delete by using the git branch -D command:

git branch -D test1

Potential Errors and Their Solutions

While deleting local branches, there are some potential errors that can occur. Let’s see what they are and how to solve them.

‘Branch Not Found’ Error

One of the most common errors we can face while we delete a Git branch locally is the ‘Branch not found’ error. This error occurs when the branch name is spelled wrong. So, we need to ensure that we spell the branch name correctly.

To avoid such errors, verify the branch name by listing all branches using the following command:

git branch

Failure to Delete the Current Branch

Git doesn’t allow us to delete the branch we’re currently on. We first need to move to another branch and then delete the original branch.

Let’s take the test1 branch, for example. If we’re currently on this branch, we first need to move to another branch (say main) using the git switch command:

git switch main

Then, you can delete the test1 branch:

git branch -d test1

In the next section, we’ll discuss how to delete a branch remotely in Git.

How to Delete a Branch Remotely in Git

Before we look at the process of deleting a remote branch in Git, let’s discuss some common reasons as to why we should be deleting branches remotely.

When to Delete Remote Branches

Scenario 1: If we’ve merged all the changes from a remote branch to the default branch, it indicates that we don’t need that branch anymore, and we can delete it to clean up our repository.

Scenario 2: If we haven’t updated a remote branch for a long time, then we can consider it stale or inactive. In this case, we can delete the branch to keep our repository organized.

Scenario 3: If we no longer need a remote branch because of modifications in the project requirements, then we can delete it to clean up our repository.

Deleting a Branch Remotely in Git

The git push -d command allows us to delete a remote branch in Git. Here is the syntax for it:

git push remote -d <branch_name>

Here, remote is the remote repository that contains the branch to be deleted and branch-name is the name of the branch itself.

Just like the git branch -d command, git push -d can be alternatively written as:

git push remote --delete branch

Now, follow the steps mentioned to understand how to delete a remote branch using the git push -d command.

Firstly, fetch all the remote branches that exist on the forked docs repository using the git fetch command:

git fetch origin

Here, origin is an alias that replaces the link to the forked docs repository. Git automatically sets this when we enter the cloned repository for the first time.

Next, check the fetched remote branches using the git branch -r command:

git branch -r

Here is a sample output:

origin/HEAD -> origin/main
origin/main
origin/Aireon_Adding_Substring
origin/PyTorch-Tensors-.mean()
origin/agraves.test-branch
origin/cppentry
origin/dotnet
origin/full
...

Now, for instance, if we want to delete the cppentry remote branch, we can use the git push -d command:

git push origin -d cppentry

Alternatively, we can use the following command:

git push origin --delete cppentry

The following output confirms that the remote branch is successfully deleted:

- [deleted]  cppentry

Concept Review and Next Steps

In this article, we explored the commands that allow us to delete a branch locally and remotely in Git, respectively. By understanding these commands, we can eliminate unnecessary branches, keep our repository clean and organized, and improve efficiency.

To learn more about Git, check out How to Use Git for Beginners on Codecademy.