1GIT-LFS-PRUNE(1)            General Commands Manual           GIT-LFS-PRUNE(1)
2
3
4

NAME

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

SYNOPSIS

9       git lfs prune options
10

DESCRIPTION

12       Deletes  local  copies of LFS files which are old, thus freeing up disk
13       space. Prune operates by enumerating all the  locally  stored  objects,
14       and  then  deleting any which are not referenced by at least ONE of the
15       following:
16
17       ○   the current checkout
18
19       ○   all existing stashes
20
21       ○   a ´recent branch´; see RECENT FILES
22
23       ○   a ´recent commit´ on the current branch or recent branches; see RE‐
24           CENT FILES
25
26       ○   a commit which has not been pushed; see UNPUSHED LFS FILES
27
28       ○   any other worktree checkouts; see git-worktree(1)
29
30
31
32       In  general  terms,  prune will delete files you´re not currently using
33       and which are not ´recent´, so long as they´ve been pushed i.e. the lo‐
34       cal copy is not the only one.
35
36       The  reflog is not considered, only commits. Therefore LFS objects that
37       are only referenced by orphaned commits are always deleted.
38
39       Note: you should not run git lfs prune if you have different  reposito‐
40       ries  sharing  the same custom storage directory; see git-lfs-config(1)
41       for more details about lfs.storage option.
42

OPTIONS

44--dry-run -d Don´t actually delete anything, just  report  on  what
45           would have been done
46
47--force -f Prune all objects except unpushed objects, including ob‐
48           jects required for currently checked out refs. Implies --recent.
49
50--recent Prune even objects that would normally be preserved by the
51           configuration options specified below in RECENT FILES.
52
53--verify-remote  -c Contact the remote and check that copies of the
54           files we would delete definitely exist before deleting. See  VERIFY
55           REMOTE.
56
57--no-verify-remote  Disables  remote verification if lfs.pruneveri‐
58           fyremotealways was enabled in settings. See VERIFY REMOTE.
59
60--verbose -v Report the full detail of what is/would be deleted.
61
62
63

RECENT FILES

65       Prune won´t delete LFS files referenced by ´recent´  commits,  in  case
66       you  want  to use them again without having to download. The definition
67       of ´recent´ is derived from the one used by git-lfs-fetch(1)  to  down‐
68       load  recent objects with the --recent option, with an offset of a num‐
69       ber of days (default 3) to ensure that we always keep files  you  down‐
70       load for a few days.
71
72       Here are the git-config(1) settings that control this behaviour:
73
74lfs.pruneoffsetdays
75           The  number  of  extra days added to the fetch recent settings when
76           using them to decide when to prune. So for a reference to  be  con‐
77           sidered old enough to prune, it has to be this many days older than
78           the oldest reference that would be downloaded  via  git  lfs  fetch
79           --recent.  Only used if the relevant fetch recent ´days´ setting is
80           non-zero. Default 3 days.
81
82lfs.fetchrecentrefsdays
83           lfs.fetchrecentremoterefs
84           lfs.fetchrecentcommitsdays
85           These have the same meaning as git-lfs-fetch(1) with  the  --recent
86           option,  they  are  used  as  a base for the offset above. Anything
87           which falls outside of this  offsetted  window  is  considered  old
88           enough to prune. If a day value is zero, that condition is not used
89           at all to retain objects and they will be pruned.
90
91
92

UNPUSHED LFS FILES

94       When the only copy of an LFS file is local, and it is  still  reachable
95       from  any  reference,  that file can never be pruned, regardless of how
96       old it is.
97
98       To determine whether an LFS file has been pushed, we check the  differ‐
99       ence  between local refs and remote refs; where the local ref is ahead,
100       any LFS files referenced in those commits is unpushed and will  not  be
101       deleted.  This  works because the LFS pre-push hook always ensures that
102       LFS files are pushed before the remote branch is updated.
103
104       See DEFAULT REMOTE, for which remote is considered ´pushed´ for pruning
105       purposes.
106

VERIFY REMOTE

108       The  --verify-remote  option  calls  the  remote to ensure that any LFS
109       files to be deleted have copies on the remote before actually  deleting
110       them.
111
112       Usually  the  check performed by UNPUSHED LFS FILES is enough to deter‐
113       mine that files have been pushed, but if you want to be extra  sure  at
114       the  expense of extra overhead you can make prune actually call the re‐
115       mote API and verify the presence of the files you´re  about  to  delete
116       locally. See DEFAULT REMOTE for which remote is checked.
117
118       You  can  make this behaviour the default by setting lfs.pruneverifyre‐
119       motealways to true.
120
121       In addition to the overhead of calling the remote,  using  this  option
122       also  requires  prune  to distinguish between totally unreachable files
123       (e.g. those that were added to the index but never committed, or refer‐
124       enced  only by orphaned commits), and files which are still referenced,
125       but by commits which are prunable. This makes the  prune  process  take
126       longer.
127

DEFAULT REMOTE

129       When  identifying  UNPUSHED  LFS  FILES and performing VERIFY REMOTE, a
130       single remote, ´origin´, is normally used as the  reference.  This  one
131       remote  is  considered canonical; even if you use multiple remotes, you
132       probably want to retain your local copies until they´ve made it to that
133       remote. ´origin´ is used by default because that will usually be a main
134       central repo, or your fork of it - in both cases that´s a valid  remote
135       backup  of  your  work. If origin doesn´t exist then by default nothing
136       will be pruned because everything is treated as ´unpushed´.
137
138       You can alter the remote via git  config:  lfs.pruneremotetocheck.  Set
139       this to a different remote name to check that one instead of ´origin´.
140

SEE ALSO

142       git-lfs-fetch(1)
143
144       Part of the git-lfs(1) suite.
145
146
147
148                                 October 2021                 GIT-LFS-PRUNE(1)
Impressum