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 Settings from Git configuration files override the .lfsconfig file.
21 This allows you to override settings like lfs.url in your local envi‐
22 ronment without having to modify the .lfsconfig file.
23 Most options regarding git-lfs are contained in the [lfs] section,
25 meaning they are all named lfs.foo or similar, although occasionally an
26 lfs option can be scoped inside the configuration for a remote.
27
29 General settings
30 · lfs.url / remote.<remote>.lfsurl
31 The url used to call the Git LFS remote API. Default blank (derive
33 from clone URL).
34 · lfs.pushurl / remote.<remote>.lfspushurl
36 The url used to call the Git LFS remote API when pushing. Default
38 blank (derive from either LFS non-push urls or clone url).
39 · lfs.dialtimeout
41 Sets the maximum time, in seconds, that the HTTP client will wait
43 to initiate a connection. This does not include the time to send a
44 request and wait for a response. Default: 30 seconds
45 · lfs.tlstimeout
47 Sets the maximum time, in seconds, that the HTTP client will wait
49 for a TLS handshake. Default: 30 seconds.
50 · lfs.activitytimeout / lfs.https://<host>.activitytimeout
52 Sets the maximum time, in seconds, that the HTTP client will wait
54 for the next tcp read or write. If < 1, no activity timeout is used
55 at all. Default: 30 seconds
56 · lfs.keepalive
58 Sets the maximum time, in seconds, for the HTTP client to maintain
60 keepalive connections. Default: 30 minutes.
61 · lfs.ssh.retries
63 Specifies the number of times Git LFS will attempt to obtain autho‐
65 rization via SSH before aborting. Default: 5.
66 · core.askpass, GIT_ASKPASS
68 Given as a program and its arguments, this is invoked when authen‐
70 tication is needed against the LFS API. The contents of stdout are
71 interpreted as the password.
72 · lfs.cachecredentials
74 Enables in-memory SSH and Git Credential caching for a single ´git
76 lfs´ command. Default: enabled.
77 · lfs.storage
79 Allow override LFS storage directory. Non-absolute path is rela‐
81 tivized to inside of Git repository directory (usually .git).
82 Note: you should not run git lfs prune if you have different repos‐
84 itories sharing the same storage directory.
85 Default: lfs in Git repository directory (usually .git/lfs).
87 Transfer (upload / download) settings
91 These settings control how the upload and download of LFS content
92 occurs.
93 · lfs.concurrenttransfers
95 The number of concurrent uploads/downloads. Default 8.
97 · lfs.basictransfersonly
99 If set to true, only basic HTTP upload/download transfers will be
101 used, ignoring any more advanced transfers that the client/server
102 may support. This is primarily to work around bugs or incompatibil‐
103 ities.
104 The git-lfs client supports basic HTTP downloads, resumable HTTP
106 downloads (using Range headers), and resumable uploads via tus.io
107 protocol. Custom transfer methods can be added via lfs.customtrans‐
108 fer (see next section). However setting this value to true limits
109 the client to simple HTTP.
110 · lfs.tustransfers
112 If set to true, this enables resumable uploads of LFS objects
114 through the tus.io API. Once this feature is finalized, this set‐
115 ting will be removed, and tus.io uploads will be available for all
116 clients.
117 · lfs.standalonetransferagent
119 Allows the specified custom transfer agent to be used directly for
121 transferring files, without asking the server how the transfers
122 should be made. The custom transfer agent has to be defined in a
123 lfs.customtransfer.<name> settings group.
124 · lfs.customtransfer.<name>.path
126 lfs.customtransfer.<name> is a settings group which defines a cus‐
128 tom transfer hook which allows you to upload/download via an inter‐
129 mediate process, using any mechanism you like (rather than just
130 HTTP). path should point to the process you wish to invoke. The
131 protocol between the git-lfs client and the custom transfer process
132 is documented at https://github.com/git-lfs/git-lfs/blob/mas‐
133 ter/docs/custom-transfers.md
134 name must be a unique identifier that the LFS server understands.
136 When calling the LFS API the client will include a list of sup‐
137 ported transfer types. If the server also supports this named
138 transfer type, it will select it and actions returned from the API
139 will be in relation to that transfer type (may not be traditional
140 URLs for example). Only if the server accepts name as a transfer it
141 supports will this custom transfer process be invoked.
142 · lfs.customtransfer.<name>.args
144 If the custom transfer process requires any arguments, these can be
146 provided here. This string will be expanded by the shell.
147 · lfs.customtransfer.<name>.concurrent
149 If true (the default), git-lfs will invoke the custom transfer
151 process multiple times in parallel, according to lfs.concurrent‐
152 transfers, splitting the transfer workload between the processes.
153 · lfs.customtransfer.<name>.direction
155 Specifies which direction the custom transfer process supports,
157 either "download", "upload", or "both". The default if unspecified
158 is "both".
159 · lfs.transfer.maxretries
161 Specifies how many retries LFS will attempt per OID before marking
163 the transfer as failed. Must be an integer which is at least one.
164 If the value is not an integer, is less than one, or is not given,
165 a value of eight will be used instead.
166 · lfs.transfer.maxverifies
168 Specifies how many verification requests LFS will attempt per OID
170 before marking the transfer as failed, if the object has a verifi‐
171 cation action associated with it. Must be an integer which is at
172 least one. If the value is not an integer, is less than one, or is
173 not given, a default value of three will be used instead.
174 · lfs.transfer.enablehrefrewrite
176 If set to true, this enables rewriting href of LFS objects using
178 url.*.insteadof/pushinsteadof config. pushinsteadof is used only
179 for uploading, and insteadof is used for downloading and for
180 uploading when pushinsteadof is not set.
181 Push settings
185 · lfs.allowincompletepush
186 When pushing, allow objects to be missing from the local cache
188 without halting a Git push. Default: false.
189 Fetch settings
193 · lfs.fetchinclude
194 When fetching, only download objects which match any entry on this
196 comma-separated list of paths/filenames. Wildcard matching is as
197 per git-ignore(1). See git-lfs-fetch(1) for examples.
198 · lfs.fetchexclude
200 When fetching, do not download objects which match any item on this
202 comma-separated list of paths/filenames. Wildcard matching is as
203 per git-ignore(1). See git-lfs-fetch(1) for examples.
204 · lfs.fetchrecentrefsdays
206 If non-zero, fetches refs which have commits within N days of the
208 current date. Only local refs are included unless lfs.fetchrecen‐
209 tremoterefs is true. Also used as a basis for pruning old files.
210 The default is 7 days.
211 · lfs.fetchrecentremoterefs
213 If true, fetches remote refs (for the remote you´re fetching) as
215 well as local refs in the recent window. This is useful to fetch
216 objects for remote branches you might want to check out later. The
217 default is true; if you set this to false, fetching for those
218 branches will only occur when you either check them out (losing the
219 advantage of fetch --recent), or create a tracking local branch
220 separately then fetch again.
221 · lfs.fetchrecentcommitsdays
223 In addition to fetching at refs, also fetches previous changes made
225 within N days of the latest commit on the ref. This is useful if
226 you´re often reviewing recent changes. Also used as a basis for
227 pruning old files. The default is 0 (no previous changes).
228 · lfs.fetchrecentalways
230 Always operate as if --recent was included in a git lfs fetch call.
232 Default false.
233 Prune settings
237 · lfs.pruneoffsetdays
238 The number of days added to the lfs.fetchrecent* settings to deter‐
240 mine what can be pruned. Default is 3 days, i.e. that anything
241 fetched at the very oldest edge of the ´recent window´ is eligible
242 for pruning 3 days later.
243 · lfs.pruneremotetocheck
245 Set the remote that LFS files must have been pushed to in order for
247 them to be considered eligible for local pruning. Also the remote
248 which is called if --verify-remote is enabled.
249 · lfs.pruneverifyremotealways
251 Always run git lfs prune as if --verify-remote was provided.
253 Extensions
257 · lfs.extension.<name>.<setting>
258 Git LFS extensions enable the manipulation of files streams during
260 smudge and clean. name groups the settings for a single extension,
261 and the settings are:
262 · clean The command which runs when files are added to the index
264 · smudge The command which runs when files are written to the working
266 copy
267 · priority The order of this extension compared to others
269 Other settings
276 · lfs.<url>.access
277 Note: this setting is normally set by LFS itself on receiving a 401
279 response (authentication required), you don´t normally need to set
280 it manually.
281 If set to "basic" then credentials will be requested before making
283 batch requests to this url, otherwise a public request will ini‐
284 tially be attempted.
285 · lfs.<url>.locksverify
287 Determines whether locks are checked before Git pushes. This pre‐
289 vents you from pushing changes to files that other users have
290 locked. The Git LFS pre-push hook varies its behavior based on the
291 value of this config key.
292 · null - In the absence of a value, Git LFS will attempt the call,
294 and warn if it returns an error. If the response is valid, Git LFS
295 will set the value to true, and will halt the push if the user
296 attempts to update a file locked by another user. If the server
297 returns a 501 Not Implemented response, Git LFS will set the value
298 to false.
299 · true - Git LFS will attempt to verify locks, halting the Git push
301 if there are any server issues, or if the user attempts to update a
302 file locked by another user.
303 · false - Git LFS will completely skip the lock check in the pre-push
305 hook. You should set this if you´re not using File Locking, or your
306 Git server verifies locked files on pushes automatically.
307 Supports URL config lookup as described in:
311 https://git-scm.com/docs/git-config#git-config-httplturlgt. To set this
312 value per-host: git config --global lfs.https://github.com/.locksverify
313 [true|false].
314 · lfs.<url>.contenttype
316 Determines whether Git LFS should attempt to detect an appropriate
318 HTTP Content-Type header when uploading using the ´basic´ upload
319 adapter. If set to false, the default header of Content-Type:
320 application/octet-stream is chosen instead. Default: ´true´.
321 · lfs.skipdownloaderrors
323 Causes Git LFS not to abort the smudge filter when a download error
325 is encountered, which allows actions such as checkout to work when
326 you are unable to download the LFS content. LFS files which could
327 not download will contain pointer content instead.
328 Note that this will result in git commands which call the smudge
330 filter to report success even in cases when LFS downloads fail,
331 which may affect scripts.
332 You can also set the environment variable GIT_LFS_SKIP_DOWN‐
334 LOAD_ERRORS=1 to get the same effect.
335 · GIT_LFS_PROGRESS
337 This environment variable causes Git LFS to emit progress updates
339 to an absolute file-path on disk when cleaning, smudging, or fetch‐
340 ing.
341 Progress is reported periodically in the form of a new line being
343 appended to the end of the file. Each new line will take the fol‐
344 lowing format:
345 <direction> <current>/<total files> <downloaded>/<total> <name>
347 Each field is described below:
349 · direction: The direction of transfer, either "checkout", "down‐
351 load", or "upload".
352 · current The index of the currently transferring file.
354 · total files The estimated count of all files to be transferred.
356 · downloaded The number of bytes already downloaded.
358 · total The entire size of the file, in bytes.
360 · name The name of the file.
362 · GIT_LFS_FORCE_PROGRESS lfs.forceprogress
367 Controls whether Git LFS will suppress progress status when the
369 standard output stream is not attached to a terminal. The default
370 is false which makes Git LFS detect whether stdout is a terminal
371 and suppress progress when it´s not; you can disable this behaviour
372 and force progress status even when standard output stream is not a
373 terminal by setting either variable to 1, ´yes´ or ´true´.
374 · GIT_LFS_SKIP_SMUDGE
376 Sets whether or not Git LFS will skip attempting to convert point‐
378 ers of files tracked into their corresponding objects when checked
379 out into a working copy. If ´true´, ´1´, ´on´, or similar, Git LFS
380 will skip the smudge process in both git lfs smudge and git lfs
381 filter-process. If unset, or set to ´false´, ´0´, ´off´, or simi‐
382 lar, Git LFS will smudge files as normal.
383 · GIT_LFS_SET_LOCKABLE_READONLY lfs.setlockablereadonly
385 These settings, the first an environment variable and the second a
387 gitconfig setting, control whether files marked as ´lockable´ in
388 git lfs track are made read-only in the working copy when not
389 locked by the current user. The default is true; you can disable
390 this behaviour and have all files writeable by setting either vari‐
391 able to 0, ´no´ or ´false´.
392 · lfs.lockignoredfiles
394 This setting controls whether Git LFS will set ignored files that
396 match the lockable pattern read only as well as tracked files. The
397 default is false; you can enable this behavior by setting the vari‐
398 able to 1, ´yes´, or ´true´.
399 · lfs.defaulttokenttl
401 This setting sets a default token TTL when git-lfs-authenticate
403 does not include the TTL in the JSON response but still enforces
404 it.
405 Note that this is only necessary for larger repositories hosted on
407 LFS servers that don´t include the TTL.
408
412 The .lfsconfig file in a repository is read and interpreted in the same
413 format as the file stored in .git/config. It allows a subset of keys to
414 be used, including and limited to:
415 · lfs.allowincompletepush
417 · lfs.fetchexclude
419 · lfs.fetchinclude
421 · lfs.gitprotocol
423 · lfs.locksverify
425 · lfs.pushurl
427 · lfs.url
429 · lfs.extension.{name}.clean
431 · lfs.extension.{name}.smudge
433 · lfs.extension.{name}.priority
435 · remote.{name}.lfsurl
437 · lfs.{*}.access
439 The set of keys allowed in this file is restricted for security rea‐
443 sons.
444
446 Configure a custom LFS endpoint for your repository:
447 git config -f .lfsconfig lfs.url https://lfs.exam‐
450 ple.com/foo/bar/info/lfs
451
453 git-config(1), git-lfs-install(1), gitattributes(5)
454 Part of the git-lfs(1) suite.
456 July 2019 GIT-LFS-CONFIG(5)