1GIT-LFS-CONFIG(5) GIT-LFS-CONFIG(5)
2
6 git-lfs-config - Configuration options for git-lfs
7
9 git-lfs reads its configuration from any file supported by git config
10 -l, including all per-repository, per-user, and per-system Git
11 configuration files.
12 Additionally, a small number of settings can be specified in a file
14 called .lfsconfig at the root of the repository; see the "LFSCONFIG"
15 section for more details. This configuration file is useful for setting
16 options such as the LFS URL or access type for all users of a
17 repository, especially when these differ from the default. The
18 .lfsconfig file uses the same format as .gitconfig.
19 If the .lfsconfig file is missing, the index is checked for a version
21 of the file, and that is used instead. If both are missing, HEAD is
22 checked for the file. If the repository is bare, only HEAD is checked.
23 This order may change for checkouts in the future to better match Git’s
24 behavior.
25 Settings from Git configuration files override the .lfsconfig file.
27 This allows you to override settings like lfs.url in your local
28 environment without having to modify the .lfsconfig file.
29 Most options regarding git-lfs are contained in the [lfs] section,
31 meaning they are all named lfs.foo or similar, although occasionally an
32 lfs option can be scoped inside the configuration for a remote.
33
35 General settings
36 • lfs.url / remote.<remote>.lfsurl
37 The url used to call the Git LFS remote API. Default blank (derive
39 from clone URL).
40 • lfs.pushurl / remote.<remote>.lfspushurl
42 The url used to call the Git LFS remote API when pushing. Default
44 blank (derive from either LFS non-push urls or clone url).
45 • remote.lfsdefault
47 The remote used to find the Git LFS remote API. lfs.url and
49 branch.*.remote for the current branch override this setting. If
50 this setting is not specified and there is exactly one remote, that
51 remote is picked; otherwise, the default is origin.
52 • remote.lfspushdefault
54 The remote used to find the Git LFS remote API when pushing.
56 lfs.url and branch.*.pushremote for the current branch override
57 this setting. If this setting is not set, remote.pushdefault is
58 used, or if that is not set, the order of selection is used as
59 specified in the remote.lfsdefault above.
60 • lfs.remote.autodetect
62 This boolean option enables the remote autodetect feaure within Git
64 LFS. LFS tries to derive the corresponding remote from the commit
65 information and, in case of success, ignores the settings defined
66 by remote.lfsdefault and remote.<remote>.lfsurl.
67 • lfs.remote.searchall
69 This boolean option enables Git LFS to search all registered
71 remotes to find LFS data. This is a fallback mechanism executed
72 only if the LFS data could not be found via the ordinary heuristics
73 as described in remote.lfsdefault, remote.<remote>.lfsurl and, if
74 enabled, lfs.remote.autodetect.
75 • lfs.dialtimeout
77 Sets the maximum time, in seconds, that the HTTP client will wait
79 to initiate a connection. This does not include the time to send a
80 request and wait for a response. Default: 30 seconds
81 • lfs.tlstimeout
83 Sets the maximum time, in seconds, that the HTTP client will wait
85 for a TLS handshake. Default: 30 seconds.
86 • lfs.activitytimeout / lfs.https://<host>.activitytimeout
88 Sets the maximum time, in seconds, that the HTTP client will wait
90 for the next tcp read or write. If < 1, no activity timeout is used
91 at all. Default: 30 seconds
92 • lfs.keepalive
94 Sets the maximum time, in seconds, for the HTTP client to maintain
96 keepalive connections. Default: 30 minutes.
97 • lfs.ssh.automultiplex
99 When using the pure SSH-based protocol, whether to multiplex
101 requests over a single connection when possible. This option
102 requires the use of OpenSSH or a compatible SSH client. Default:
103 true.
104 • lfs.ssh.retries
106 Specifies the number of times Git LFS will attempt to obtain
108 authorization via SSH before aborting. Default: 5.
109 • core.askpass, GIT_ASKPASS
111 Given as a program and its arguments, this is invoked when
113 authentication is needed against the LFS API. The contents of
114 stdout are interpreted as the password.
115 • lfs.cachecredentials
117 Enables in-memory SSH and Git Credential caching for a single 'git
119 lfs' command. Default: enabled.
120 • lfs.storage
122 Allow override LFS storage directory. Non-absolute path is
124 relativized to inside of Git repository directory (usually .git).
125 Note: you should not run git lfs prune if you have different
127 repositories sharing the same storage directory.
128 Default: lfs in Git repository directory (usually .git/lfs).
130 • lfs.largefilewarning
132 Warn when a file is 4 GiB or larger. Such files will be corrupted
134 when using Windows (unless smudging is disabled) with a Git for
135 Windows version less than 2.34.0 due to a limitation in Git.
136 Default: true if the version is less than 2.34.0, false otherwise.
137 Upload and download transfer settings
139 These settings control how the upload and download of LFS content
140 occurs.
141 • lfs.concurrenttransfers
143 The number of concurrent uploads/downloads. Default 8.
145 • lfs.basictransfersonly
147 If set to true, only basic HTTP upload/download transfers will be
149 used, ignoring any more advanced transfers that the client/server
150 may support. This is primarily to work around bugs or
151 incompatibilities.
152 The git-lfs client supports basic HTTP downloads, resumable HTTP
154 downloads (using Range headers), and resumable uploads via tus.io
155 protocol. Custom transfer methods can be added via
156 lfs.customtransfer (see next section). However setting this value
157 to true limits the client to simple HTTP.
158 • lfs.tustransfers
160 If set to true, this enables resumable uploads of LFS objects
162 through the tus.io API. Once this feature is finalized, this
163 setting will be removed, and tus.io uploads will be available for
164 all clients.
165 • lfs.standalonetransferagent
167 Allows the specified custom transfer agent to be used directly for
169 transferring files, without asking the server how the transfers
170 should be made. The custom transfer agent has to be defined in a
171 lfs.customtransfer.<name> settings group.
172 • lfs.customtransfer.<name>.path
174 lfs.customtransfer.<name> is a settings group which defines a
176 custom transfer hook which allows you to upload/download via an
177 intermediate process, using any mechanism you like (rather than
178 just HTTP). path should point to the process you wish to invoke.
179 The protocol between the git-lfs client and the custom transfer
180 process is documented at
181 https://github.com/git-lfs/git-lfs/blob/main/docs/custom-transfers.md
182 must be a unique identifier that the LFS server understands. When
184 calling the LFS API the client will include a list of supported
185 transfer types. If the server also supports this named transfer
186 type, it will select it and actions returned from the API will be
187 in relation to that transfer type (may not be traditional URLs for
188 example). Only if the server accepts as a transfer it supports will
189 this custom transfer process be invoked.
190 • lfs.customtransfer.<name>.args
192 If the custom transfer process requires any arguments, these can be
194 provided here. This string will be expanded by the shell.
195 • lfs.customtransfer.<name>.concurrent
197 If true (the default), git-lfs will invoke the custom transfer
199 process multiple times in parallel, according to
200 lfs.concurrenttransfers, splitting the transfer workload between
201 the processes.
202 • lfs.customtransfer.<name>.direction
204 Specifies which direction the custom transfer process supports,
206 either "download", "upload", or "both". The default if unspecified
207 is "both".
208 • lfs.transfer.maxretries
210 Specifies how many retries LFS will attempt per OID before marking
212 the transfer as failed. Must be an integer which is at least one.
213 If the value is not an integer, is less than one, or is not given,
214 a value of eight will be used instead.
215 • lfs.transfer.maxretrydelay
217 Specifies the maximum time in seconds LFS will wait between each
219 retry attempt. LFS uses exponential backoff for retries, doubling
220 the time between each retry until reaching this limit. If a server
221 requests a delay using the Retry-After header, the header value
222 overrides the exponential delay for that attempt and is not limited
223 by this option.
224 Must be an integer which is not negative. Use zero to disable
226 delays between retries unless requested by a server. If the value
227 is not an integer, is negative, or is not given, a value of ten
228 will be used instead.
229 • lfs.transfer.maxverifies
231 Specifies how many verification requests LFS will attempt per OID
233 before marking the transfer as failed, if the object has a
234 verification action associated with it. Must be an integer which is
235 at least one. If the value is not an integer, is less than one, or
236 is not given, a default value of three will be used instead.
237 • lfs.transfer.enablehrefrewrite
239 If set to true, this enables rewriting href of LFS objects using
241 url.*.insteadof/pushinsteadof config. pushinsteadof is used only
242 for uploading, and insteadof is used for downloading and for
243 uploading when pushinsteadof is not set.
244 Push settings
246 • lfs.allowincompletepush
247 When pushing, allow objects to be missing from the local cache
249 without halting a Git push. Default: false.
250 Fetch settings
252 • lfs.fetchinclude
253 When fetching, only download objects which match any entry on this
255 comma-separated list of paths/filenames. Wildcard matching is as
256 per gitignore(5). See git-lfs-fetch(1) for examples.
257 • lfs.fetchexclude
259 When fetching, do not download objects which match any item on this
261 comma-separated list of paths/filenames. Wildcard matching is as
262 per gitignore(5). See git-lfs-fetch(1) for examples.
263 • lfs.fetchrecentrefsdays
265 If non-zero, fetches refs which have commits within N days of the
267 current date. Only local refs are included unless
268 lfs.fetchrecentremoterefs is true. Also used as a basis for pruning
269 old files. The default is 7 days.
270 • lfs.fetchrecentremoterefs
272 If true, fetches remote refs (for the remote you’re fetching) as
274 well as local refs in the recent window. This is useful to fetch
275 objects for remote branches you might want to check out later. The
276 default is true; if you set this to false, fetching for those
277 branches will only occur when you either check them out (losing the
278 advantage of fetch --recent), or create a tracking local branch
279 separately then fetch again.
280 • lfs.fetchrecentcommitsdays
282 In addition to fetching at refs, also fetches previous changes made
284 within N days of the latest commit on the ref. This is useful if
285 you’re often reviewing recent changes. Also used as a basis for
286 pruning old files. The default is 0 (no previous changes).
287 • lfs.fetchrecentalways
289 Always operate as if --recent was included in a git lfs fetch call.
291 Default false.
292 Prune settings
294 • lfs.pruneoffsetdays
295 The number of days added to the lfs.fetchrecent* settings to
297 determine what can be pruned. Default is 3 days, i.e. that anything
298 fetched at the very oldest edge of the 'recent window' is eligible
299 for pruning 3 days later.
300 • lfs.pruneremotetocheck
302 Set the remote that LFS files must have been pushed to in order for
304 them to be considered eligible for local pruning. Also the remote
305 which is called if --verify-remote is enabled.
306 • lfs.pruneverifyremotealways
308 Always run git lfs prune as if --verify-remote was provided.
310 Extensions
312 • lfs.extension.<name>.<setting>
313 Git LFS extensions enable the manipulation of files streams during
315 smudge and clean. name groups the settings for a single extension,
316 and the settings are:
317 clean The command which runs when files are added to the index
318 smudge The command which runs when files are written to the
319 working copy ** priority The order of this extension compared to
320 others
321 Other settings
323 • lfs.<url>.access
324 Note: this setting is normally set by LFS itself on receiving a 401
326 response (authentication required), you don’t normally need to set
327 it manually.
328 If set to "basic" then credentials will be requested before making
330 batch requests to this url, otherwise a public request will
331 initially be attempted.
332 • lfs.<url>.locksverify
334 Determines whether locks are checked before Git pushes. This
336 prevents you from pushing changes to files that other users have
337 locked. The Git LFS pre-push hook varies its behavior based on the
338 value of this config key.
339 null - In the absence of a value, Git LFS will attempt the call,
340 and warn if it returns an error. If the response is valid, Git LFS
341 will set the value to true, and will halt the push if the user
342 attempts to update a file locked by another user. If the server
343 returns a 501 Not Implemented response, Git LFS will set the value
344 to false.
345 true - Git LFS will attempt to verify locks, halting the Git push
346 if there are any server issues, or if the user attempts to update a
347 file locked by another user. ** false - Git LFS will completely
348 skip the lock check in the pre-push hook. You should set this if
349 you’re not using File Locking, or your Git server verifies locked
350 files on pushes automatically.
351 + Supports URL config lookup as described in:
353 https://git-scm.com/docs/git-config#git-config-httplturlgt. To set
354 this value per-host: git config --global
355 lfs.https://github.com/.locksverify [true|false].
356 • lfs.<url>.contenttype
358 Determines whether Git LFS should attempt to detect an appropriate
360 HTTP Content-Type header when uploading using the 'basic' upload
361 adapter. If set to false, the default header of Content-Type:
362 application/octet-stream is chosen instead. Default: 'true'.
363 • lfs.skipdownloaderrors
365 Causes Git LFS not to abort the smudge filter when a download error
367 is encountered, which allows actions such as checkout to work when
368 you are unable to download the LFS content. LFS files which could
369 not download will contain pointer content instead.
370 Note that this will result in git commands which call the smudge
372 filter to report success even in cases when LFS downloads fail,
373 which may affect scripts.
374 You can also set the environment variable
376 GIT_LFS_SKIP_DOWNLOAD_ERRORS=1 to get the same effect.
377 • GIT_LFS_PROGRESS
379 This environment variable causes Git LFS to emit progress updates
381 to an absolute file-path on disk when cleaning, smudging, or
382 fetching.
383 Progress is reported periodically in the form of a new line being
385 appended to the end of the file. Each new line will take the
386 following format:
387 <direction> <current>/<total files> <downloaded>/<total> <name>
389 Each field is described below:
391 direction: The direction of transfer, either "checkout",
392 "download", or "upload".
393 current The index of the currently transferring file.
394 total files The estimated count of all files to be transferred.
395 downloaded The number of bytes already downloaded.
396 total The entire size of the file, in bytes.
397 name The name of the file.
398 • GIT_LFS_FORCE_PROGRESS lfs.forceprogress
400 Controls whether Git LFS will suppress progress status when the
402 standard output stream is not attached to a terminal. The default
403 is false which makes Git LFS detect whether stdout is a terminal
404 and suppress progress when it’s not; you can disable this behaviour
405 and force progress status even when standard output stream is not a
406 terminal by setting either variable to 1, 'yes' or 'true'.
407 • GIT_LFS_SKIP_SMUDGE
409 Sets whether or not Git LFS will skip attempting to convert
411 pointers of files tracked into their corresponding objects when
412 checked out into a working copy. If 'true', '1', 'on', or similar,
413 Git LFS will skip the smudge process in both git lfs smudge and git
414 lfs filter-process. If unset, or set to 'false', '0', 'off', or
415 similar, Git LFS will smudge files as normal.
416 • GIT_LFS_SKIP_PUSH
418 Sets whether or not Git LFS will attempt to upload new Git LFS
420 object in a pre-push hook. If 'true', '1', 'on', or similar, Git
421 LFS will skip the pre-push hook, so no new Git LFS objects will be
422 uploaded. If unset, or set to 'false', '0', 'off', or similar, Git
423 LFS will proceed as normal.
424 • GIT_LFS_SET_LOCKABLE_READONLY lfs.setlockablereadonly
426 These settings, the first an environment variable and the second a
428 gitconfig setting, control whether files marked as 'lockable' in
429 git lfs track are made read-only in the working copy when not
430 locked by the current user. The default is true; you can disable
431 this behaviour and have all files writeable by setting either
432 variable to 0, 'no' or 'false'.
433 • lfs.lockignoredfiles
435 This setting controls whether Git LFS will set ignored files that
437 match the lockable pattern read only as well as tracked files. The
438 default is false; you can enable this behavior by setting the
439 variable to 1, 'yes', or 'true'.
440 • lfs.defaulttokenttl
442 This setting sets a default token TTL when git-lfs-authenticate
444 does not include the TTL in the JSON response but still enforces
445 it.
446 Note that this is only necessary for larger repositories hosted on
448 LFS servers that don’t include the TTL.
449
451 The .lfsconfig file in a repository is read and interpreted in the same
452 format as the file stored in .git/config. It allows a subset of keys to
453 be used, including and limited to:
454 • lfs.allowincompletepush
456 • lfs.fetchexclude
458 • lfs.fetchinclude
460 • lfs.gitprotocol
462 • lfs.locksverify
464 • lfs.pushurl
466 • lfs.skipdownloaderrors
468 • lfs.url
470 • lfs.\{*}.access
472 • remote.{name}.lfsurl
474 The set of keys allowed in this file is restricted for security
476 reasons.
477
479 • Configure a custom LFS endpoint for your repository:
480 git config -f .lfsconfig lfs.url
482 https://lfs.example.com/foo/bar/info/lfs
483
485 git-config(1), git-lfs-install(1), gitattributes(5), gitignore(5).
486 Part of the git-lfs(1) suite.
488 GIT-LFS-CONFIG(5)