NAME

       git-lfs-prune - Delete old LFS files from local storage

SYNOPSIS

       git lfs prune #OPTIONS

DESCRIPTION

       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-FILES

       ○   a ´recent commit´ on the current branch or recent branches; see #RECENT-FILES

       ○   a commit which has not been pushed; see #UNPUSHED-LFS-FILES

       ○   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 option.

OPTIONS

       ○   --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-REMOTE.

       ○   --verbose -v Report the full detail of what is/would be deleted.

RECENT FILES

       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  option, 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:

       ○   lfs.pruneoffsetdays
           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 days.

       ○   lfs.fetchrecentrefsdays
           lfs.fetchrecentremoterefs
           lfs.fetchrecentcommitsdays
           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.

UNPUSHED LFS FILES

       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.

VERIFY REMOTE

       The --verify-remote 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 #DEFAULT-REMOTE for
       which remote is checked.

       You can make this behaviour the default by setting lfs.pruneverifyremotealways to true.

       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.

DEFAULT REMOTE

       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 ´unpushed´.

       You  can  alter the remote via git config: lfs.pruneremotetocheck. Set this to a different remote name to
       check that one instead of ´origin´.

SEE ALSO

       git-lfs-fetch(1)

       Part of the git-lfs(1) suite.

                                                  December 2019                                 GIT-LFS-PRUNE(1)