- Delete old LFS files from local storage
git lfs prune options
Deletes local copies of LFS files which are old, thus freeing up disk space.
Prune operates by enumerating all the locally stored objects, and then
deleting any which are not referenced by at least ONE of the following:
- the current checkout
- a ´recent branch´; see RECENT
- a ´recent commit´ on the current branch or
recent branches; see RECENT FILES
- a commit which has not been pushed; see UNPUSHED LFS
- any other worktree checkouts; see git-worktree(1)
In general terms, prune will delete files you´re not currently using and
which are not ´recent´, so long as they´ve been pushed
i.e. the local copy is not the only one.
The reflog is not considered, only commits. Therefore LFS objects that are only
referenced by orphaned commits are always deleted.
Note: you should not run git lfs prune
if you have different repositories
sharing the same custom storage directory; see git-lfs-config(1) for more
details about lfs.storage
- --dry-run -d Don´t actually delete
anything, just report on what would have been done
- --verify-remote -c Contact the remote and
check that copies of the files we would delete definitely exist before
deleting. See VERIFY REMOTE.
- --no-verify-remote Disables remote verification if
lfs.pruneverifyremotealways was enabled in settings. See VERIFY
- --verbose -v Report the full detail of what
is/would be deleted.
Prune won´t delete LFS files referenced by ´recent´
commits, in case you want to use them again without having to download. The
definition of ´recent´ is derived from the one used by
git-lfs-fetch(1) to download recent objects with the --recent
with an offset of a number of days (default 3) to ensure that we always keep
files you download for a few days.
Here are the git-config(1) settings that control this behaviour:
The number of extra days added to the fetch recent settings when using them
to decide when to prune. So for a reference to be considered old enough to
prune, it has to be this many days older than the oldest reference that
would be downloaded via git lfs fetch --recent. Only used if the
relevant fetch recent ´days´ setting is non-zero. Default 3
These have the same meaning as git-lfs-fetch(1) with the --recent
option, they are used as a base for the offset above. Anything which falls
outside of this offsetted window is considered old enough to prune. If a
day value is zero, that condition is not used at all to retain objects and
they will be pruned.
When the only copy of an LFS file is local, and it is still reachable from any
reference, that file can never be pruned, regardless of how old it is.
To determine whether an LFS file has been pushed, we check the difference
between local refs and remote refs; where the local ref is ahead, any LFS
files referenced in those commits is unpushed and will not be deleted. This
works because the LFS pre-push hook always ensures that LFS files are pushed
before the remote branch is updated.
See DEFAULT REMOTE
, for which remote is considered ´pushed´
for pruning purposes.
option calls the remote to ensure that any LFS files
to be deleted have copies on the remote before actually deleting them.
Usually the check performed by UNPUSHED LFS FILES
is enough to determine
that files have been pushed, but if you want to be extra sure at the expense
of extra overhead you can make prune actually call the remote API and verify
the presence of the files you´re about to delete locally. See
for which remote is checked.
You can make this behaviour the default by setting
In addition to the overhead of calling the remote, using this option also
requires prune to distinguish between totally unreachable files (e.g. those
that were added to the index but never committed, or referenced only by
orphaned commits), and files which are still referenced, but by commits which
are prunable. This makes the prune process take longer.
When identifying UNPUSHED LFS FILES
and performing VERIFY REMOTE
a single remote, ´origin´, is normally used as the reference.
This one remote is considered canonical; even if you use multiple remotes, you
probably want to retain your local copies until they´ve made it to that
remote. ´origin´ is used by default because that will usually be
a master central repo, or your fork of it - in both cases that´s a
valid remote backup of your work. If origin doesn´t exist then by
default nothing will be pruned because everything is treated as
You can alter the remote via git config: lfs.pruneremotetocheck
. Set this
to a different remote name to check that one instead of
Part of the git-lfs(1) suite.