Remote branches and cleanup

Why this matters

A branch that has been merged has done its job. Left in place, it joins the hundreds of others in the branch dropdown, and nobody can tell which are alive. Cleaning up is three seconds of work, but it involves three separate copies of the same branch, and knowing which command removes which is what stops people from either leaving debris or deleting something they still needed.

Three copies of one branch

After you publish a branch, the name exists in three places (lesson 6.4):

Deleting one does not touch the others, which is exactly why branch lists fill up with names that no longer exist anywhere real.

Deleting after a merge

$ git push origin --delete docs/12-windows-install-steps

To https://gitlab.com/northwind-trails/trailguide.git
 - [deleted]         docs/12-windows-install-steps

$ git branch -d docs/12-windows-install-steps

Deleted branch docs/12-windows-install-steps (was 5f181fc).

Both GitLab and GitHub can do the remote half for you: a merge request has a Delete source branch checkbox, ticked by default on most projects, so in practice you often only run the local delete.

The safe delete refuses when the commits are not in another branch:

$ git branch -d feature/21-difficulty-filter

error: the branch 'feature/21-difficulty-filter' is not fully merged
hint: If you are sure you want to delete it, run 'git branch -D feature/21-difficulty-filter'
hint: Disable this message with "git config set advice.forceDeleteBranch false"

Two situations produce this, and they need opposite responses:

• The branch was squash-merged. main has the change but not those commits, so Git cannot see the merge. -D is correct.
• The branch was never merged. -D abandons the work. Check first.

The check is one command:

$ git branch --merged

* main

$ git branch --no-merged

  fix/15-empty-distance

--merged lists branches whose commits are already in the branch you are on, so they are safe to delete; --no-merged lists the rest. Run them from main after pulling.

Stale bookmarks

Colleagues merge and delete their branches all day. Your clone keeps the bookmarks until you tell it otherwise:

$ git branch -r

  origin/HEAD -> origin/main
  origin/docs/40-temp
  origin/main

origin/docs/40-temp no longer exists on the server. Clearing it out:

$ git fetch --prune

From https://gitlab.com/northwind-trails/trailguide
 - [deleted]         (none)     -> origin/docs/40-temp

$ git branch -r

  origin/HEAD -> origin/main
  origin/main

Pruning only removes bookmarks for branches that are gone from the remote; it never touches your local branches or any commit. Set fetch.prune true once (lesson 3.5) and every fetch and pull cleans up by itself.

To see the whole picture at once, including which branches are stale:

$ git remote show origin

* remote origin
  Fetch URL: https://gitlab.com/northwind-trails/trailguide.git
  Push  URL: https://gitlab.com/northwind-trails/trailguide.git
  HEAD branch: main
  Remote branch:
    main tracked
  Local branch configured for 'git pull':
    main merges with remote main
  Local ref configured for 'git push':
    main pushes to main (up to date)

How to do it

$ git switch main && git pull
$ git branch --merged
$ git branch -d docs/12-windows-install-steps
$ git push origin --delete docs/12-windows-install-steps
$ git fetch --prune

Common mistakes

• Deleting the local branch and leaving the remote one. The name stays in everyone's dropdown forever. Use the merge request checkbox or git push origin --delete.
• -D without checking. Confirm with git branch --no-merged or by finding the change in main; on a squash-merged branch -D is right, on an abandoned one it discards work (recoverable for a while through the reflog).
• git branch -a still listing a colleague's deleted branch. That is a stale bookmark, not a branch. Prune.
• Trying to delete the branch you are on. Git refuses; switch to main first.