1GIT-LFS-CONFIG(5) File Formats Manual 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 configu‐
11 ration 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 reposi‐
17 tory, especially when these differ from the default. The .lfsconfig
18 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 envi‐
28 ronment 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.dialtimeout
62 Sets the maximum time, in seconds, that the HTTP client will wait
64 to initiate a connection. This does not include the time to send a
65 request and wait for a response. Default: 30 seconds
66 ○ lfs.tlstimeout
68 Sets the maximum time, in seconds, that the HTTP client will wait
70 for a TLS handshake. Default: 30 seconds.
71 ○ lfs.activitytimeout / lfs.https://<host>.activitytimeout
73 Sets the maximum time, in seconds, that the HTTP client will wait
75 for the next tcp read or write. If < 1, no activity timeout is used
76 at all. Default: 30 seconds
77 ○ lfs.keepalive
79 Sets the maximum time, in seconds, for the HTTP client to maintain
81 keepalive connections. Default: 30 minutes.
82 ○ lfs.ssh.automultiplex
84 When using the pure SSH-based protocol, whether to multiplex re‐
86 quests over a single connection when possible. This option requires
87 the use of OpenSSH or a compatible SSH client. Default: true.
88 ○ lfs.ssh.retries
90 Specifies the number of times Git LFS will attempt to obtain autho‐
92 rization via SSH before aborting. Default: 5.
93 ○ core.askpass, GIT_ASKPASS
95 Given as a program and its arguments, this is invoked when authen‐
97 tication is needed against the LFS API. The contents of stdout are
98 interpreted as the password.
99 ○ lfs.cachecredentials
101 Enables in-memory SSH and Git Credential caching for a single ´git
103 lfs´ command. Default: enabled.
104 ○ lfs.storage
106 Allow override LFS storage directory. Non-absolute path is rela‐
108 tivized to inside of Git repository directory (usually .git).
109 Note: you should not run git lfs prune if you have different repos‐
111 itories sharing the same storage directory.
112 Default: lfs in Git repository directory (usually .git/lfs).
114 ○ lfs.largefilewarning
116 Warn when a file is 4 GiB or larger. Such files will be corrupted
118 when using Windows (unless smudging is disabled) with a Git for
119 Windows version less than 2.34.0 due to a limitation in Git. De‐
120 fault: true if the version is less than 2.34.0, false otherwise.
121 Upload and download transfer settings
125 These settings control how the upload and download of LFS content oc‐
126 curs.
127 ○ lfs.concurrenttransfers
129 The number of concurrent uploads/downloads. Default 8.
131 ○ lfs.basictransfersonly
133 If set to true, only basic HTTP upload/download transfers will be
135 used, ignoring any more advanced transfers that the client/server
136 may support. This is primarily to work around bugs or incompatibil‐
137 ities.
138 The git-lfs client supports basic HTTP downloads, resumable HTTP
140 downloads (using Range headers), and resumable uploads via tus.io
141 protocol. Custom transfer methods can be added via lfs.customtrans‐
142 fer (see next section). However setting this value to true limits
143 the client to simple HTTP.
144 ○ lfs.tustransfers
146 If set to true, this enables resumable uploads of LFS objects
148 through the tus.io API. Once this feature is finalized, this set‐
149 ting will be removed, and tus.io uploads will be available for all
150 clients.
151 ○ lfs.standalonetransferagent
153 Allows the specified custom transfer agent to be used directly for
155 transferring files, without asking the server how the transfers
156 should be made. The custom transfer agent has to be defined in a
157 lfs.customtransfer.<name> settings group.
158 ○ lfs.customtransfer.<name>.path
160 lfs.customtransfer.<name> is a settings group which defines a cus‐
162 tom transfer hook which allows you to upload/download via an inter‐
163 mediate process, using any mechanism you like (rather than just
164 HTTP). path should point to the process you wish to invoke. The
165 protocol between the git-lfs client and the custom transfer process
166 is documented at
167 https://github.com/git-lfs/git-lfs/blob/main/docs/custom-trans‐
168 fers.md
169 name must be a unique identifier that the LFS server understands.
171 When calling the LFS API the client will include a list of sup‐
172 ported transfer types. If the server also supports this named
173 transfer type, it will select it and actions returned from the API
174 will be in relation to that transfer type (may not be traditional
175 URLs for example). Only if the server accepts name as a transfer it
176 supports will this custom transfer process be invoked.
177 ○ lfs.customtransfer.<name>.args
179 If the custom transfer process requires any arguments, these can be
181 provided here. This string will be expanded by the shell.
182 ○ lfs.customtransfer.<name>.concurrent
184 If true (the default), git-lfs will invoke the custom transfer
186 process multiple times in parallel, according to lfs.concurrent‐
187 transfers, splitting the transfer workload between the processes.
188 ○ lfs.customtransfer.<name>.direction
190 Specifies which direction the custom transfer process supports, ei‐
192 ther "download", "upload", or "both". The default if unspecified is
193 "both".
194 ○ lfs.transfer.maxretries
196 Specifies how many retries LFS will attempt per OID before marking
198 the transfer as failed. Must be an integer which is at least one.
199 If the value is not an integer, is less than one, or is not given,
200 a value of eight will be used instead.
201 ○ lfs.transfer.maxretrydelay
203 Specifies the maximum time in seconds LFS will wait between each
205 retry attempt. LFS uses exponential backoff for retries, doubling
206 the time between each retry until reaching this limit. If a server
207 requests a delay using the Retry-After header, the header value
208 overrides the exponential delay for that attempt and is not limited
209 by this option.
210 Must be an integer which is not negative. Use zero to disable de‐
212 lays between retries unless requested by a server. If the value is
213 not an integer, is negative, or is not given, a value of ten will
214 be used instead.
215 ○ lfs.transfer.maxverifies
217 Specifies how many verification requests LFS will attempt per OID
219 before marking the transfer as failed, if the object has a verifi‐
220 cation action associated with it. Must be an integer which is at
221 least one. If the value is not an integer, is less than one, or is
222 not given, a default value of three will be used instead.
223 ○ lfs.transfer.enablehrefrewrite
225 If set to true, this enables rewriting href of LFS objects using
227 url.*.insteadof/pushinsteadof config. pushinsteadof is used only
228 for uploading, and insteadof is used for downloading and for up‐
229 loading when pushinsteadof is not set.
230 Push settings
234 ○ lfs.allowincompletepush
235 When pushing, allow objects to be missing from the local cache
237 without halting a Git push. Default: false.
238 Fetch settings
242 ○ lfs.fetchinclude
243 When fetching, only download objects which match any entry on this
245 comma-separated list of paths/filenames. Wildcard matching is as
246 per git-ignore(1). See git-lfs-fetch(1) for examples.
247 ○ lfs.fetchexclude
249 When fetching, do not download objects which match any item on this
251 comma-separated list of paths/filenames. Wildcard matching is as
252 per git-ignore(1). See git-lfs-fetch(1) for examples.
253 ○ lfs.fetchrecentrefsdays
255 If non-zero, fetches refs which have commits within N days of the
257 current date. Only local refs are included unless lfs.fetchrecen‐
258 tremoterefs is true. Also used as a basis for pruning old files.
259 The default is 7 days.
260 ○ lfs.fetchrecentremoterefs
262 If true, fetches remote refs (for the remote you´re fetching) as
264 well as local refs in the recent window. This is useful to fetch
265 objects for remote branches you might want to check out later. The
266 default is true; if you set this to false, fetching for those
267 branches will only occur when you either check them out (losing the
268 advantage of fetch --recent), or create a tracking local branch
269 separately then fetch again.
270 ○ lfs.fetchrecentcommitsdays
272 In addition to fetching at refs, also fetches previous changes made
274 within N days of the latest commit on the ref. This is useful if
275 you´re often reviewing recent changes. Also used as a basis for
276 pruning old files. The default is 0 (no previous changes).
277 ○ lfs.fetchrecentalways
279 Always operate as if --recent was included in a git lfs fetch call.
281 Default false.
282 Prune settings
286 ○ lfs.pruneoffsetdays
287 The number of days added to the lfs.fetchrecent* settings to deter‐
289 mine what can be pruned. Default is 3 days, i.e. that anything
290 fetched at the very oldest edge of the ´recent window´ is eligible
291 for pruning 3 days later.
292 ○ lfs.pruneremotetocheck
294 Set the remote that LFS files must have been pushed to in order for
296 them to be considered eligible for local pruning. Also the remote
297 which is called if --verify-remote is enabled.
298 ○ lfs.pruneverifyremotealways
300 Always run git lfs prune as if --verify-remote was provided.
302 Extensions
306 ○ lfs.extension.<name>.<setting>
307 Git LFS extensions enable the manipulation of files streams during
309 smudge and clean. name groups the settings for a single extension,
310 and the settings are: * clean The command which runs when files are
311 added to the index * smudge The command which runs when files are
312 written to the working copy * priority The order of this extension
313 compared to others
314 Other settings
318 ○ lfs.<url>.access
319 Note: this setting is normally set by LFS itself on receiving a 401
321 response (authentication required), you don´t normally need to set
322 it manually.
323 If set to "basic" then credentials will be requested before making
325 batch requests to this url, otherwise a public request will ini‐
326 tially be attempted.
327 ○ lfs.<url>.locksverify
329 Determines whether locks are checked before Git pushes. This pre‐
331 vents you from pushing changes to files that other users have
332 locked. The Git LFS pre-push hook varies its behavior based on the
333 value of this config key.
334 ○ null - In the absence of a value, Git LFS will attempt the call,
336 and warn if it returns an error. If the response is valid, Git LFS
337 will set the value to true, and will halt the push if the user at‐
338 tempts to update a file locked by another user. If the server re‐
339 turns a 501 Not Implemented response, Git LFS will set the value to
340 false.
341 ○ true - Git LFS will attempt to verify locks, halting the Git push
343 if there are any server issues, or if the user attempts to update a
344 file locked by another user.
345 ○ false - Git LFS will completely skip the lock check in the pre-push
347 hook. You should set this if you´re not using File Locking, or your
348 Git server verifies locked files on pushes automatically.
349 Supports URL config lookup as described in:
353 https://git-scm.com/docs/git-config#git-config-httplturlgt. To set this
354 value per-host: git config --global lfs.https://github.com/.locksverify
355 [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: ap‐
362 plication/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 GIT_LFS_SKIP_DOWNLOAD_ER‐
376 RORS=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 fetch‐
382 ing.
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 fol‐
386 lowing format:
387 <direction> <current>/<total files> <downloaded>/<total> <name>
389 Each field is described below: * direction: The direction of trans‐
391 fer, either "checkout", "download", or "upload". * current The in‐
392 dex of the currently transferring file. * total files The estimated
393 count of all files to be transferred. * downloaded The number of
394 bytes already downloaded. * total The entire size of the file, in
395 bytes. * name The name of the file.
396 ○ GIT_LFS_FORCE_PROGRESS lfs.forceprogress
398 Controls whether Git LFS will suppress progress status when the
400 standard output stream is not attached to a terminal. The default
401 is false which makes Git LFS detect whether stdout is a terminal
402 and suppress progress when it´s not; you can disable this behaviour
403 and force progress status even when standard output stream is not a
404 terminal by setting either variable to 1, ´yes´ or ´true´.
405 ○ GIT_LFS_SKIP_SMUDGE
407 Sets whether or not Git LFS will skip attempting to convert point‐
409 ers of files tracked into their corresponding objects when checked
410 out into a working copy. If ´true´, ´1´, ´on´, or similar, Git LFS
411 will skip the smudge process in both git lfs smudge and git lfs
412 filter-process. If unset, or set to ´false´, ´0´, ´off´, or simi‐
413 lar, Git LFS will smudge files as normal.
414 ○ GIT_LFS_SKIP_PUSH
416 Sets whether or not Git LFS will attempt to upload new Git LFS ob‐
418 ject in a pre-push hook. If ´true´, ´1´, ´on´, or similar, Git LFS
419 will skip the pre-push hook, so no new Git LFS objects will be up‐
420 loaded. If unset, or set to ´false´, ´0´, ´off´, or similar, Git
421 LFS will proceed as normal.
422 ○ GIT_LFS_SET_LOCKABLE_READONLY lfs.setlockablereadonly
424 These settings, the first an environment variable and the second a
426 gitconfig setting, control whether files marked as ´lockable´ in
427 git lfs track are made read-only in the working copy when not
428 locked by the current user. The default is true; you can disable
429 this behaviour and have all files writeable by setting either vari‐
430 able to 0, ´no´ or ´false´.
431 ○ lfs.lockignoredfiles
433 This setting controls whether Git LFS will set ignored files that
435 match the lockable pattern read only as well as tracked files. The
436 default is false; you can enable this behavior by setting the vari‐
437 able to 1, ´yes´, or ´true´.
438 ○ lfs.defaulttokenttl
440 This setting sets a default token TTL when git-lfs-authenticate
442 does not include the TTL in the JSON response but still enforces
443 it.
444 Note that this is only necessary for larger repositories hosted on
446 LFS servers that don´t include the TTL.
447
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 rea‐
478 sons.
479
481 Configure a custom LFS endpoint for your repository:
482 git config -f .lfsconfig lfs.url https://lfs.exam‐
485 ple.com/foo/bar/info/lfs
486
488 git-config(1), git-lfs-install(1), gitattributes(5)
489 Part of the git-lfs(1) suite.
491 February 2022 GIT-LFS-CONFIG(5)