docs/man/git-lfs-config.5.ronn

   1 git-lfs-config(5) -- Configuration options for git-lfs
   2 ======================================================
   3
   4 ## CONFIGURATION FILES
   5
   6 git-lfs reads its configuration from a file called `.lfsconfig` at the root of
   7 the repository. The `.lfsconfig` file uses the same format as `.gitconfig`.
   8
   9 Additionally, all settings can be overridden by values returned by `git config -l`.
  10 This allows you to override settings like `lfs.url` in your local environment
  11 without having to modify the `.lfsconfig` file.
  12
  13 Most options regarding git-lfs are contained in the `[lfs]` section, meaning
  14 they are all named `lfs.foo` or similar, although occasionally an lfs option can
  15 be scoped inside the configuration for a remote.
  16
  17
  18 ## LIST OF OPTIONS
  19
  20 ### General settings
  21
  22 * `lfs.url` / `remote.<remote>.lfsurl`
  23
  24   The url used to call the Git LFS remote API. Default blank (derive from clone
  25   URL).
  26
  27 * `lfs.pushurl` / `remote.<remote>.lfspushurl`
  28
  29   The url used to call the Git LFS remote API when pushing. Default blank (derive
  30   from either LFS non-push urls or clone url).
  31
  32 * `lfs.dialtimeout`
  33
  34   Sets the maximum time, in seconds, that the HTTP client will wait to initiate
  35   a connection. This does not include the time to send a request and wait for a
  36   response. Default: 30 seconds
  37
  38 * `lfs.tlstimeout`
  39
  40   Sets the maximum time, in seconds, that the HTTP client will wait for a TLS
  41   handshake. Default: 30 seconds.
  42
  43 * `lfs.activitytimeout` / `lfs.https://<host>.activitytimeout`
  44
  45   Sets the maximum time, in seconds, that the HTTP client will wait for the
  46   next tcp read or write. If < 1, no activity timeout is used at all.
  47   Default: 30 seconds
  48
  49 * `lfs.keepalive`
  50
  51   Sets the maximum time, in seconds, for the HTTP client to maintain keepalive
  52   connections. Default: 30 minutes.
  53
  54 * `lfs.ssh.retries`
  55
  56   Specifies the number of times Git LFS will attempt to obtain authorization via
  57   SSH before aborting. Default: 5.
  58
  59 * `core.askpass`, GIT_ASKPASS
  60
  61   Given as a program and its arguments, this is invoked when authentication is
  62   needed against the LFS API. The contents of stdout are interpreted as the
  63   password.
  64
  65 * `lfs.cachecredentials`
  66
  67   Enables in-memory SSH and Git Credential caching for a single 'git lfs'
  68   command. Default: enabled.
  69
  70 * `lfs.storage`
  71
  72   Allow override LFS storage directory. Non-absolute path is relativized to
  73   inside of Git repository directory (usually `.git`).
  74
  75   Note: you should not run `git lfs prune` if you have different repositories
  76   sharing the same storage directory.
  77
  78   Default: `lfs` in Git repository directory (usually `.git/lfs`).
  79
  80 ### Transfer (upload / download) settings
  81
  82   These settings control how the upload and download of LFS content occurs.
  83
  84 * `lfs.concurrenttransfers`
  85
  86   The number of concurrent uploads/downloads. Default 8.
  87
  88 * `lfs.basictransfersonly`
  89
  90   If set to true, only basic HTTP upload/download transfers will be used,
  91   ignoring any more advanced transfers that the client/server may support.
  92   This is primarily to work around bugs or incompatibilities.
  93
  94   The git-lfs client supports basic HTTP downloads, resumable HTTP downloads
  95   (using `Range` headers), and resumable uploads via tus.io protocol. Custom
  96   transfer methods can be added via `lfs.customtransfer` (see next section).
  97   However setting this value to true limits the client to simple HTTP.
  98
  99 * `lfs.tustransfers`
 100
 101   If set to true, this enables resumable uploads of LFS objects through the
 102   tus.io API. Once this feature is finalized, this setting will be removed,
 103   and tus.io uploads will be available for all clients.
 104
 105 * `lfs.standalonetransferagent`
 106
 107   Allows the specified custom transfer agent to be used directly
 108   for transferring files, without asking the server how the transfers
 109   should be made. The custom transfer agent has to be defined in a
 110   `lfs.customtransfer.<name>` settings group.
 111
 112 * `lfs.customtransfer.<name>.path`
 113
 114   `lfs.customtransfer.<name>` is a settings group which defines a custom
 115   transfer hook which allows you to upload/download via an intermediate process,
 116   using any mechanism you like (rather than just HTTP). `path` should point to
 117   the process you wish to invoke. The protocol between the git-lfs client and
 118   the custom transfer process is documented at
 119   https://github.com/git-lfs/git-lfs/blob/master/docs/custom-transfers.md
 120
 121   <name> must be a unique identifier that the LFS server understands. When
 122   calling the LFS API the client will include a list of supported transfer
 123   types. If the server also supports this named transfer type, it will select it
 124   and actions returned from the API will be in relation to that transfer type
 125   (may not be traditional URLs for example). Only if the server accepts <name>
 126   as a transfer it supports will this custom transfer process be invoked.
 127
 128 * `lfs.customtransfer.<name>.args`
 129
 130   If the custom transfer process requires any arguments, these can be provided
 131   here.
 132
 133 * `lfs.customtransfer.<name>.concurrent`
 134
 135   If true (the default), git-lfs will invoke the custom transfer process
 136   multiple times in parallel, according to `lfs.concurrenttransfers`, splitting
 137   the transfer workload between the processes.
 138
 139 * `lfs.customtransfer.<name>.direction`
 140
 141   Specifies which direction the custom transfer process supports, either
 142   "download", "upload", or "both". The default if unspecified is "both".
 143
 144 * `lfs.transfer.maxretries`
 145
 146   Specifies how many retries LFS will attempt per OID before marking the
 147   transfer as failed. Must be an integer which is at least one. If the value is
 148   not an integer, is less than one, or is not given, a value of eight will be
 149   used instead.
 150
 151 * `lfs.transfer.maxverifies`
 152
 153   Specifies how many verification requests LFS will attempt per OID before
 154   marking the transfer as failed, if the object has a verification action
 155   associated with it. Must be an integer which is at least one. If the value is
 156   not an integer, is less than one, or is not given, a default value of three
 157   will be used instead.
 158
 159 ### Push settings
 160
 161 * `lfs.allowincompletepush`
 162
 163   When pushing, allow objects to be missing from the local cache without halting
 164   a Git push. Default: false.
 165
 166 ### Fetch settings
 167
 168 * `lfs.fetchinclude`
 169
 170   When fetching, only download objects which match any entry on this
 171   comma-separated list of paths/filenames. Wildcard matching is as per
 172   git-ignore(1). See git-lfs-fetch(1) for examples.
 173
 174 * `lfs.fetchexclude`
 175
 176   When fetching, do not download objects which match any item on this
 177   comma-separated list of paths/filenames. Wildcard matching is as per
 178   git-ignore(1). See git-lfs-fetch(1) for examples.
 179
 180 * `lfs.fetchrecentrefsdays`
 181
 182   If non-zero, fetches refs which have commits within N days of the current
 183   date. Only local refs are included unless lfs.fetchrecentremoterefs is true.
 184   Also used as a basis for pruning old files.
 185   The default is 7 days.
 186
 187 * `lfs.fetchrecentremoterefs`
 188
 189   If true, fetches remote refs (for the remote you're fetching) as well as local
 190   refs in the recent window. This is useful to fetch objects for remote branches
 191   you might want to check out later. The default is true; if you set this to
 192   false, fetching for those branches will only occur when you either check them
 193   out (losing the advantage of fetch --recent), or create a tracking local
 194   branch separately then fetch again.
 195
 196 * `lfs.fetchrecentcommitsdays`
 197
 198   In addition to fetching at refs, also fetches previous changes made within N
 199   days of the latest commit on the ref. This is useful if you're often reviewing
 200   recent changes.   Also used as a basis for pruning old files.
 201   The default is 0 (no previous changes).
 202
 203 * `lfs.fetchrecentalways`
 204
 205   Always operate as if --recent was included in a `git lfs fetch` call. Default
 206   false.
 207
 208 ### Prune settings
 209
 210 * `lfs.pruneoffsetdays`
 211
 212   The number of days added to the `lfs.fetchrecent*` settings to determine what
 213   can be pruned. Default is 3 days, i.e. that anything fetched at the very
 214   oldest edge of the 'recent window' is eligible for pruning 3 days later.
 215
 216 * `lfs.pruneremotetocheck`
 217
 218   Set the remote that LFS files must have been pushed to in order for them to
 219   be considered eligible for local pruning. Also the remote which is called if
 220   --verify-remote is enabled.
 221
 222 * `lfs.pruneverifyremotealways`
 223
 224   Always run `git lfs prune` as if `--verify-remote` was provided.
 225
 226 ### Extensions
 227
 228 * `lfs.extension.<name>.<setting>`
 229
 230   Git LFS extensions enable the manipulation of files streams during smudge and
 231   clean. `name` groups the settings for a single extension, and the settings
 232   are:
 233   * `clean` The command which runs when files are added to the index
 234   * `smudge` The command which runs when files are written to the working copy
 235   * `priority` The order of this extension compared to others
 236
 237 ### Other settings
 238
 239 * `lfs.<url>.access`
 240
 241   Note: this setting is normally set by LFS itself on receiving a 401 response
 242   (authentication required), you don't normally need to set it manually.
 243
 244   If set to "basic" then credentials will be requested before making batch
 245   requests to this url, otherwise a public request will initially be attempted.
 246
 247 * `lfs.<url>.locksverify`
 248
 249   Determines whether locks are checked before Git pushes. This prevents you from
 250   pushing changes to files that other users have locked. The Git LFS pre-push
 251   hook varies its behavior based on the value of this config key.
 252
 253   * `null` - In the absence of a value, Git LFS will attempt the call, and warn
 254   if it returns an error. If the response is valid, Git LFS will set the value
 255   to `true`, and will halt the push if the user attempts to update a file locked
 256   by another user. If the server returns a `501 Not Implemented` response, Git
 257   LFS will set the value to `false.`
 258   * `true` - Git LFS will attempt to verify locks, halting the Git push if there
 259   are any server issues, or if the user attempts to update a file locked by
 260   another user.
 261   * `false` - Git LFS will completely skip the lock check in the pre-push hook.
 262   You should set this if you're not using File Locking, or your Git server
 263   verifies locked files on pushes automatically.
 264
 265   Supports URL config lookup as described in:
 266   https://git-scm.com/docs/git-config#git-config-httplturlgt. To set this value
 267   per-host: `git config --global lfs.https://github.com/.locksverify [true|false]`.
 268
 269 * `lfs.<url>.contenttype`
 270
 271   Determines whether Git LFS should attempt to detect an appropriate HTTP
 272   `Content-Type` header when uploading using the 'basic' upload adapter. If set
 273   to false, the default header of `Content-Type: application/octet-stream` is
 274   chosen instead. Default: 'true'.
 275
 276 * `lfs.skipdownloaderrors`
 277
 278   Causes Git LFS not to abort the smudge filter when a download error is
 279   encountered, which allows actions such as checkout to work when you are unable
 280   to download the LFS content. LFS files which could not download will contain
 281   pointer content instead.
 282
 283   Note that this will result in git commands which call the smudge filter to
 284   report success even in cases when LFS downloads fail, which may affect
 285   scripts.
 286
 287   You can also set the environment variable GIT_LFS_SKIP_DOWNLOAD_ERRORS=1 to
 288   get the same effect.
 289
 290 * `GIT_LFS_PROGRESS`
 291
 292   This environment variable causes Git LFS to emit progress updates to an
 293   absolute file-path on disk when cleaning, smudging, or fetching.
 294
 295   Progress is reported periodically in the form of a new line being appended to
 296   the end of the file. Each new line will take the following format:
 297
 298   `<direction> <current>/<total files> <downloaded>/<total> <name>`
 299
 300   Each field is described below:
 301   * `direction`: The direction of transfer, either "checkout", "download", or
 302     "upload".
 303   * `current` The index of the currently transferring file.
 304   * `total files` The estimated count of all files to be transferred.
 305   * `downloaded` The number of bytes already downloaded.
 306   * `total` The entire size of the file, in bytes.
 307   * `name` The name of the file.
 308
 309 * `GIT_LFS_SET_LOCKABLE_READONLY`
 310   `lfs.setlockablereadonly`
 311
 312   These settings, the first an environment variable and the second a gitconfig
 313   setting, control whether files marked as 'lockable' in `git lfs track` are
 314   made read-only in the working copy when not locked by the current user.
 315   The default is `true`; you can disable this behaviour and have all files
 316   writeable by setting either variable to 0, 'no' or 'false'.
 317
 318 * `lfs.defaulttokenttl`
 319
 320   This setting sets a default token TTL when git-lfs-authenticate does not
 321   include the TTL in the JSON response but still enforces it.
 322
 323   Note that this is only necessary for larger repositories hosted on LFS
 324   servers that don't include the TTL.
 325
 326 ## LFSCONFIG
 327
 328 The .lfsconfig file in a repository is read and interpreted in the same format
 329 as the file stored in .git/config. It allows a subset of keys to be used,
 330 including and limited to:
 331
 332 - lfs.fetchexclude
 333 - lfs.fetchinclude
 334 - lfs.gitprotocol
 335 - lfs.pushurl
 336 - lfs.url
 337 - lfs.extension.{name}.clean
 338 - lfs.extension.{name}.smudge
 339 - lfs.extension.{name}.priority
 340 - remote.{name}.lfsurl
 341 - remote.{name}.{*}.access
 342
 343 ## EXAMPLES
 344
 345 *  Configure a custom LFS endpoint for your repository:
 346
 347   `git config -f .lfsconfig lfs.url https://lfs.example.com/foo/bar/info/lfs`
 348
 349 ## SEE ALSO
 350
 351 git-config(1), git-lfs-install(1), gitattributes(5)
 352
 353 Part of the git-lfs(1) suite.