git remote prune: Usage, Options & Common CI Errors

By Kaveh Alemi·Latchkey

git remote prune removes the local stand-ins for branches that were deleted on the remote.

After PRs merge and branches are deleted upstream, your origin/* refs go stale. Pruning keeps branch listings and ref iterations honest in long-lived caches and CI workspaces.

What it does

git remote prune deletes remote-tracking references under refs/remotes/<remote>/ that no longer have a corresponding branch on the remote. It does not touch local branches or remote data.

Common usage

git remote prune origin
git remote prune --dry-run origin
# equivalent during a fetch:
git fetch --prune origin

Options

Common errors in CI

Pruning only removes remote-tracking refs, not your local branches - a local branch whose upstream vanished still lingers and may show "gone" in git branch -vv. Use git fetch --prune to refresh and prune in one step; --dry-run first if a script deletes based on the output.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

Related guides

References

• GitHub Actions documentation