diff --git a/docs/man/git-lfs-config.5.ronn b/docs/man/git-lfs-config.5.ronn index ba321666..5fce82fb 100644 --- a/docs/man/git-lfs-config.5.ronn +++ b/docs/man/git-lfs-config.5.ronn @@ -46,6 +46,7 @@ lfs option can be scoped inside the configuration for a remote. If non-zero, fetches refs which have commits within N days of the current date. Only local refs are included unless lfs.fetchrecentremoterefs is true. + Also used as a basis for pruning old files. The default is 7 days. * `lfs.fetchrecentremoterefs` @@ -61,13 +62,32 @@ lfs option can be scoped inside the configuration for a remote. In addition to fetching at refs, also fetches previous changes made within N days of the latest commit on the ref. This is useful if you're often reviewing - recent changes. The default is 0 (no previous changes). + recent changes. Also used as a basis for pruning old files. + The default is 0 (no previous changes). * `lfs.fetchrecentalways` Always operate as if --recent was included in a `git lfs fetch` call. Default false. +### Prune settings + +* `lfs.pruneoffsetdays` + + The number of days added to the `lfs.fetchrecent*` settings to determine what + can be pruned. Default is 3 days, i.e. that anything fetched at the very + oldest edge of the 'recent window' is eligible for pruning 3 days later. + +* `lfs.pruneremotetocheck` + + Set the remote that LFS files must have been pushed to in order for them to + be considered eligible for local pruning. Also the remote which is called if + --verify-remote is enabled. + +* `lfs.pruneverifyremotealways` + + Always run `git lfs prune` as if `--verify-remote` was provided. + ### Extensions * `lfs.extension..` diff --git a/docs/man/git-lfs-prune.1.ronn b/docs/man/git-lfs-prune.1.ronn new file mode 100644 index 00000000..b1d9909c --- /dev/null +++ b/docs/man/git-lfs-prune.1.ronn @@ -0,0 +1,116 @@ +git-lfs-prune(1) -- 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. + +## 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`. 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. + +## 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. +