2015-09-01 10:43:32 +00:00
|
|
|
git-lfs-config(5) -- Configuration options for git-lfs
|
2015-08-17 11:05:44 +00:00
|
|
|
======================================================
|
|
|
|
|
|
|
|
## CONFIGURATION FILES
|
|
|
|
|
2017-03-09 10:26:18 +00:00
|
|
|
git-lfs reads its configuration from a file called `.lfsconfig` at the root of
|
|
|
|
the repository. The `.lfsconfig` file uses the same format as `.gitconfig`.
|
2015-08-17 11:05:44 +00:00
|
|
|
|
2017-03-09 10:26:18 +00:00
|
|
|
Additionally, all settings can be overridden by values returned by `git config -l`.
|
|
|
|
This allows you to override settings like `lfs.url` in your local environment
|
|
|
|
without having to modify the `.lfsconfig` file.
|
|
|
|
|
|
|
|
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.
|
2017-03-03 15:47:06 +00:00
|
|
|
|
|
|
|
|
2015-08-17 11:05:44 +00:00
|
|
|
## LIST OF OPTIONS
|
|
|
|
|
|
|
|
### General settings
|
|
|
|
|
2017-02-13 23:11:59 +00:00
|
|
|
* `lfs.url` / `remote.<remote>.lfsurl`
|
2015-09-02 16:48:13 +00:00
|
|
|
|
2015-08-17 11:05:44 +00:00
|
|
|
The url used to call the Git LFS remote API. Default blank (derive from clone
|
|
|
|
URL).
|
2015-09-02 16:48:13 +00:00
|
|
|
|
2017-02-13 23:11:59 +00:00
|
|
|
* `lfs.pushurl` / `remote.<remote>.lfspushurl`
|
2016-01-25 15:09:55 +00:00
|
|
|
|
|
|
|
The url used to call the Git LFS remote API when pushing. Default blank (derive
|
|
|
|
from either LFS non-push urls or clone url).
|
|
|
|
|
2016-02-04 17:01:25 +00:00
|
|
|
* `lfs.dialtimeout`
|
|
|
|
|
|
|
|
Sets the maximum time, in seconds, that the HTTP client will wait 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.keepalive`
|
|
|
|
|
|
|
|
Sets the maximum time, in seconds, for the HTTP client to maintain keepalive
|
|
|
|
connections. Default: 30 minutes.
|
|
|
|
|
2016-07-06 16:33:08 +00:00
|
|
|
### Transfer (upload / download) settings
|
|
|
|
|
|
|
|
These settings control how the upload and download of LFS content occurs.
|
|
|
|
|
|
|
|
* `lfs.concurrenttransfers`
|
|
|
|
|
|
|
|
The number of concurrent uploads/downloads. Default 3.
|
|
|
|
|
|
|
|
* `lfs.basictransfersonly`
|
|
|
|
|
2016-07-26 14:51:48 +00:00
|
|
|
If set to true, only basic HTTP upload/download transfers will be used,
|
2016-07-06 16:33:08 +00:00
|
|
|
ignoring any more advanced transfers that the client/server may support.
|
|
|
|
This is primarily to work around bugs or incompatibilities.
|
|
|
|
|
2016-07-26 14:51:48 +00:00
|
|
|
The git-lfs client supports basic HTTP downloads, resumable HTTP downloads
|
2016-07-06 16:33:08 +00:00
|
|
|
(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.
|
|
|
|
|
2016-07-26 14:51:48 +00:00
|
|
|
* `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,
|
2017-01-06 09:53:14 +00:00
|
|
|
and tus.io uploads will be available for all clients.
|
2016-07-26 14:51:48 +00:00
|
|
|
|
2016-07-06 16:33:08 +00:00
|
|
|
* `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
|
2016-07-07 15:43:56 +00:00
|
|
|
the custom transfer process is documented at
|
2016-11-15 17:07:11 +00:00
|
|
|
https://github.com/git-lfs/git-lfs/blob/master/docs/custom-transfers.md
|
2016-07-26 14:51:48 +00:00
|
|
|
|
2016-07-06 16:33:08 +00:00
|
|
|
<name> must be a unique identifier that the LFS server understands. 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 <name>
|
|
|
|
as a transfer it supports will this custom transfer process be invoked.
|
|
|
|
|
|
|
|
* `lfs.customtransfer.<name>.args`
|
|
|
|
|
|
|
|
If the custom transfer process requires any arguments, these can be provided
|
2016-07-26 14:51:48 +00:00
|
|
|
here.
|
2016-07-06 16:33:08 +00:00
|
|
|
|
|
|
|
* `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.
|
|
|
|
|
|
|
|
* `lfs.customtransfer.<name>.direction`
|
|
|
|
|
2016-07-26 14:51:48 +00:00
|
|
|
Specifies which direction the custom transfer process supports, either
|
2016-07-06 16:33:08 +00:00
|
|
|
"download", "upload", or "both". The default if unspecified is "both".
|
|
|
|
|
2016-10-10 20:22:24 +00:00
|
|
|
* `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
|
2017-02-18 20:22:49 +00:00
|
|
|
not an integer, is less than one, or is not given, a value of eight will be
|
|
|
|
used instead.
|
2016-10-10 20:22:24 +00:00
|
|
|
|
2017-02-22 17:56:25 +00:00
|
|
|
* `lfs.transfer.maxverifies`
|
|
|
|
|
|
|
|
Specifies how many verification requests LFS will attempt per OID before
|
|
|
|
marking the transfer as failed, if the object has a verification action
|
2017-02-22 18:39:31 +00:00
|
|
|
associated with it. Must be an integer which is at least one. If the value is
|
2017-02-22 17:56:25 +00:00
|
|
|
not an integer, is less than one, or is not given, a default value of three
|
|
|
|
will be used instead.
|
|
|
|
|
2015-08-17 11:05:44 +00:00
|
|
|
### Fetch settings
|
|
|
|
|
|
|
|
* `lfs.fetchinclude`
|
|
|
|
|
2015-09-02 16:48:13 +00:00
|
|
|
When fetching, only download objects which match any entry on this
|
|
|
|
comma-separated list of paths/filenames. Wildcard matching is as per
|
2015-08-18 09:00:40 +00:00
|
|
|
git-ignore(1). See git-lfs-fetch(1) for examples.
|
2015-08-17 11:05:44 +00:00
|
|
|
|
|
|
|
* `lfs.fetchexclude`
|
|
|
|
|
|
|
|
When fetching, do not download objects which match any item on this
|
2015-09-02 16:48:13 +00:00
|
|
|
comma-separated list of paths/filenames. Wildcard matching is as per
|
2015-08-18 09:00:40 +00:00
|
|
|
git-ignore(1). See git-lfs-fetch(1) for examples.
|
2015-08-17 11:05:44 +00:00
|
|
|
|
|
|
|
|
|
|
|
* `lfs.fetchrecentrefsdays`
|
2015-09-02 16:48:13 +00:00
|
|
|
|
|
|
|
If non-zero, fetches refs which have commits within N days of the current
|
2015-08-17 11:05:44 +00:00
|
|
|
date. Only local refs are included unless lfs.fetchrecentremoterefs is true.
|
2015-09-08 11:38:36 +00:00
|
|
|
Also used as a basis for pruning old files.
|
2015-08-17 11:05:44 +00:00
|
|
|
The default is 7 days.
|
|
|
|
|
|
|
|
* `lfs.fetchrecentremoterefs`
|
2015-09-02 16:48:13 +00:00
|
|
|
|
2015-09-01 11:06:30 +00:00
|
|
|
If true, fetches remote refs (for the remote you're fetching) as well as local
|
2015-09-02 16:48:13 +00:00
|
|
|
refs in the recent window. This is useful to fetch objects for remote branches
|
|
|
|
you might want to check out later. The default is true; if you set this to
|
|
|
|
false, fetching for those branches will only occur when you either check them
|
|
|
|
out (losing the advantage of fetch --recent), or create a tracking local
|
2015-09-01 11:06:30 +00:00
|
|
|
branch separately then fetch again.
|
2015-08-17 11:05:44 +00:00
|
|
|
|
|
|
|
* `lfs.fetchrecentcommitsdays`
|
2015-09-02 16:48:13 +00:00
|
|
|
|
|
|
|
In addition to fetching at refs, also fetches previous changes made within N
|
2015-08-17 11:05:44 +00:00
|
|
|
days of the latest commit on the ref. This is useful if you're often reviewing
|
2015-09-08 11:38:36 +00:00
|
|
|
recent changes. Also used as a basis for pruning old files.
|
|
|
|
The default is 0 (no previous changes).
|
2015-08-17 11:05:44 +00:00
|
|
|
|
|
|
|
* `lfs.fetchrecentalways`
|
2015-09-02 16:48:13 +00:00
|
|
|
|
2015-08-17 11:05:44 +00:00
|
|
|
Always operate as if --recent was included in a `git lfs fetch` call. Default
|
|
|
|
false.
|
|
|
|
|
2015-09-08 11:38:36 +00:00
|
|
|
### Prune settings
|
|
|
|
|
|
|
|
* `lfs.pruneoffsetdays`
|
|
|
|
|
|
|
|
The number of days added to the `lfs.fetchrecent*` settings to determine what
|
|
|
|
can be pruned. Default is 3 days, i.e. that anything fetched at the very
|
|
|
|
oldest edge of the 'recent window' is eligible for pruning 3 days later.
|
|
|
|
|
|
|
|
* `lfs.pruneremotetocheck`
|
|
|
|
|
|
|
|
Set the remote that LFS files must have been pushed to in order for them to
|
|
|
|
be considered eligible for local pruning. Also the remote which is called if
|
|
|
|
--verify-remote is enabled.
|
|
|
|
|
|
|
|
* `lfs.pruneverifyremotealways`
|
|
|
|
|
|
|
|
Always run `git lfs prune` as if `--verify-remote` was provided.
|
|
|
|
|
2015-08-17 11:05:44 +00:00
|
|
|
### Extensions
|
|
|
|
|
|
|
|
* `lfs.extension.<name>.<setting>`
|
|
|
|
|
2015-09-02 16:48:13 +00:00
|
|
|
Git LFS extensions enable the manipulation of files streams during smudge and
|
2015-08-17 11:05:44 +00:00
|
|
|
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`
|
2015-09-02 16:48:13 +00:00
|
|
|
|
2015-08-17 11:05:44 +00:00
|
|
|
Note: this setting is normally set by LFS itself on receiving a 401 response
|
2015-09-02 16:48:47 +00:00
|
|
|
(authentication required), you don't normally need to set it manually.
|
2015-08-17 11:05:44 +00:00
|
|
|
|
2015-09-02 16:48:47 +00:00
|
|
|
If set to "basic" then credentials will be requested before making batch
|
2015-09-02 16:48:13 +00:00
|
|
|
requests to this url, otherwise a public request will initially be attempted.
|
2015-08-17 11:05:44 +00:00
|
|
|
|
2017-02-15 20:38:47 +00:00
|
|
|
* `lfs.<url>.locksverify`
|
2017-02-13 23:11:59 +00:00
|
|
|
|
|
|
|
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 based 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 will set 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 will set 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.
|
2017-02-15 20:38:47 +00:00
|
|
|
You should set this if you're not using File Locking, or your Git server
|
|
|
|
verifies locked files on pushes automatically.
|
2017-02-13 23:11:59 +00:00
|
|
|
|
2016-05-10 10:38:45 +00:00
|
|
|
* `lfs.skipdownloaderrors`
|
|
|
|
|
|
|
|
Causes Git LFS not to abort the smudge filter when a download error is
|
|
|
|
encountered, which allows actions such as checkout to work when you are unable
|
|
|
|
to download the LFS content. LFS files which could not download will contain
|
|
|
|
pointer content instead.
|
|
|
|
|
|
|
|
Note that this will result in git commands which call the smudge filter to
|
|
|
|
report success even in cases when LFS downloads fail, which may affect
|
|
|
|
scripts.
|
|
|
|
|
2016-07-26 14:51:48 +00:00
|
|
|
You can also set the environment variable GIT_LFS_SKIP_DOWNLOAD_ERRORS=1 to
|
|
|
|
get the same effect.
|
|
|
|
|
2016-08-19 15:49:03 +00:00
|
|
|
* `GIT_LFS_PROGRESS`
|
|
|
|
|
2016-08-19 16:00:32 +00:00
|
|
|
This environment variable causes Git LFS to emit progress updates to an
|
|
|
|
absolute file-path on disk when cleaning, smudging, or fetching.
|
2016-08-19 15:49:03 +00:00
|
|
|
|
|
|
|
Progress is reported periodically in the form of a new line being appended to
|
|
|
|
the end of the file. Each new line will take 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.
|
|
|
|
|
2016-12-19 17:41:16 +00:00
|
|
|
* `GIT_LFS_SET_LOCKABLE_READONLY`
|
2017-01-06 09:53:14 +00:00
|
|
|
`lfs.setlockablereadonly`
|
2016-12-19 17:41:16 +00:00
|
|
|
|
2017-01-06 09:53:14 +00:00
|
|
|
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'.
|
2016-12-19 17:41:16 +00:00
|
|
|
|
2017-03-09 10:33:58 +00:00
|
|
|
## EXAMPLES
|
|
|
|
|
|
|
|
* Configure a custom LFS endpoint for your repository:
|
|
|
|
|
|
|
|
`git config -f .lfsconfig lfs.url https://lfs.example.com/foo/bar/info/lfs`
|
|
|
|
|
2015-08-17 11:05:44 +00:00
|
|
|
## SEE ALSO
|
|
|
|
|
2016-07-07 15:43:56 +00:00
|
|
|
git-config(1), git-lfs-install(1), gitattributes(5)
|
2015-08-17 11:05:44 +00:00
|
|
|
|
|
|
|
Part of the git-lfs(1) suite.
|