GIT-LFS-CONFIG(5)

📦
version 3.8.1 · 17 versions
, in arch rolling, nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

okay bestie, welcome to the git-lfs-config manual page — it's literally all about 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. no cap, it's that flexible 🫶

On top of that, 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 config file is lowkey iconic 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. main character energy for your local setup, fr fr 🌈

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. iykyk 💜

✨ LIST OF OPTIONS ✨

🧚 General settings

  • lfs.url / remote.<remote>.lfsurl — the url used to call the Git LFS remote API. Default is blank (derive from clone URL). 💫
  • lfs.pushurl / remote.<remote>.lfspushurl — the url used to call the Git LFS remote API when pushing. Default is 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 feature 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. detective mode: on 🔍
  • 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. fallback queen behavior 👑
  • 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.pathFilterCacheSize — sets the size of the in-memory cache of results from matching file paths against the filter defined by the lfs.fetchInclude and lfs.fetchExclude options, or for commands which accept them, by the --include and --exclude command-line options or their -I and -X equivalents. Set to 0 or none to disable the cache, or to unlimited to allow the cache to grow without bound. Default: 10,000 unique file paths. 🗂️
  • 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. that's a no-no, bestie 😭

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. so basically the transfer vibe check 🌈

  • lfs.concurrenttransfers — the number of concurrent uploads/downloads. Default is 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. no fancy stuff, just basics ✨

  • 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. future vibes fr fr 🔮
  • 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 must be defined in a lfs.customtransfer.<name> settings group, or else must be the internal lfs-standalone-file transfer adapter. Other values will be ignored.

See git-lfs-standalone-file(1) for details of the internal lfs-standalone-file custom transfer adapter, which is intended for use with local file:/// URLs. 📁

  • 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 📜

The <name> must be a unique identifier that the LFS server understands and which does not conflict with the name of any pre-defined internal transfer adapter in the client such as "basic" or "ssh", as these will always override a custom transfer adapter with the same name. 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. 👯‍♀️

If multiple lfs.customtransfer.<name> settings are defined, they must all be contained within the same configuration sub-section, meaning that the sub-section portion of their names must be identical. For instance, if lfs.customTransfer.myAdapter.path is defined, then lfs.customTransfer.myAdapter.args will be accepted, while lfs.customtransfer.myadapter.args will not. case-sensitive, bestie 💅

  • 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. teamwork makes the dream work 🫶
  • 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.httpDownloadEncoding / lfs.transfer.<url>.httpDownloadEncoding — specifies the compression encoding to use when downloading LFS objects over HTTP. Valid values are gzip or zstd. Default is gzip. 🗜️

This option may be applied selectively to some URLs, following the same matching rules as those defined for Git’s http.<url>.* options (https://git-scm.com/docs/git-config#Documentation/git-config.txt-httplturlgt). For example, to set this option only for a specific host, use:

git config lfs.transfer.https://example.com/.httpDownloadEncoding zstd
  • 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 that isn't negative. Use zero to kill the delays between retries — unless a server explicitly requests one. If the value isn't an integer, is negative, or just isn't there at all, a value of ten gets used instead. 🫶

  • lfs.transfer.maxRetryTime — the max time in seconds LFS will wait before it gives up on a transfer when a server asks for a delay via the Retry-After header. So if the server says "wait longer than this," LFS logs a warning and marks the transfer as failed instead of sleeping for the whole requested duration (no cap, no vibe). 😭

Must be an integer that's at least one. If the value isn't an integer, is less than one, or isn't given, a value of 300 gets used instead.

  • lfs.transfer.maxverifies — how many verification requests LFS will attempt per OID before marking the transfer as failed, but only if the object has a verification action attached to it. Must be an integer at least one. If it isn't an integer, is less than one, or isn't given, the default of three gets used instead.
  • lfs.transfer.enablehrefrewrite — set it to true and it turns on rewriting the href of LFS objects using url.*.insteadof/pushinsteadof config. pushinsteadof is used only for uploading, and insteadof is used for downloading plus uploading when pushinsteadof isn't set. iykyk 💅
  • lfs.transfer.batchSize — the number of objects to download/upload sent in a single batch request to the LFS server. Default is 100.
Change this one with caution, bestie — 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. The Batch API specification says so, so it's not me being dramatic. 💀

🚀 Push settings

  • lfs.allowincompletepush — when pushing, let objects be missing from the local cache without halting a Git push. Default: false.

🌸 Fetch settings

  • lfs.fetchinclude — when fetching, only download objects that match any entry on this comma-separated list of paths/filenames. Wildcard matching works as per gitignore(5). See git-lfs-fetch(1) for examples. ✨
  • lfs.fetchexclude — when fetching, do not download objects that 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 that have commits within N days of the current date. Only local refs get 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 inside the recent window. Genuinely useful for grabbing objects for remote branches you might wanna check out later. The default is true; if you set it to false, fetching for those branches only happens when you either check them out (and there goes your fetch --recent advantage 😭), or you create a tracking local branch separately and fetch again.
  • lfs.fetchrecentcommitsdays — in addition to fetching at refs, it also fetches previous changes made within N days of the latest commit on the ref. Great if you're constantly 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 figure out what can be pruned. Default is 3 days, meaning anything fetched at the very oldest edge of the "recent window" is eligible for pruning 3 days later. 🗑️
  • lfs.pruneremotetocheck — sets the remote that LFS files must have been pushed to in order for them to count as eligible for local pruning. It's also the remote that gets 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 file 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), so you don't normally need to set it manually, bestie.

If set to "basic" then credentials get requested before making batch requests to this url, otherwise a public request is attempted first.

  • 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 depending 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 sets 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 sets 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. 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) get 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 lets actions like checkout work when you're unable to download the LFS content. LFS files that couldn't download will contain pointer content instead.
Heads up: this will result in git commands which call the smudge filter reporting success even in cases when LFS downloads fail, which may affect scripts. So like… be aware. 🙈

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 takes 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 — these control whether Git LFS suppresses progress status when the standard output stream isn't attached to a terminal. The default is false, which makes Git LFS detect whether stdout is a terminal and suppress progress when it isn't; you can disable that behaviour and force progress status even when standard output stream isn't 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 skips 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 smudges 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 skips the pre-push hook, so no new Git LFS objects get uploaded. If unset, or set to 'false', '0', 'off', or similar, Git LFS proceeds 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 — 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 — sets a default token TTL when git-lfs-authenticate doesn't 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 — yes bestie, same format, no cap 💅.

It allows a subset of keys to be used, including and limited to this whole iconic guest list:

  • 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 — so no sneaky extras, periodt 🔒✨.

🌸 EXAMPLES 🌸

  • Wanna configure a custom LFS endpoint for your repository? Say less, bestie:
git config -f .lfsconfig lfs.url
https://lfs.example.com/foo/bar/info/lfs

👑 SEE ALSO 👑

Go have a lil read of these besties: git-config(1), git-lfs-install(1), git-lfs-standalone-file(1), gitattributes(5), gitignore(5) 🫶.

Also — important vibe — this page is part of the git-lfs(1) suite ✨.

That’s a wrap on GIT-LFS-CONFIG(5) — shoutout to the source/version and date in the footer doing their tiny end-credit cameo 🎀💖. Bye bestie!

📦 where this page comes from