src/main/resources/Documentation/config.md - plugins/lfs - Git at Google

 # Plugin @PLUGIN@ configuration

 ## Core Gerrit Settings

 The following options must be set in `$GERRIT_SITE/etc/gerrit.config`.

 ### Section `lfs`

 lfs.plugin = @PLUGIN@
 : With this option set LFS requests are forwarded to the @PLUGIN@ plugin.

 ## Per Project Settings

 The following options can be configured in `@PLUGIN@.config` on the
 `refs/meta/config` branch of the `All-Projects` project.

 ```
   [@PLUGIN@ "sandbox/*"]
     enabled = true
     maxObjectSize = 10m
   [@PLUGIN@ "public/*"]
     enabled = true
     maxObjectSize = 200m
   [@PLUGIN@ "customerX/*"]
     enabled = true
     maxObjectSize = 500m
   [@PLUGIN@ "customerY/*"]
     enabled = false
 ```

 A namespace can be specified as

 - exact project name (`plugins/myPlugin`): Defines LFS settings for one project.

 - pattern (`sandbox/*`): Defines LFS settings for one project namespace.

 - regular expression (`^test-.*/.*`): Defines LFS settings for the namespace
 matching the regular expression.

 - for-each-pattern (`?/*`): Defines the same LFS settings for each subfolder.
 `?` is a placeholder for any name and `?/*` with `maxObjectSize = 100m` means
 that for every subfolder the maximum object size is `100 mb`. Hence `?/*` is a
 shortcut for having n explicit namespaces.

 If a project name matches several @PLUGIN@ namespaces, the one the that is defined
 first in the @PLUGIN@.config will be applied.

 Example: Enable LFS for all projects, allowing unlimited object size for
 projects under `/test` and limiting to `500 mb` for projects under other
 folders:

 ```
   [@PLUGIN@ "test/*"]
     enabled = true
   [@PLUGIN@ "?/*"]
     enabled = true
     maxObjectSize = 500m
 ```

 Example: Only enable LFS for projects under `customer-A`:

 ```
   [@PLUGIN@ "customer-A/*]
     enabled = true
 ```


 ### Section `lfs`

 lfs.enabled
 : Whether to enable LFS for projects in this namespace. If not set, defaults
 to `false`.

 lfs.maxObjectSize
 : Maximum allowed object size (per object) in bytes for projects in this
 namespace, or 0 for no limit. If not set, defaults to 0. Common unit suffixes
 of `k`, `m`, and `g` are supported.

 lfs.readOnly
 : Whether to switch LFS for projects in this namespace into read-only mode.
 In this mode reading LFS objects is still possible but pushing is forbidden.
 Note that regular git operations are not affected.
 If not set, defaults to `false`.

 lfs.backend
 : Backend that should be used for storing binaries. It has to be one of
 backends specified as [fs](#lfs-fs-backend) or [s3](#lfs-s3-backend) subsection
 of Global Plugin Settings. If not set, defaults to value of `storage.backend`
 from Global Plugin Settings.

 ## Global Plugin Settings

 The following options can be configured in `$GERRIT_SITE/etc/@PLUGIN@.config`
 and `$GERRIT_SITE/etc/@PLUGIN@.secure.config.`

 ### Section `locks`

 The [Git LFS File Locking API](https://github.com/git-lfs/git-lfs/blob/master/docs/api/locking.md)
 specifies that a certain path can be locked by a user. It prevents the file
 being accidentally overwritten by a different user, and costly (manual in
 most cases) binary file merge. Each lock is represented by a JSON structure:

 ```
  {
     "id":"[lock id the same as lock file name]",
     "path":"[path to the resource being locked]",
     "locked_at":"[timestamp the lock was created in ISO 8601 format]",
     "owner":{
       "name":"[the name of the user that created the lock]"
     }
   }
 ```

 The lock is stored in a file whose name is the SHA256 hash of the path being
 locked, under `locks.directory` followed by the project name.

 locks.directory
 : The directory in which to store Git LFS file locks.

 : Default is `$GERRIT_SITE/data/@PLUGIN@/lfs_locks`.

 ### Section `auth`

 auth.sshExpirationSeconds
 : Validity, in seconds, of authentication token for SSH requests.
 [Git LFS Authentication](https://github.com/git-lfs/git-lfs/blob/master/docs/api/authentication.md)
 specifies that SSH might be used to authenticate the user. Successful authentication
 provides token that is later used for Git LFS requests.
 : Default is `10` seconds.

 ### Section `storage`

 storage.backend
 : The default storage backend to use. Valid values are `fs` for local file system,
 and `s3` for Amazon S3. If not set, defaults to `fs`.

 ### <a id="lfs-fs-backend"></a>Section `fs` - default file system backend

 The following configuration options are only used when the backend is `fs`.

 fs.directory
 : The directory in which to store data files. If not specified, defaults to
 the plugin's data folder: `$GERRIT_SITE/data/@PLUGIN@`.

 fs.expirationSeconds
 : Validity, in seconds, of authentication token for signed requests.
 Gerrit's LFS protocol handler signs requests to be issued by the git-lfs
 extension. This way the git-lfs extension doesn't need any credentials to
 access objects in the FS bucket. Validity of these request signatures expires
 after this period.
 : Default is `10` seconds.

 ### <a id="lfs-s3-backend"></a>Section `s3` - default S3 backend

 The following configuration options are only used when the backend is `s3`.

 s3.region
 : [Amazon region](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions)
 the S3 storage bucket is residing in.

 s3.bucket
 : Name of the [Amazon S3 storage bucket](http://docs.aws.amazon.com/AmazonS3/latest/UG/CreatingaBucket.html)
  which will store large objects.

 s3.storageClass
 : [Amazon S3 storage class](http://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html)
  used for storing large objects.
 : Default is `REDUCED_REDUNDANCY`

 s3.expirationSeconds
 : Expiration in seconds of validity of signed requests. Gerrit's LFS protocol
 handler signs requests to be issued by the git-lfs extension with the configured
 `accessKey` and `secretKey`. This way the git-lfs extension doesn't need
 any credentials to access objects in the S3 bucket. Validity of these request
 signatures expires after this period.
 : Default is `60` seconds.

 s3.disableSslVerify
 : `true`: SSL verification is disabled
 : `false`: SSL verification is enabled
 : Default is `false`.

 s3.accessKey
 : The [Amazon IAM accessKey](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)
 for authenticating to S3. It is recommended to place this
 setting in `$GERRIT_SITE/etc/@PLUGIN@.secure.config`.

 s3.secretKey
 : The [Amazon IAM secretKey](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)
  for authenticating to S3. It is recommended to place this
 setting in `$GERRIT_SITE/etc/@PLUGIN@.secure.config`.

 ### Multiple LFS backends

 One can specify multiple LFS backends for both FS and S3 storage by introducing
 backend subsections:

 ```
   [fs "foo"]
     directory = /foo_dir
   [s3 "bar"]
     ...
 ```

 and use them for namespace configuration by adding backend namespace parameter:

 ```
   [@PLUGIN@ "sandbox/*"]
     backend = foo
     ...
   [@PLUGIN@ "release/*"]
     backend = bar
     ...
 ```

 ## Local Project Configuration

 The following options must be set in the local project's `.git/config` file.

 ### Section `lfs`

 lfs.url
 : `http://<username>@<gerrit-host>:<port>/<project-name>/info/lfs`

 When the Gerrit repo is cloned via ssh, the git lfs url must be set to use http.
	# Plugin @PLUGIN@ configuration

	## Core Gerrit Settings

	The following options must be set in `$GERRIT_SITE/etc/gerrit.config`.

	### Section `lfs`

	lfs.plugin = @PLUGIN@
	: With this option set LFS requests are forwarded to the @PLUGIN@ plugin.

	## Per Project Settings

	The following options can be configured in `@PLUGIN@.config` on the
	`refs/meta/config` branch of the `All-Projects` project.

	```
	[@PLUGIN@ "sandbox/*"]
	enabled = true
	maxObjectSize = 10m
	[@PLUGIN@ "public/*"]
	enabled = true
	maxObjectSize = 200m
	[@PLUGIN@ "customerX/*"]
	enabled = true
	maxObjectSize = 500m
	[@PLUGIN@ "customerY/*"]
	enabled = false
	```

	A namespace can be specified as

	- exact project name (`plugins/myPlugin`): Defines LFS settings for one project.

	- pattern (`sandbox/*`): Defines LFS settings for one project namespace.

	- regular expression (`^test-./.`): Defines LFS settings for the namespace
	matching the regular expression.

	- for-each-pattern (`?/*`): Defines the same LFS settings for each subfolder.
	`?` is a placeholder for any name and `?/*` with `maxObjectSize = 100m` means
	that for every subfolder the maximum object size is `100 mb`. Hence `?/*` is a
	shortcut for having n explicit namespaces.

	If a project name matches several @PLUGIN@ namespaces, the one the that is defined
	first in the @PLUGIN@.config will be applied.

	Example: Enable LFS for all projects, allowing unlimited object size for
	projects under `/test` and limiting to `500 mb` for projects under other
	folders:

	```
	[@PLUGIN@ "test/*"]
	enabled = true
	[@PLUGIN@ "?/*"]
	enabled = true
	maxObjectSize = 500m
	```

	Example: Only enable LFS for projects under `customer-A`:

	```
	[@PLUGIN@ "customer-A/*]
	enabled = true
	```


	### Section `lfs`

	lfs.enabled
	: Whether to enable LFS for projects in this namespace. If not set, defaults
	to `false`.

	lfs.maxObjectSize
	: Maximum allowed object size (per object) in bytes for projects in this
	namespace, or 0 for no limit. If not set, defaults to 0. Common unit suffixes
	of `k`, `m`, and `g` are supported.

	lfs.readOnly
	: Whether to switch LFS for projects in this namespace into read-only mode.
	In this mode reading LFS objects is still possible but pushing is forbidden.
	Note that regular git operations are not affected.
	If not set, defaults to `false`.

	lfs.backend
	: Backend that should be used for storing binaries. It has to be one of
	backends specified as [fs](#lfs-fs-backend) or [s3](#lfs-s3-backend) subsection
	of Global Plugin Settings. If not set, defaults to value of `storage.backend`
	from Global Plugin Settings.

	## Global Plugin Settings

	The following options can be configured in `$GERRIT_SITE/etc/@PLUGIN@.config`
	and `$GERRIT_SITE/etc/@PLUGIN@.secure.config.`

	### Section `locks`

	The [Git LFS File Locking API](https://github.com/git-lfs/git-lfs/blob/master/docs/api/locking.md)
	specifies that a certain path can be locked by a user. It prevents the file
	being accidentally overwritten by a different user, and costly (manual in
	most cases) binary file merge. Each lock is represented by a JSON structure:

	```
	{
	"id":"[lock id the same as lock file name]",
	"path":"[path to the resource being locked]",
	"locked_at":"[timestamp the lock was created in ISO 8601 format]",
	"owner":{
	"name":"[the name of the user that created the lock]"
	}
	}
	```

	The lock is stored in a file whose name is the SHA256 hash of the path being
	locked, under `locks.directory` followed by the project name.

	locks.directory
	: The directory in which to store Git LFS file locks.

	: Default is `$GERRIT_SITE/data/@PLUGIN@/lfs_locks`.

	### Section `auth`

	auth.sshExpirationSeconds
	: Validity, in seconds, of authentication token for SSH requests.
	[Git LFS Authentication](https://github.com/git-lfs/git-lfs/blob/master/docs/api/authentication.md)
	specifies that SSH might be used to authenticate the user. Successful authentication
	provides token that is later used for Git LFS requests.
	: Default is `10` seconds.

	### Section `storage`

	storage.backend
	: The default storage backend to use. Valid values are `fs` for local file system,
	and `s3` for Amazon S3. If not set, defaults to `fs`.

	### <a id="lfs-fs-backend"></a>Section `fs` - default file system backend

	The following configuration options are only used when the backend is `fs`.

	fs.directory
	: The directory in which to store data files. If not specified, defaults to
	the plugin's data folder: `$GERRIT_SITE/data/@PLUGIN@`.

	fs.expirationSeconds
	: Validity, in seconds, of authentication token for signed requests.
	Gerrit's LFS protocol handler signs requests to be issued by the git-lfs
	extension. This way the git-lfs extension doesn't need any credentials to
	access objects in the FS bucket. Validity of these request signatures expires
	after this period.
	: Default is `10` seconds.

	### <a id="lfs-s3-backend"></a>Section `s3` - default S3 backend

	The following configuration options are only used when the backend is `s3`.

	s3.region
	: [Amazon region](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions)
	the S3 storage bucket is residing in.

	s3.bucket
	: Name of the [Amazon S3 storage bucket](http://docs.aws.amazon.com/AmazonS3/latest/UG/CreatingaBucket.html)
	which will store large objects.

	s3.storageClass
	: [Amazon S3 storage class](http://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html)
	used for storing large objects.
	: Default is `REDUCED_REDUNDANCY`

	s3.expirationSeconds
	: Expiration in seconds of validity of signed requests. Gerrit's LFS protocol
	handler signs requests to be issued by the git-lfs extension with the configured
	`accessKey` and `secretKey`. This way the git-lfs extension doesn't need
	any credentials to access objects in the S3 bucket. Validity of these request
	signatures expires after this period.
	: Default is `60` seconds.

	s3.disableSslVerify
	: `true`: SSL verification is disabled
	: `false`: SSL verification is enabled
	: Default is `false`.

	s3.accessKey
	: The [Amazon IAM accessKey](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)
	for authenticating to S3. It is recommended to place this
	setting in `$GERRIT_SITE/etc/@PLUGIN@.secure.config`.

	s3.secretKey
	: The [Amazon IAM secretKey](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)
	for authenticating to S3. It is recommended to place this
	setting in `$GERRIT_SITE/etc/@PLUGIN@.secure.config`.

	### Multiple LFS backends

	One can specify multiple LFS backends for both FS and S3 storage by introducing
	backend subsections:

	```
	[fs "foo"]
	directory = /foo_dir
	[s3 "bar"]
	...
	```

	and use them for namespace configuration by adding backend namespace parameter:

	```
	[@PLUGIN@ "sandbox/*"]
	backend = foo
	...
	[@PLUGIN@ "release/*"]
	backend = bar
	...
	```

	## Local Project Configuration

	The following options must be set in the local project's `.git/config` file.

	### Section `lfs`

	lfs.url
	: `http://<username>@<gerrit-host>:<port>/<project-name>/info/lfs`

	When the Gerrit repo is cloned via ssh, the git lfs url must be set to use http.