1GIT-LFS-PRUNE(1) General Commands Manual GIT-LFS-PRUNE(1)
2
6 git-lfs-prune - Delete old LFS files from local storage
7
9 git lfs prune options
10
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 ○ the current checkout
18 ○ all existing stashes
20 ○ a ´recent branch´; see RECENT FILES
22 ○ a ´recent commit´ on the current branch or recent branches; see RE‐
24 CENT FILES
25 ○ a commit which has not been pushed; see UNPUSHED LFS FILES
27 ○ any other worktree checkouts; see git-worktree(1)
29 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 The reflog is not considered, only commits. Therefore LFS objects that
37 are only referenced by orphaned commits are always deleted.
38 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 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
51 ○ --dry-run -d Don´t actually delete anything, just report on what
52 would have been done
53 ○ --force -f Prune all objects except unpushed objects, including ob‐
55 jects required for currently checked out refs. Implies --recent.
56 ○ --recent Prune even objects that would normally be preserved by the
58 configuration options specified below in RECENT FILES.
59 ○ --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 ○ --no-verify-remote Disables remote verification if lfs.pruneveri‐
65 fyremotealways was enabled in settings. See VERIFY REMOTE.
66 ○ --verbose -v Report the full detail of what is/would be deleted.
68
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 Here are the git-config(1) settings that control this behaviour:
80 ○ lfs.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 ○ lfs.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
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 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 See DEFAULT REMOTE, for which remote is considered ´pushed´ for pruning
112 purposes.
113
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 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 You can make this behaviour the default by setting lfs.pruneverifyre‐
126 motealways to true.
127 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
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 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
149 git-lfs-fetch(1), gitignore(5).
150 Part of the git-lfs(1) suite.
152 May 2022 GIT-LFS-PRUNE(1)