Published 2025-01-06.
Time to read: 4 minutes.
This page is part of the
git collection.
I have published 8 articles about the Git large file system (LFS). They are meant to be read in order.
- Git Large File System Overview
- Git LFS Scripts
- Git LFS Client Installation
- Git LFS Server URLs
- Git-ls-files, Wildmatch Patterns and Permutation Scripts
- Git LFS Tracking, Migration and Un-Migration
- Git LFS Client Configuration & Commands
- Git LFS SSH Authentication
- Working With Git LFS
- Evaluation Procedure For Git LFS Servers
- Git LFS server tests:
6 articles are still in process.
Instructions for typing along are given for Ubuntu and WSL/Ubuntu. If you have a Mac, most of this information should be helpful.
Git LFS Client Configuration
The Git LFS configuration man page follows:
Output of 'man git-lfs-config'
GIT-LFS-CONFIG(5) GIT-LFS-CONFIG(5)
NAME git-lfs-config - Configuration options for git-lfs
CONFIGURATION FILES git-lfs reads its configuration from any file supported by git config -l, including all per-repository, per-user, and per-system Git configuration files.
Additionally, a small number of settings can be specified in a file called .lfsconfig at the root of the repository; see the "LFSCONFIG" section for more details. This configuration file is useful for setting options such as the LFS URL or access type for all users of a repository, especially when these differ from the default. The .lfsconfig file uses the same format as .gitconfig.
If the .lfsconfig file is missing, the index is checked for a version of the file, and that is used instead. If both are missing, HEAD is checked for the file. If the repository is bare, only HEAD is checked. This order may change for checkouts in the future to better match Git’s behavior.
Settings from Git configuration files override the .lfsconfig file. This allows you to override settings like lfs.url in your local environment without having to modify the .lfsconfig file.
Most options regarding git-lfs are contained in the [lfs] section, meaning they are all named lfs.foo or similar, although occasionally an lfs option can be scoped inside the configuration for a remote.
LIST OF OPTIONS General settings • lfs.url / remote.<remote>.lfsurl
The url used to call the Git LFS remote API. Default blank (derive from clone URL).
• lfs.pushurl / remote.<remote>.lfspushurl
The url used to call the Git LFS remote API when pushing. Default blank (derive from either LFS non-push urls or clone url).
• remote.lfsdefault
The remote used to find the Git LFS remote API. lfs.url and branch.*.remote for the current branch override this setting. If this setting is not specified and there is exactly one remote, that remote is picked; otherwise, the default is origin.
• remote.lfspushdefault
The remote used to find the Git LFS remote API when pushing. lfs.url and branch.*.pushremote for the current branch override this setting. If this setting is not set, remote.pushdefault is used, or if that is not set, the order of selection is used as specified in the remote.lfsdefault above.
• lfs.remote.autodetect
This boolean option enables the remote autodetect feaure within Git LFS. LFS tries to derive the corresponding remote from the commit information and, in case of success, ignores the settings defined by remote.lfsdefault and remote.<remote>.lfsurl.
• lfs.remote.searchall
This boolean option enables Git LFS to search all registered remotes to find LFS data. This is a fallback mechanism executed only if the LFS data could not be found via the ordinary heuristics as described in remote.lfsdefault, remote.<remote>.lfsurl and, if enabled, lfs.remote.autodetect.
• lfs.dialtimeout
Sets the maximum time, in seconds, that the HTTP client will wait to initiate a connection. This does not include the time to send a request and wait for a response. Default: 30 seconds
• lfs.tlstimeout
Sets the maximum time, in seconds, that the HTTP client will wait for a TLS handshake. Default: 30 seconds.
• lfs.activitytimeout / lfs.https://<host>.activitytimeout
Sets the maximum time, in seconds, that the HTTP client will wait for the next tcp read or write. If < 1, no activity timeout is used at all. Default: 30 seconds
• lfs.keepalive
Sets the maximum time, in seconds, for the HTTP client to maintain keepalive connections. Default: 30 minutes.
• lfs.ssh.automultiplex
When using the pure SSH-based protocol, whether to multiplex requests over a single connection when possible. This option requires the use of OpenSSH or a compatible SSH client. Default: false on Windows, otherwise true.
• lfs.ssh.retries
Specifies the number of times Git LFS will attempt to obtain authorization via SSH before aborting. Default: 5.
• core.askpass, GIT_ASKPASS
Given as a program and its arguments, this is invoked when authentication is needed against the LFS API. The contents of stdout are interpreted as the password.
• lfs.cachecredentials
Enables in-memory SSH and Git Credential caching for a single 'git lfs' command. Default: enabled.
• lfs.storage
Allow override LFS storage directory. Non-absolute path is relativized to inside of Git repository directory (usually .git).
Note: you should not run git lfs prune if you have different repositories sharing the same storage directory.
Default: lfs in Git repository directory (usually .git/lfs).
• lfs.largefilewarning
Warn when a file is 4 GiB or larger. Such files will be corrupted when using Windows (unless smudging is disabled) with a Git for Windows version less than 2.34.0 due to a limitation in Git. Default: true if the version is less than 2.34.0, false otherwise.
Upload and download transfer settings These settings control how the upload and download of LFS content occurs.
• lfs.concurrenttransfers
The number of concurrent uploads/downloads. Default 8.
• lfs.basictransfersonly
If set to true, only basic HTTP upload/download transfers will be used, ignoring any more advanced transfers that the client/server may support. This is primarily to work around bugs or incompatibilities.
The git-lfs client supports basic HTTP downloads, resumable HTTP downloads (using Range headers), and resumable uploads via tus.io protocol. Custom transfer methods can be added via lfs.customtransfer (see next section). However setting this value to true limits the client to simple HTTP.
• lfs.tustransfers
If set to true, this enables resumable uploads of LFS objects through the tus.io API. Once this feature is finalized, this setting will be removed, and tus.io uploads will be available for all clients.
• lfs.standalonetransferagent
Allows the specified custom transfer agent to be used directly for transferring files, without asking the server how the transfers should be made. The custom transfer agent has to be defined in a lfs.customtransfer.<name> settings group.
• lfs.customtransfer.<name>.path
lfs.customtransfer.<name> is a settings group which defines a custom transfer hook which allows you to upload/download via an intermediate process, using any mechanism you like (rather than just HTTP). path should point to the process you wish to invoke. The protocol between the git-lfs client and the custom transfer process is documented at https://github.com/git-lfs/git-lfs/blob/main/docs/custom-transfers.md
must be a unique identifier that the LFS server understands. When calling the LFS API the client will include a list of supported transfer types. If the server also supports this named transfer type, it will select it and actions returned from the API will be in relation to that transfer type (may not be traditional URLs for example). Only if the server accepts as a transfer it supports will this custom transfer process be invoked.
• lfs.customtransfer.<name>.args
If the custom transfer process requires any arguments, these can be provided here. This string will be expanded by the shell.
• lfs.customtransfer.<name>.concurrent
If true (the default), git-lfs will invoke the custom transfer process multiple times in parallel, according to lfs.concurrenttransfers, splitting the transfer workload between the processes.
• lfs.customtransfer.<name>.direction
Specifies which direction the custom transfer process supports, either "download", "upload", or "both". The default if unspecified is "both".
• lfs.transfer.maxretries
Specifies how many retries LFS will attempt per OID before marking the transfer as failed. Must be an integer which is at least one. If the value is not an integer, is less than one, or is not given, a value of eight will be used instead.
• lfs.transfer.maxretrydelay
Specifies the maximum time in seconds LFS will wait between each retry attempt. LFS uses exponential backoff for retries, doubling the time between each retry until reaching this limit. If a server requests a delay using the Retry-After header, the header value overrides the exponential delay for that attempt and is not limited by this option.
Must be an integer which is not negative. Use zero to disable delays between retries unless requested by a server. If the value is not an integer, is negative, or is not given, a value of ten will be used instead.
• lfs.transfer.maxverifies
Specifies how many verification requests LFS will attempt per OID before marking the transfer as failed, if the object has a verification action associated with it. Must be an integer which is at least one. If the value is not an integer, is less than one, or is not given, a default value of three will be used instead.
• lfs.transfer.enablehrefrewrite
If set to true, this enables rewriting href of LFS objects using url.*.insteadof/pushinsteadof config. pushinsteadof is used only for uploading, and insteadof is used for downloading and for uploading when pushinsteadof is not set.
• lfs.transfer.batchSize
The number of objects to download/upload sent in a single batch request to the LFS server. Default is 100.
This value should be changed with caution, as it can have a significant impact on the performance of the LFS server and the server is free to return an HTTP 413 status code if this value is too high as the Batch API specification states.
Push settings • lfs.allowincompletepush
When pushing, allow objects to be missing from the local cache without halting a Git push. Default: false.
Fetch settings • lfs.fetchinclude
When fetching, only download objects which match any entry on this comma-separated list of paths/filenames. Wildcard matching is as per gitignore(5). See git-lfs-fetch(1) for examples.
• lfs.fetchexclude
When fetching, do not download objects which match any item on this comma-separated list of paths/filenames. Wildcard matching is as per gitignore(5). See git-lfs-fetch(1) for examples.
• lfs.fetchrecentrefsdays
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
If true, fetches remote refs (for the remote you’re fetching) as well as local refs in the recent window. This is useful to fetch objects for remote branches you might want to check out later. The default is true; if you set this to false, fetching for those branches will only occur when you either check them out (losing the advantage of fetch --recent), or create a tracking local branch separately then fetch again.
• lfs.fetchrecentcommitsdays
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. 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.
• lfs.pruneverifyunreachablealways
Always run git lfs prune as if --verify-unreachable was provided.
Extensions • lfs.extension.<name>.<setting>
Git LFS extensions enable the manipulation of files streams during smudge and clean. name groups the settings for a single extension, and the settings are: clean The command which runs when files are added to the index smudge The command which runs when files are written to the working copy ** priority The order of this extension compared to others
Other settings • lfs.<url>.access
Note: this setting is normally set by LFS itself on receiving a 401 response (authentication required), you don’t normally need to set it manually.
If set to "basic" then credentials will be requested before making batch requests to this url, otherwise a public request will initially be attempted.
• lfs.<url>.locksverify
Determines whether locks are checked before Git pushes. This prevents you from pushing changes to files that other users have locked. The Git LFS pre-push hook varies its behavior based on the value of this config key. null - In the absence of a value, Git LFS will attempt the call, and warn if it returns an error. If the response is valid, Git LFS will set the value to true, and will halt the push if the user attempts to update a file locked by another user. If the server returns a 501 Not Implemented response, Git LFS will set the value to false. true - Git LFS will attempt to verify locks, halting the Git push if there are any server issues, or if the user attempts to update a file locked by another user. ** false - Git LFS will completely skip the lock check in the pre-push hook. You should set this if you’re not using File Locking, or your Git server verifies locked files on pushes automatically.
+ Supports URL config lookup as described in: https://git-scm.com/docs/git-config#Documentation/git-config.txt-httplturlgt. To set this value per-host: git config --global lfs.https://github.com/.locksverify [true|false].
• lfs.sshtransfer / lfs.<url>.sshtransfer
Configures whether SSH transfers (the pure SSH protocol) are used. By default (or if the value is set to negotiate), the pure SSH protocol is tried first, and then the older hybrid protocol. If always is used, then only the pure SSH protocol is tried. Similarly, if never is used, then only the hybrid protocol is attempted.
• lfs.<url>.contenttype
Determines whether Git LFS should attempt to detect an appropriate HTTP Content-Type header when uploading using the 'basic' upload adapter. If set to false, the default header of Content-Type: application/octet-stream is chosen instead. Default: 'true'.
• lfs.skipdownloaderrors
Causes Git LFS not to abort the smudge filter when a download error is encountered, which allows actions such as checkout to work when you are unable to download the LFS content. LFS files which could not download will contain pointer content instead.
Note that this will result in git commands which call the smudge filter to report success even in cases when LFS downloads fail, which may affect scripts.
You can also set the environment variable GIT_LFS_SKIP_DOWNLOAD_ERRORS=1 to get the same effect.
• GIT_LFS_PROGRESS
This environment variable causes Git LFS to emit progress updates to an absolute file-path on disk when cleaning, smudging, or fetching.
Progress is reported periodically in the form of a new line being appended to the end of the file. Each new line will take the following format:
<direction> <current>/<total files> <downloaded>/<total> <name>
Each field is described below: direction: The direction of transfer, either "checkout", "download", or "upload". current The index of the currently transferring file. total files The estimated count of all files to be transferred. downloaded The number of bytes already downloaded. total The entire size of the file, in bytes. name The name of the file.
• GIT_LFS_FORCE_PROGRESS lfs.forceprogress
Controls whether Git LFS will suppress progress status when the standard output stream is not attached to a terminal. The default is false which makes Git LFS detect whether stdout is a terminal and suppress progress when it’s not; you can disable this behaviour and force progress status even when standard output stream is not a terminal by setting either variable to 1, 'yes' or 'true'.
• GIT_LFS_SKIP_SMUDGE
Sets whether or not Git LFS will skip attempting to convert pointers of files tracked into their corresponding objects when checked out into a working copy. If 'true', '1', 'on', or similar, Git LFS will skip the smudge process in both git lfs smudge and git lfs filter-process. If unset, or set to 'false', '0', 'off', or similar, Git LFS will smudge files as normal.
• GIT_LFS_SKIP_PUSH
Sets whether or not Git LFS will attempt to upload new Git LFS object in a pre-push hook. If 'true', '1', 'on', or similar, Git LFS will skip the pre-push hook, so no new Git LFS objects will be uploaded. If unset, or set to 'false', '0', 'off', or similar, Git LFS will proceed as normal.
• GIT_LFS_SET_LOCKABLE_READONLY lfs.setlockablereadonly
These settings, the first an environment variable and the second a gitconfig setting, control whether files marked as 'lockable' in git lfs track are made read-only in the working copy when not locked by the current user. The default is true; you can disable this behaviour and have all files writeable by setting either variable to 0, 'no' or 'false'.
• lfs.lockignoredfiles
This setting controls whether Git LFS will set ignored files that match the lockable pattern read only as well as tracked files. The default is false; you can enable this behavior by setting the variable to 1, 'yes', or 'true'.
• lfs.defaulttokenttl
This setting sets a default token TTL when git-lfs-authenticate does not include the TTL in the JSON response but still enforces it.
Note that this is only necessary for larger repositories hosted on LFS servers that don’t include the TTL.
LFSCONFIG The .lfsconfig file in a repository is read and interpreted in the same format as the file stored in .git/config. It allows a subset of keys to be used, including and limited to:
• lfs.allowincompletepush
• lfs.fetchexclude
• lfs.fetchinclude
• lfs.gitprotocol
• lfs.locksverify
• lfs.pushurl
• lfs.skipdownloaderrors
• lfs.url
• lfs.\{*}.access
• remote.{name}.lfsurl
The set of keys allowed in this file is restricted for security reasons.
EXAMPLES • Configure a custom LFS endpoint for your repository:
git config -f .lfsconfig lfs.url https://lfs.example.com/foo/bar/info/lfs
SEE ALSO git-config(1), git-lfs-install(1), gitattributes(5), gitignore(5).
Part of the git-lfs(1) suite.
GIT-LFS-CONFIG(5)
We can examine the Git client LFS configuration for the current Git repository:
Shell
mslinn@bear my_repo $ git lfs env git-lfs/3.6.0 (GitHub; linux amd64; go 1.23.1) git version 2.45.2
LocalWorkingDir=/mnt/e/media/songs/test LocalGitDir=/mnt/e/media/songs/test/.git LocalGitStorageDir=/mnt/e/media/songs/test/.git LocalMediaDir=/mnt/e/media/songs/test/.git/lfs/objects LocalReferenceDirs= TempDir=/mnt/e/media/songs/test/.git/lfs/tmp ConcurrentTransfers=8 TusTransfers=false BasicTransfersOnly=false SkipDownloadErrors=false FetchRecentAlways=false FetchRecentRefsDays=7 FetchRecentCommitsDays=0 FetchRecentRefsIncludeRemotes=true PruneOffsetDays=3 PruneVerifyRemoteAlways=false PruneVerifyUnreachableAlways=false PruneRemoteName=origin LfsStorageDir=/mnt/e/media/songs/test/.git/lfs AccessDownload=none AccessUpload=none DownloadTransfers=basic,lfs-standalone-file,ssh UploadTransfers=basic,lfs-standalone-file,ssh GIT_EXEC_PATH=/usr/lib/git-core GIT_MERGE_AUTOEDIT=no git config filter.lfs.process = "git-lfs filter-process" git config filter.lfs.smudge = "git-lfs smudge -- %f" git config filter.lfs.clean = "git-lfs clean -- %f"
LFS Cache
As a Git user, you know that the Git client maintains a local copy of the Git database for each repository. The Git LFS client extension does a similar thing, for large files. The LFS stores these files in an LFS cache.
By default, there are at least 2 copies of every large file in LFS-enabled Git repositories: one copy in the working tree, and another copy in the Git LFS database.
Shell
mslinn@bear my_repo $ tree .git/lfs .git/lfs ├── cache │ └── locks │ └── refs │ └── heads │ └── master │ └── verifiable ├── objects │ ├── 32 │ │ └── 63 │ │ └── 326380bc400b0928eca447202e7e6f2b32e547ac10e626849dbb58d1160909fe │ └── 41 │ └── d4 │ └── 41d489370da9b7199d5b6651c7fd16705e0a70be7a7f42bb62f2211079b3a168 └── tmp
12 directories, 3 files
Important Git LFS Commands
After the command-line Git client has been enhanced with the Git LFS extension, the following new commands become available:
git-lfs-checkout
git lfs checkout:
updates the working copy with large file content if it has already been downloaded.
Does not download any content; see git-lfs-fetch for that.
Output of 'man git-lfs-checkout'
GIT-LFS-CHECKOUT(1) GIT-LFS-CHECKOUT(1)
NAME git-lfs-checkout - Update working copy with file content if available
SYNOPSIS git lfs checkout [<glob-pattern>...] git lfs checkout --to <file> {--base|--ours|--theirs} <conflict-obj-path>
DESCRIPTION Try to ensure that the working copy contains file content for Git LFS objects for the current ref, if the object data is available. Does not download any content; see git-lfs-fetch(1) for that.
Checkout scans the current ref for all LFS objects that would be required, then where a file is either missing in the working copy, or contains placeholder pointer content with the same SHA, the real file content is written, provided we have it in the local store. Modified files are never overwritten.
One or more s may be provided as arguments to restrict the set of files that are updated. Glob patterns are matched as per the format described in gitignore(5).
When used with --to and the working tree is in a conflicted state due to a merge, this option checks out one of the three stages a conflicting Git LFS object into a separate file (which can be outside of the work tree). This can make using diff tools to inspect and resolve merges easier. A single Git LFS object’s file path must be provided in <conflict-obj-path>.
OPTIONS --base Check out the merge base of the specified file.
--ours Check out our side (that of the current branch) of the conflict for the specified file.
--theirs Check out their side (that of the other branch) of the conflict for the specified file.
--to <path> If the working tree is in a conflicted state, check out the portion of the conflict specified by --base, --ours, or --theirs to the given path.
EXAMPLES • Checkout all files that are missing or placeholders:
$ git lfs checkout
• Checkout a specific couple of files:
$ git lfs checkout path/to/file1.png path/to.file2.png
• Checkout a path with a merge conflict into separate files:
# Attempt merge with a branch that has a merge conflict $ git merge conflicting-branch CONFLICT (content): Merge conflict in path/to/conflicting/file.dat
# Checkout versions of the conflicting file into temp files $ git lfs checkout ours.dat --ours path/to/conflicting/file.dat $ git lfs checkout theirs.dat --theirs path/to/conflicting/file.dat
# Compare conflicting versions in ours.dat and theirs.dat, # then resolve conflict (e.g., by choosing one version over # the other, or creating a new version)
# Cleanup and continue with merge $ rm ours.dat theirs.dat $ git add path/to/conflicting/file.dat $ git merge --continue
SEE ALSO git-lfs-fetch(1), git-lfs-pull(1), gitignore(5).
Part of the git-lfs(1) suite.
GIT-LFS-CHECKOUT(1)
git-lfs-env
git lfs env:
displays the current Git LFS environment.
This command is helpful for debugging.
Output of 'man git-lfs-env'
GIT-LFS-ENV(1) GIT-LFS-ENV(1)
NAME git-lfs-env - Display the Git LFS environment
SYNOPSIS git lfs env
DESCRIPTION Display the current Git LFS environment.
SEE ALSO Part of the git-lfs(1) suite.
GIT-LFS-ENV(1)
git-lfs-fetch
git lfs fetch:
Downloads Git LFS objects from the specified remote, or the default remote if not specified.
This does not update the working copy; use git lfs checkout for that.
Output of 'man git-lfs-fetch'
GIT-LFS-FETCH(1) GIT-LFS-FETCH(1)
NAME git-lfs-fetch - Download all Git LFS files for a given ref
SYNOPSIS git lfs fetch [options] [<remote> [<ref>...]]
DESCRIPTION Download Git LFS objects at the given refs from the specified remote. See DEFAULT REMOTE and DEFAULT REFS for what happens if you don’t specify.
This does not update the working copy.
OPTIONS -I <paths>, --include=<paths> Specify lfs.fetchinclude just for this invocation; see INCLUDE AND EXCLUDE.
-X <paths>, --exclude=<paths> Specify lfs.fetchexclude just for this invocation; see INCLUDE AND EXCLUDE.
--recent Download objects referenced by recent branches & commits in addition to those that would otherwise be downloaded. See RECENT CHANGES.
--all Download all objects that are referenced by any commit reachable from the refs provided as arguments. If no refs are provided, then all refs are fetched. This is primarily for backup and migration purposes. Cannot be combined with --recent or --include/--exclude. Ignores any globally configured include and exclude paths to ensure that all objects are downloaded.
--prune, -p Prune old and unreferenced objects after fetching, equivalent to running git lfs prune afterwards. See git-lfs-prune(1) for more details.
INCLUDE AND EXCLUDE You can configure Git LFS to only fetch objects to satisfy references in certain paths of the repo, and/or to exclude certain paths of the repo, to reduce the time you spend downloading things you do not use.
In your Git configuration or in a .lfsconfig file, you may set either or both of lfs.fetchinclude and lfs.fetchexclude to comma-separated lists of paths. If lfs.fetchinclude is defined, Git LFS objects will only be fetched if their path matches one in that list, and if lfs.fetchexclude is defined, Git LFS objects will only be fetched if their path does not match one in that list. Paths are matched using wildcard matching as per gitignore(5).
Note that using the command-line options -I and -X override the respective configuration settings. Setting either option to an empty string clears the value.
Examples • git config lfs.fetchinclude "textures,images/foo*"
This will only fetch objects referenced in paths in the textures folder, and files called foo* in the images folder
• git config lfs.fetchinclude ".jpg,.png,*.tga"
Only fetch JPG/PNG/TGA files, wherever they are in the repository
• git config lfs.fetchexclude "media/reallybigfiles"
Don’t fetch any LFS objects referenced in the folder media/reallybigfiles, but fetch everything else
• git config lfs.fetchinclude "media" git config lfs.fetchexclude "media/excessive"
Only fetch LFS objects in the 'media' folder, but exclude those in one of its subfolders.
DEFAULT REMOTE Without arguments, fetch downloads from the default remote. The default remote is the same as for git fetch, i.e. based on the remote branch you’re tracking first, or origin otherwise.
DEFAULT REFS If no refs are given as arguments, the currently checked out ref is used. In addition, if enabled, recently changed refs and commits are also included. See RECENT CHANGES for details.
RECENT CHANGES If the --recent option is specified, or if the gitconfig option lfs.fetchrecentalways is true, then after the current ref (or those in the arguments) is fetched, we also search for 'recent' changes to fetch objects for, so that it’s more convenient to checkout or diff those commits without incurring further downloads.
What changes are considered 'recent' is based on a number of gitconfig options:
lfs.fetchrecentrefsdays If non-zero, includes branches which have commits within N days of the current date. Only local refs are included unless lfs.fetchrecentremoterefs is true. The default is 7 days.
lfs.fetchrecentremoterefs If true, fetches remote refs (for the remote you’re fetching) as well as local refs in the recent window. This is useful to fetch objects for remote branches you might want to check out later. The default is true; if you set this to false, fetching for those branches will only occur when you either check them out (losing the advantage of fetch --recent), or create a tracking local branch separately then fetch again.
lfs.fetchrecentcommitsdays In addition to fetching at branches, also fetches changes made within N days of the latest commit on the branch. This is useful if you’re often reviewing recent changes. The default is 0 (no previous changes).
lfs.fetchrecentalways Always operate as if --recent was provided on the command line.
EXAMPLES • Fetch the LFS objects for the current ref from default remote
git lfs fetch
• Fetch the LFS objects for the current ref AND recent changes from default remote
git lfs fetch --recent
• Fetch the LFS objects for the current ref from a secondary remote 'upstream'
git lfs fetch upstream
• Fetch all the LFS objects from the default remote that are referenced by any commit in the main and develop branches
git lfs fetch --all origin main develop
• Fetch the LFS objects for a branch from origin
git lfs fetch origin mybranch
• Fetch the LFS objects for 2 branches and a commit from origin
git lfs fetch origin main mybranch e445b45c1c9c6282614f201b62778e4c0688b5c8
SEE ALSO git-lfs-checkout(1), git-lfs-pull(1), git-lfs-prune(1), gitconfig(5).
Part of the git-lfs(1) suite.
GIT-LFS-FETCH(1)
git-lfs-fsck
This command does a sanity check of the local Git LFS repository.
You must run git lfs fetch --all before running this command.
Output of 'man git-lfs-fsck'
GIT-LFS-FSCK(1) GIT-LFS-FSCK(1)
NAME git-lfs-fsck - Check GIT LFS files for consistency
SYNOPSIS git lfs fsck [options] [revisions]
DESCRIPTION Checks all Git LFS files in the current HEAD for consistency.
Corrupted files are moved to ".git/lfs/bad".
The revisions may be specified as either a single committish, in which case only that commit is inspected; specified as a range of the form A..B (and only this form), in which case that range is inspected; or omitted entirely, in which case HEAD (and, for --objects, the index) is examined.
The default is to perform all checks.
In your Git configuration or in a .lfsconfig file, you may set lfs.fetchexclude to a comma-separated list of paths. If lfs.fetchexclude is defined, then any Git LFS files whose paths match one in that list will not be checked for consistency. Paths are matched using wildcard matching as per gitignore(5).
OPTIONS --objects Check that each object in HEAD matches its expected hash and that each object exists on disk.
--pointers Check that each pointer is canonical and that each file which should be stored as a Git LFS file is so stored.
SEE ALSO git-lfs-ls-files(1), git-lfs-status(1), gitignore(5).
Part of the git-lfs(1) suite.
GIT-LFS-FSCK(1)
git-lfs-install
git lfs install:
Performs two functions:
- Defines filters in the global git client configuration.
- Installs the Git LFS pre-push hook in the repository that it was called from, if any.
Output of 'man git-lfs-install'
GIT-LFS-INSTALL(1) GIT-LFS-INSTALL(1)
NAME git-lfs-install - Install Git LFS configuration.
SYNOPSIS git lfs install [options]
DESCRIPTION Perform the following actions to ensure that Git LFS is setup properly:
• Set up the clean and smudge filters under the name "lfs" in the global Git config.
• Install a pre-push hook to run git-lfs-pre-push(1) for the current repository, if run from inside one. If "core.hooksPath" is configured in any Git configuration (and supported, i.e., the installed Git version is at least 2.9.0), then the pre-push hook will be installed to that directory instead.
OPTIONS Without any options, git lfs install will only setup the "lfs" smudge and clean filters if they are not already set.
--force Sets the "lfs" smudge and clean filters, overwriting existing values.
--local Sets the "lfs" smudge and clean filters in the local repository’s git config, instead of the global git config (~/.gitconfig).
--worktree Sets the "lfs" smudge and clean filters in the current working tree’s git config, instead of the global git config (~/.gitconfig) or local repository’s git config ($GIT_DIR/config). If multiple working trees are in use, the Git config extension worktreeConfig must be enabled to use this option. If only one working tree is in use, --worktree has the same effect as --local. This option is only available if the installed Git version is at least 2.20.0 and therefore supports the "worktreeConfig" extension.
--manual Print instructions for manually updating your hooks to include git-lfs functionality. Use this option if git lfs install fails because of existing hooks and you want to retain their functionality.
--system Sets the "lfs" smudge and clean filters in the system git config, e.g. /etc/gitconfig instead of the global git config (~/.gitconfig).
--skip-smudge Skips automatic downloading of objects on clone or pull. This requires a manual "git lfs pull" every time a new commit is checked out on your repository.
--skip-repo Skips installation of hooks into the local repository; use if you want to install the LFS filters but not make changes to the hooks. It is valid to use --local, --global, or --system in conjunction with this option.
SEE ALSO git-lfs-uninstall(1), git-worktree(1).
Part of the git-lfs(1) suite.
GIT-LFS-INSTALL(1)
git-lfs-ls-files
Also see the lfs-files script.
Unlike git ls-files, which shows files in the index as well as those in the Git database,
git lfs ls-files only shows files in the Git LFS database.
Output of 'man git-lfs-ls-files'
GIT-LFS-LS-FILES(1) GIT-LFS-LS-FILES(1)
NAME git-lfs-ls-files - Show information about Git LFS files in the index and working tree
SYNOPSIS git lfs ls-files [<ref>] git lfs ls-files <ref> <ref>
DESCRIPTION Display paths of Git LFS files that are found in the tree at the given reference. If no reference is given, scan the currently checked-out branch. If two references are given, the LFS files that are modified between the two references are shown; deletions are not listed.
An asterisk (*) after the OID indicates a full object, a minus (-) indicates an LFS pointer.
OPTIONS -l, --long Show the entire 64 character OID, instead of just first 10.
-s, --size Show the size of the LFS object between parenthesis at the end of a line.
-d, --debug Show as much information as possible about a LFS file. This is intended for manual inspection; the exact format may change at any time.
-a, --all Inspects the full history of the repository, not the current HEAD (or other provided reference). This will include previous versions of LFS objects that are no longer found in the current tree.
--deleted Shows the full history of the given reference, including objects that have been deleted.
-I <paths>, --include=<paths> Include paths matching only these patterns; see [_fetch_settings].
-X <paths>, --exclude=<paths> Exclude paths matching any of these patterns; see [_fetch_settings].
-n, --name-only Show only the lfs tracked file names.
SEE ALSO git-lfs-status(1), git-lfs-config(5).
Part of the git-lfs(1) suite.
GIT-LFS-LS-FILES(1)
The following example shows a mixture of pointers and objects. Objects are indicated with asterisks (*) after the OID, while pointers are indicated by dashes (-):
Shell
mslinn@bear my_repo $ git lfs ls-files 3740843b34 - images/sydney_regatta_gzsim.png 91e96edd71 * vrx_gz/models/coast_waves/meshes/waterlow.dae 3ca6d28451 - vrx_gz/models/dock_block_4x4/mesh/DockCubes_Albedo.png
git-lfs-ls-migrate
See the section entitled
Converting An Existing Repository to Git LFS
in my article Git LFS Tracking, Migration and Un-Migration for further details.
The git-lfs-migrate man page is here.
-
lfs migrate importcan be extremely slow. -
It seems that the
--aboveoption causes problems because tracking does not consider file size. I would not use this option at this time.
git-lfs-prune
git lfs prune:
releases disk space used by unused files in the Git LFS client cache.
This keeps a copy of the latest version of each large file in the Git LFS client cache.
If you want to be aggressive, and do away with the redundant copy in the Git LFS client cache
(.git/lfs/objects, not .git/objects), add the --force option.
For safely, also specify the --verify-remote and --verify-unreachable options,
so you do not lose large files from the local git client and have to download them again the next time you need them.
Shell
$ git lfs prune --force --verify-remote --verify-unreachable
Again, the only objects
that git-lfs-prune will remove are locally stored object files,
that is, those cached under .git/lfs/objects.
The command won't touch anything in the working tree.
The current version of
git lfs prune is slow on large repositories;
Perhaps a version released in 2025 might improve performance.
Output of 'man git-lfs-prune'
GIT-LFS-PRUNE(1) GIT-LFS-PRUNE(1)
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
• all existing stashes
• 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(5) for more details about lfs.storage option.
In your Git configuration or in a .lfsconfig file, you may set lfs.fetchexclude to a comma-separated list of paths. If lfs.fetchexclude is defined, then any Git LFS files whose paths match one in that list will be pruned unless they are referenced by a stash or an unpushed commit. Paths are matched using wildcard matching as per gitignore(5).
OPTIONS --dry-run, -d Don’t actually delete anything, just report on what would have been done
--force, -f Prune all objects except unpushed objects, including objects required for currently checked out refs. Implies --recent.
--recent Prune even objects that would normally be preserved by the configuration options specified below in RECENT FILES.
--verify-remote, -c Contact the remote and check that copies of reachable 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.
--verify-reachable When doing --verify-remote contact the remote and check unreachable objects as well. See VERIFY REMOTE.
--no-verify-reachable Disables remote verification of unreachable files if lfs.pruneverifyunreachablealways was enabled in settings. See VERIFY REMOTE.
--when-unverified=<halt,continue> When --verify-remote cannot verify an object on the remote, either halt the execution or continue the deletion of verified objects. 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 reachable 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.
If you want to verify unreachable objects as well, set the --verify-unreachable option.
You can check for unreachable objects by default by setting lfs.pruneverifyunreachablealways to true.
By default, --verify-remote halts execution if a file cannot be verified. Set --when-unverified=continue to not halt exceution but continue deleting all objects that can be verified.
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 main 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), gitignore(5).
Part of the git-lfs(1) suite.
GIT-LFS-PRUNE(1)
git-lfs-status
git lfs status:
Display paths of Git LFS objects that:
- have not been pushed to the Git LFS server. These are large files that would be uploaded by git push.
- have differences between the index file and the current HEAD commit. These are large files that would be committed by git commit.
- have differences between the working tree and the index file. These are files that could be staged using git add.
Output of 'man git-lfs-status'
GIT-LFS-STATUS(1) GIT-LFS-STATUS(1)
NAME git-lfs-status - Show the status of Git LFS files in the working tree
SYNOPSIS git lfs status [<options>]
DESCRIPTION Display paths of Git LFS objects that
• have not been pushed to the Git LFS server. These are large files that would be uploaded by git push.
• have differences between the index file and the current HEAD commit. These are large files that would be committed by git commit.
• have differences between the working tree and the index file. These are files that could be staged using git add.
This command must be run in a non-bare repository.
OPTIONS --porcelain Give the output in an easy-to-parse format for scripts.
--json Give the output in a stable json format for scripts.
SEE ALSO git-lfs-ls-files(1).
Part of the git-lfs(1) suite.
GIT-LFS-STATUS(1)
I have published 8 articles about the Git large file system (LFS). They are meant to be read in order.
- Git Large File System Overview
- Git LFS Scripts
- Git LFS Client Installation
- Git LFS Server URLs
- Git-ls-files, Wildmatch Patterns and Permutation Scripts
- Git LFS Tracking, Migration and Un-Migration
- Git LFS Client Configuration & Commands
- Git LFS SSH Authentication
- Working With Git LFS
- Evaluation Procedure For Git LFS Servers
- Git LFS server tests:
6 articles are still in process.
Instructions for typing along are given for Ubuntu and WSL/Ubuntu. If you have a Mac, most of this information should be helpful.
