Please note this post details how to permanently delete branches from Git - make sure you’re comfortable/confident in doing this!
Gitlab has a big red button in the repository branch list to Delete merged branches
which prompts you to be really sure you want to delete them, because there’s no way back.
Unfortunately if you have a backlog of stale branches - say, 500 - then you might be a little nervous about hitting this button…just in case.
Instead of having to click through 25 pages of branch listings, we can use the Gitlab API to pull out our branches, pipe them through jq
and pick out the branches we want to delete. Branches can then be deleted from the git CLI and hopefully the branch backlog starts to get a little clearer.
You’ll need a couple of things to get started:
- Personal Access Token to pass through the API - find it via the “Access Token” submenu from your “Settings” page (find this by clicking your profile menu in the top right). The token needs to have
api
permissions - Project ID for the project with the stale branches. This is shown
Project ID: NNNNNNNN
at the top of your repo’s front page or in “Settings > General” - Something to submit the API request and save the JSON response(s)
- The
jq
utility to query the data - Git CLI to push branch deletions
Getting your branch list by API
It’s quite straight forward, but there’s a limit on how many branches are returned so you need to page through the results (the API returns Link
fields in the header).
Using the Branch endpoint you can get your branch list with the following
100 seems to be the largest set we can get back, so inspect your Link
field in the header to see how many you need to get and increment the page
URL accordingly. For demonstration purposes, the JSON bodies of these requests can be saved to response-N.json
where N
is the page number.
Merging the JSON files
The jq
tool can happily merge files:
…Will merge the contents of each response array and put them into a single array under all.json
. This makes it a bit easier to to query out.
Extracting the relevant fields
Because we’re looking to purge out really stale branches, we’ll pull out the branch name and committed date so we can sort the list
This will create a list of oldest branches first - commit date and name separated by a comma. You can even add on a | pbcopy
pipe if you’re on Mac and ready to paste these elsewhere.
Analysing stale branches
I’ve simply pasted these into a spreadsheet, split the text into columns and confirmed the dates and branches of names I want to delete. You can add a handy third column to generate the git command for you.
This should yield a command git push origin --delete feature/name
. Running this git command in your repo/directory will trigger a remote delete of the branch and you’re on your way to cleaning up your stale branch backlog.