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(5)
41       for more details about lfs.storage option.
42
43       In your Git  configuration  or  in  a  .lfsconfig  file,  you  may  set
44       lfs.fetchexclude  to  a  comma-separated list of paths. If lfs.fetchex‐
45       clude is defined, then any Git LFS files whose paths match one in  that
46       list  will  be  pruned  unless they are referenced by a stash or an un‐
47       pushed commit. Paths are matched using wildcard matching as per  gitig‐
48       nore(5).
49

OPTIONS

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

RECENT FILES

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

UNPUSHED LFS FILES

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

VERIFY REMOTE

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

DEFAULT REMOTE

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

SEE ALSO

149       git-lfs-fetch(1), gitignore(5).
150
151       Part of the git-lfs(1) suite.
152
153
154
155                                   May 2022                   GIT-LFS-PRUNE(1)
Impressum