With Git LFS, what does git lfs prune delete, and what keeps a local object from being pruned?
answer
- local store only
- the fetch window plus an offset
- unpushed objects are never deleted
- one remote judges what was pushed
basics
~20 sgit lfs prune deletes local copies in the LFS store that nothing current needs. It keeps objects for the checkout, stashes, worktrees, unpushed commits and recent branches, widened by lfs.pruneoffsetdays. It never frees server storage.
solid answer
~40 s`git lfs prune` touches only the local LFS store, usually `.git/lfs/objects`. It keeps any object referenced by the current checkout, a stash, another worktree, an unpushed commit, or a recent branch or commit. Recent reuses the fetch settings: `lfs.fetchrecentrefsdays` (default 7) and `lfs.fetchrecentcommitsdays` (default 0), plus `lfs.pruneoffsetdays` (default 3), so the tips of branches with commits in the last 10 days survive. Pushed is judged against one remote, `origin` by default or `lfs.pruneremotetocheck`; if it does not exist, nothing is pruned. `--dry-run` reports first, and `--verify-remote` makes prune confirm with the server that copies exist before deleting. Nothing on the server changes.
code
bash · 4 linesgit config lfs.fetchrecentrefsdays 14 # keep two weeks of branches
git config lfs.pruneoffsetdays 3
git lfs prune --dry-run --verbose # see what would go
git lfs prune --verify-remote # delete, confirming server copies firstgo deeper
Know that git lfs prune frees local disk space only and that it never deletes an object you have not pushed.
Explain the list prune keeps (checkout, stashes, worktrees, unpushed and recent objects) and how the fetch recent settings define recent.
Tune the recent window for how the team actually switches branches, use --dry-run and --verify-remote, and know the shared-storage and reference-remote traps.
Balance local disk pressure on workstations and build agents against re-download bandwidth, and set team defaults rather than per-person habits.
## What prune is for Every object Git LFS downloads or creates is kept in the **local LFS store**, usually `.git/lfs/objects`. Over months of switching branches in a binary-heavy repository, that store grows to many times the size of the current checkout. `git lfs prune` deletes local copies that nothing current needs. It works only on **your machine**: it never deletes anything on the LFS server, and it does not change your host's storage usage. ## What prune keeps Prune lists every locally stored object and deletes those not referenced by at least one of: - the **current checkout**; - any **stash**; - a **recent branch** (see below); - a **recent commit** on the current branch or a recent branch; - a commit that has **not been pushed**; - the checkout of any other **worktree**. The **reflog** is not considered, so objects referenced only by orphaned commits are deleted. ## The recent window "Recent" reuses the settings that `git lfs fetch --recent` uses, widened by an offset so that something you fetched is not deleted the moment it stops being recent: | Setting | Default | Role in prune | |---|---|---| | `lfs.fetchrecentrefsdays` | 7 | branches with commits in this many days count as recent | | `lfs.fetchrecentremoterefs` | true | remote-tracking branches count as well as local ones | | `lfs.fetchrecentcommitsdays` | 0 | older commits on recent branches are kept too (0 = not used) | | `lfs.pruneoffsetdays` | 3 | extra days added to the windows above before anything is prunable | With the defaults, a branch whose latest commit is up to 10 days old keeps the objects at its **tip**. Because `lfs.fetchrecentcommitsdays` is 0, older versions on that branch are not protected by recency. A day value of 0 disables that condition entirely. Worked through: 1. You check out `main`; its objects stay because they are the current checkout. 2. `feature/harbor` had a commit 9 days ago; its tip's objects stay (7 + 3 = 10). 3. `feature/old-ui` last changed 20 days ago; its objects go, and checking it out later downloads them again. ## Pushed versus unpushed An object whose only copy is local and still reachable is **never** pruned, whatever its age. Prune decides what is pushed by comparing local refs with one **reference remote**: `origin` by default, or the remote named in `lfs.pruneremotetocheck`. If that remote does not exist, nothing is pruned, because everything counts as unpushed. This relies on the LFS pre-push hook always uploading objects before the remote branch moves. ## Safer pruning - `git lfs prune --dry-run --verbose` reports what would be deleted. - `--verify-remote` (or `lfs.pruneverifyremotealways`) asks the server to confirm copies of reachable objects exist before deleting them; `--when-unverified=continue` keeps going when some cannot be verified, instead of halting. - `git lfs fetch --prune` fetches and then prunes in one step. - `--recent` ignores the recent window; `--force` prunes everything except unpushed objects, including the current checkout's. - Paths listed in `lfs.fetchexclude` are pruned unless a stash or an unpushed commit needs them. ## Prune on build agents Build agents with persistent workspaces are where local stores grow fastest: every branch a pipeline builds leaves its objects behind. - Run `git lfs prune` on a schedule, or `git lfs fetch --prune` in the job, so each workspace keeps roughly what recent builds need. - On agents, a shorter window is usually fine; lowering `lfs.fetchrecentrefsdays` there trades disk for occasional re-downloads. - Remember the bandwidth side: an object pruned today and needed tomorrow is downloaded again and metered again on hosts that bill bandwidth. - Never point several agent workspaces at one shared `lfs.storage` directory and prune it from one of them. ## What prune does not do - It does not reduce the **server's** storage. Hosts keep objects after files are deleted from history; reclaiming that space is a host operation. - It must not run when several repositories share one custom store set with `lfs.storage`; prune in one repository would delete objects the others still need. - It does not replace backing up work: the only guarantee for an unpushed object is that prune skips it.
- Why might prune delete objects for a branch you checked out two weeks ago?With defaults, a branch counts as recent only if it had a commit within 7 days, plus the 3-day prune offset. A branch idle for two weeks is outside that window and not checked out, so objects referenced only by it are prunable. Checking it out again downloads them, costing bandwidth. Raise `lfs.fetchrecentrefsdays` if the team switches between long-lived branches.
- When is running git lfs prune risky?When several repositories share one custom store via `lfs.storage`, because prune in one deletes objects the others need. Also when work lives only in orphaned commits, since the reflog is not considered. If you doubt the remote really has your objects, add `--verify-remote`.
- What does git lfs fetch --prune do?It fetches as usual and then runs prune, equivalent to `git lfs fetch` followed by `git lfs prune`, with the same retention rules.
- git lfs prune deletes old LFS objects from the server to save hosted storage.
- Prune can delete an object whose only copy is in a commit you have not pushed.
- lfs.pruneoffsetdays on its own decides how long objects are kept.
- Prune treats commits kept alive by the reflog as in use.
- Without an origin remote, prune deletes everything not checked out.