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 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 · lfs.dialtimeout
47 Sets the maximum time, in seconds, that the HTTP client will wait
49 to initiate a connection. This does not include the time to send a
50 request and wait for a response. Default: 30 seconds
51 · lfs.tlstimeout
53 Sets the maximum time, in seconds, that the HTTP client will wait
55 for a TLS handshake. Default: 30 seconds.
56 · lfs.activitytimeout / lfs.https://<host>.activitytimeout
58 Sets the maximum time, in seconds, that the HTTP client will wait
60 for the next tcp read or write. If < 1, no activity timeout is used
61 at all. Default: 30 seconds
62 · lfs.keepalive
64 Sets the maximum time, in seconds, for the HTTP client to maintain
66 keepalive connections. Default: 30 minutes.
67 · lfs.ssh.retries
69 Specifies the number of times Git LFS will attempt to obtain autho‐
71 rization via SSH before aborting. Default: 5.
72 · core.askpass, GIT_ASKPASS
74 Given as a program and its arguments, this is invoked when authen‐
76 tication is needed against the LFS API. The contents of stdout are
77 interpreted as the password.
78 · lfs.cachecredentials
80 Enables in-memory SSH and Git Credential caching for a single ´git
82 lfs´ command. Default: enabled.
83 · lfs.storage
85 Allow override LFS storage directory. Non-absolute path is rela‐
87 tivized to inside of Git repository directory (usually .git).
88 Note: you should not run git lfs prune if you have different repos‐
90 itories sharing the same storage directory.
91 Default: lfs in Git repository directory (usually .git/lfs).
93 · lfs.largefilewarning
95 Warn when a file is 4 GiB or larger. Such files will be corrupted
97 when using Windows (unless smudging is disabled) due to a limita‐
98 tion in Git. Default: true.
99 Transfer (upload / download) settings
103 These settings control how the upload and download of LFS content
104 occurs.
105 · lfs.concurrenttransfers
107 The number of concurrent uploads/downloads. Default 8.
109 · lfs.basictransfersonly
111 If set to true, only basic HTTP upload/download transfers will be
113 used, ignoring any more advanced transfers that the client/server
114 may support. This is primarily to work around bugs or incompatibil‐
115 ities.
116 The git-lfs client supports basic HTTP downloads, resumable HTTP
118 downloads (using Range headers), and resumable uploads via tus.io
119 protocol. Custom transfer methods can be added via lfs.customtrans‐
120 fer (see next section). However setting this value to true limits
121 the client to simple HTTP.
122 · lfs.tustransfers
124 If set to true, this enables resumable uploads of LFS objects
126 through the tus.io API. Once this feature is finalized, this set‐
127 ting will be removed, and tus.io uploads will be available for all
128 clients.
129 · lfs.standalonetransferagent
131 Allows the specified custom transfer agent to be used directly for
133 transferring files, without asking the server how the transfers
134 should be made. The custom transfer agent has to be defined in a
135 lfs.customtransfer.<name> settings group.
136 · lfs.customtransfer.<name>.path
138 lfs.customtransfer.<name> is a settings group which defines a cus‐
140 tom transfer hook which allows you to upload/download via an inter‐
141 mediate process, using any mechanism you like (rather than just
142 HTTP). path should point to the process you wish to invoke. The
143 protocol between the git-lfs client and the custom transfer process
144 is documented at https://github.com/git-lfs/git-lfs/blob/mas‐
145 ter/docs/custom-transfers.md
146 name must be a unique identifier that the LFS server understands.
148 When calling the LFS API the client will include a list of sup‐
149 ported transfer types. If the server also supports this named
150 transfer type, it will select it and actions returned from the API
151 will be in relation to that transfer type (may not be traditional
152 URLs for example). Only if the server accepts name as a transfer it
153 supports will this custom transfer process be invoked.
154 · lfs.customtransfer.<name>.args
156 If the custom transfer process requires any arguments, these can be
158 provided here. This string will be expanded by the shell.
159 · lfs.customtransfer.<name>.concurrent
161 If true (the default), git-lfs will invoke the custom transfer
163 process multiple times in parallel, according to lfs.concurrent‐
164 transfers, splitting the transfer workload between the processes.
165 · lfs.customtransfer.<name>.direction
167 Specifies which direction the custom transfer process supports,
169 either "download", "upload", or "both". The default if unspecified
170 is "both".
171 · lfs.transfer.maxretries
173 Specifies how many retries LFS will attempt per OID before marking
175 the transfer as failed. Must be an integer which is at least one.
176 If the value is not an integer, is less than one, or is not given,
177 a value of eight will be used instead.
178 · lfs.transfer.maxretrydelay
180 Specifies the maximum time in seconds LFS will wait between each
182 retry attempt. LFS uses exponential backoff for retries, doubling
183 the time between each retry until reaching this limit. If a server
184 requests a delay using the Retry-After header, the header value
185 overrides the exponential delay for that attempt and is not limited
186 by this option.
187 Must be an integer which is not negative. Use zero to disable
189 delays between retries unless requested by a server. If the value
190 is not an integer, is negative, or is not given, a value of ten
191 will be used instead.
192 · lfs.transfer.maxverifies
194 Specifies how many verification requests LFS will attempt per OID
196 before marking the transfer as failed, if the object has a verifi‐
197 cation action associated with it. Must be an integer which is at
198 least one. If the value is not an integer, is less than one, or is
199 not given, a default value of three will be used instead.
200 · lfs.transfer.enablehrefrewrite
202 If set to true, this enables rewriting href of LFS objects using
204 url.*.insteadof/pushinsteadof config. pushinsteadof is used only
205 for uploading, and insteadof is used for downloading and for
206 uploading when pushinsteadof is not set.
207 Push settings
211 · lfs.allowincompletepush
212 When pushing, allow objects to be missing from the local cache
214 without halting a Git push. Default: false.
215 Fetch settings
219 · lfs.fetchinclude
220 When fetching, only download objects which match any entry on this
222 comma-separated list of paths/filenames. Wildcard matching is as
223 per git-ignore(1). See git-lfs-fetch(1) for examples.
224 · lfs.fetchexclude
226 When fetching, do not download objects which match any item on this
228 comma-separated list of paths/filenames. Wildcard matching is as
229 per git-ignore(1). See git-lfs-fetch(1) for examples.
230 · lfs.fetchrecentrefsdays
232 If non-zero, fetches refs which have commits within N days of the
234 current date. Only local refs are included unless lfs.fetchrecen‐
235 tremoterefs is true. Also used as a basis for pruning old files.
236 The default is 7 days.
237 · lfs.fetchrecentremoterefs
239 If true, fetches remote refs (for the remote you´re fetching) as
241 well as local refs in the recent window. This is useful to fetch
242 objects for remote branches you might want to check out later. The
243 default is true; if you set this to false, fetching for those
244 branches will only occur when you either check them out (losing the
245 advantage of fetch --recent), or create a tracking local branch
246 separately then fetch again.
247 · lfs.fetchrecentcommitsdays
249 In addition to fetching at refs, also fetches previous changes made
251 within N days of the latest commit on the ref. This is useful if
252 you´re often reviewing recent changes. Also used as a basis for
253 pruning old files. The default is 0 (no previous changes).
254 · lfs.fetchrecentalways
256 Always operate as if --recent was included in a git lfs fetch call.
258 Default false.
259 Prune settings
263 · lfs.pruneoffsetdays
264 The number of days added to the lfs.fetchrecent* settings to deter‐
266 mine what can be pruned. Default is 3 days, i.e. that anything
267 fetched at the very oldest edge of the ´recent window´ is eligible
268 for pruning 3 days later.
269 · lfs.pruneremotetocheck
271 Set the remote that LFS files must have been pushed to in order for
273 them to be considered eligible for local pruning. Also the remote
274 which is called if --verify-remote is enabled.
275 · lfs.pruneverifyremotealways
277 Always run git lfs prune as if --verify-remote was provided.
279 Extensions
283 · lfs.extension.<name>.<setting>
284 Git LFS extensions enable the manipulation of files streams during
286 smudge and clean. name groups the settings for a single extension,
287 and the settings are:
288 · clean The command which runs when files are added to the index
290 · smudge The command which runs when files are written to the working
292 copy
293 · priority The order of this extension compared to others
295 Other settings
302 · lfs.<url>.access
303 Note: this setting is normally set by LFS itself on receiving a 401
305 response (authentication required), you don´t normally need to set
306 it manually.
307 If set to "basic" then credentials will be requested before making
309 batch requests to this url, otherwise a public request will ini‐
310 tially be attempted.
311 · lfs.<url>.locksverify
313 Determines whether locks are checked before Git pushes. This pre‐
315 vents you from pushing changes to files that other users have
316 locked. The Git LFS pre-push hook varies its behavior based on the
317 value of this config key.
318 · null - In the absence of a value, Git LFS will attempt the call,
320 and warn if it returns an error. If the response is valid, Git LFS
321 will set the value to true, and will halt the push if the user
322 attempts to update a file locked by another user. If the server
323 returns a 501 Not Implemented response, Git LFS will set the value
324 to false.
325 · true - Git LFS will attempt to verify locks, halting the Git push
327 if there are any server issues, or if the user attempts to update a
328 file locked by another user.
329 · false - Git LFS will completely skip the lock check in the pre-push
331 hook. You should set this if you´re not using File Locking, or your
332 Git server verifies locked files on pushes automatically.
333 Supports URL config lookup as described in:
337 https://git-scm.com/docs/git-config#git-config-httplturlgt. To set this
338 value per-host: git config --global lfs.https://github.com/.locksverify
339 [true|false].
340 · lfs.<url>.contenttype
342 Determines whether Git LFS should attempt to detect an appropriate
344 HTTP Content-Type header when uploading using the ´basic´ upload
345 adapter. If set to false, the default header of Content-Type:
346 application/octet-stream is chosen instead. Default: ´true´.
347 · lfs.skipdownloaderrors
349 Causes Git LFS not to abort the smudge filter when a download error
351 is encountered, which allows actions such as checkout to work when
352 you are unable to download the LFS content. LFS files which could
353 not download will contain pointer content instead.
354 Note that this will result in git commands which call the smudge
356 filter to report success even in cases when LFS downloads fail,
357 which may affect scripts.
358 You can also set the environment variable GIT_LFS_SKIP_DOWN‐
360 LOAD_ERRORS=1 to get the same effect.
361 · GIT_LFS_PROGRESS
363 This environment variable causes Git LFS to emit progress updates
365 to an absolute file-path on disk when cleaning, smudging, or fetch‐
366 ing.
367 Progress is reported periodically in the form of a new line being
369 appended to the end of the file. Each new line will take the fol‐
370 lowing format:
371 <direction> <current>/<total files> <downloaded>/<total> <name>
373 Each field is described below:
375 · direction: The direction of transfer, either "checkout", "down‐
377 load", or "upload".
378 · current The index of the currently transferring file.
380 · total files The estimated count of all files to be transferred.
382 · downloaded The number of bytes already downloaded.
384 · total The entire size of the file, in bytes.
386 · name The name of the file.
388 · GIT_LFS_FORCE_PROGRESS lfs.forceprogress
393 Controls whether Git LFS will suppress progress status when the
395 standard output stream is not attached to a terminal. The default
396 is false which makes Git LFS detect whether stdout is a terminal
397 and suppress progress when it´s not; you can disable this behaviour
398 and force progress status even when standard output stream is not a
399 terminal by setting either variable to 1, ´yes´ or ´true´.
400 · GIT_LFS_SKIP_SMUDGE
402 Sets whether or not Git LFS will skip attempting to convert point‐
404 ers of files tracked into their corresponding objects when checked
405 out into a working copy. If ´true´, ´1´, ´on´, or similar, Git LFS
406 will skip the smudge process in both git lfs smudge and git lfs
407 filter-process. If unset, or set to ´false´, ´0´, ´off´, or simi‐
408 lar, Git LFS will smudge files as normal.
409 · GIT_LFS_SKIP_PUSH
411 Sets whether or not Git LFS will attempt to upload new Git LFS
413 object in a pre-push hook. If ´true´, ´1´, ´on´, or similar, Git
414 LFS will skip the pre-push hook, so no new Git LFS objects will be
415 uploaded. If unset, or set to ´false´, ´0´, ´off´, or similar, Git
416 LFS will proceed as normal.
417 · GIT_LFS_SET_LOCKABLE_READONLY lfs.setlockablereadonly
419 These settings, the first an environment variable and the second a
421 gitconfig setting, control whether files marked as ´lockable´ in
422 git lfs track are made read-only in the working copy when not
423 locked by the current user. The default is true; you can disable
424 this behaviour and have all files writeable by setting either vari‐
425 able to 0, ´no´ or ´false´.
426 · lfs.lockignoredfiles
428 This setting controls whether Git LFS will set ignored files that
430 match the lockable pattern read only as well as tracked files. The
431 default is false; you can enable this behavior by setting the vari‐
432 able to 1, ´yes´, or ´true´.
433 · lfs.defaulttokenttl
435 This setting sets a default token TTL when git-lfs-authenticate
437 does not include the TTL in the JSON response but still enforces
438 it.
439 Note that this is only necessary for larger repositories hosted on
441 LFS servers that don´t include the TTL.
442
446 The .lfsconfig file in a repository is read and interpreted in the same
447 format as the file stored in .git/config. It allows a subset of keys to
448 be used, including and limited to:
449 · lfs.allowincompletepush
451 · lfs.fetchexclude
453 · lfs.fetchinclude
455 · lfs.gitprotocol
457 · lfs.locksverify
459 · lfs.pushurl
461 · lfs.url
463 · remote.{name}.lfsurl
465 · lfs.{*}.access
467 The set of keys allowed in this file is restricted for security rea‐
471 sons.
472
474 Configure a custom LFS endpoint for your repository:
475 git config -f .lfsconfig lfs.url https://lfs.exam‐
478 ple.com/foo/bar/info/lfs
479
481 git-config(1), git-lfs-install(1), gitattributes(5)
482 Part of the git-lfs(1) suite.
484 March 2021 GIT-LFS-CONFIG(5)