resources/Documentation/backend-find-owners-cookbook.md - plugins/code-owners - Git at Google

 # find-owners: Cookbook for OWNERS files

 For the [find-owners](backend-find-owners.html) backend code owners are defined
 in `OWNERS` files. This cookbook provides examples of `OWNERS` files for various
 use cases.

 **NOTE:** The syntax of `OWNERS` files is described
 [here](backend-find-owners.html#syntax).

 **NOTE:** By default the `find-owners` backend uses
 [FIND_OWNERS_GLOB's](path-expressions.html) as path expressions, but it's
 possible that a different path expression syntax is
 [configured](config.html#pluginCodeOwnersPathExpressions). All examples on this
 page assume that `FIND_OWNERS_GLOB`'s are used as path expressions.

 ### <a id="defineUsersAsCodeOwners">Define users as code owners

 To define a set of users as code owners, each user email must be placed in a
 separate line:

 ```
   jane.roe@example.com
   john.doe@example.com
   richard.roe@example.com
 ```
 \
 The order of the user emails is not important and doesn't have any effect, but
 for consistency an alphabetical order is recommended.

 The listed users own all files that are contained in the directory that contains
 this `OWNERS` file, except:

 * files in subdirectories that have an `OWNERS` file that disables inheriting
   code owners from parent directories via the
   [set noparent](backend-find-owners.html#setNoparent) file-level rule
   ([example](#ignoreParentCodeOwners))
 * files that are matched by a path expression in a
   [per-file](backend-find-owners.html#perFile) line that uses
   [set noparent](backend-find-owners.html#setNoparent) (in this `OWNERS` file or
   in any `OWNERS` file in a subdirectory, [example](#perFileWithSetNoparent))

 In addition to the specified owners the files are also owned by the code owners
 that are inherited from the parent directories. To prevent this the
 [set noparent](backend-find-owners.html#setNoparent) file-level rule can be used
 (see [next example](#ignoreParentCodeOwners)).

 ### <a id="ignoreParentCodeOwners">Ignore parent code owners

 To ignore code owners that are defined in the `OWNERS` files of the parent
 directories the [set noparent](backend-find-owners.html#setNoparent) file-level
 rule can be used:

 ```
   set noparent
   jane.roe@example.com
   john.doe@example.com
   richard.roe@example.com
 ```
 \
 For example, if code owners for the file '/foo/bar/baz.txt' are computed the
 `OWNERS` files are evaluated in this order:

 1. `/foo/bar/OWNERS`
 2. `/foo/OWNERS`
 3. `/OWNERS`
 4. `/OWNERS` in `refs/meta/config`
    (contains [default code owners](backend-find-owners.html#defaultCodeOwnerConfiguration))

 If any `set noparent` file-level rule is seen the evaluation is stopped and
 further `OWNERS` files are ignored. E.g. if `/foo/OWNERS` contains
 `set noparent` the `OWNERS` files mentioned at 3. and 4. are ignored.

 **NOTE:** When the [set noparent](backend-find-owners.html#setNoparent)
 file-level rule is used you should always define code owners which should be
 used instead of the code owners from the parent directories. Otherwise the files
 in the directory stay [without code owners](#noCodeOwners) and nobody can grant
 code owner approval on them. To [exempt a directory from requiring code owner
 approvals](#exemptFiles), assign the code ownership to [all
 users](backend-find-owners.html#allUsers) instead ([example](#exemptFiles)).

 **NOTE:** The usage of `set noparent` has no effect on `OWNERS` files in
 subfolders.

 ### <a id="defineCodeOwnersForAFile">Define code owners for a certain file

 By using the [per-file](backend-find-owners.html#perFile) restriction prefix it
 is possible to define code owners for a certain file (in the current directory
 and all its subdirectories), e.g. for the `BUILD` file:

 ```
   per-file BUILD=tina.toe@example.com
 ```
 \
 Multiple code owners for the same file can be specified as comma-separated list:

 ```
   per-file BUILD=tina.toe@example.com,martha.moe@example.com
 ```
 \
 Alternatively it's also possible to repeat the per-file line multiple times:

 ```
   per-file BUILD=tina.toe@example.com
   per-file BUILD=martha.moe@example.com
 ```
 \
 If a file is matched by the path expressions of multiple
 [per-file](backend-find-owners.html#perFile) lines, the file is owned by all
 users that are mentioned in these [per-file](backend-find-owners.html#perFile)
 lines.

 If folder code owners are present, the file is also owned by any folder code
 owners:

 ```
   jane.roe@example.com
   john.doe@example.com
   richard.roe@example.com
   per-file BUILD=tina.toe@example.com,martha.moe@example.com
 ```
 \
 In addition, the file is also owned by code owners that are inherited from
 parent directories.

 #### <a id="perFileWithSetNoparent">
 Ignoring folder code owners and inherited parent code owners for a file is
 possible by using a matching [per-file](backend-find-owners.html#perFile) line
 with [set noparent](backend-find-owners.html#setNoparent).

 ```
   jane.roe@example.com
   john.doe@example.com
   richard.roe@example.com
   per-file BUILD=set noparent
   per-file BUILD=tina.toe@example.com,martha.moe@example.com
 ```
 \
 For example, if code owners for the file '/foo/bar/baz.txt' are computed the
 code owners in the `OWNERS` files are evaluated in this order:

 1. matching per-file code owners in `/foo/bar/OWNERS`
 2. folder code owners in `/foo/bar/OWNERS`
 3. matching per-file code owners in `/foo/OWNERS`
 4. folder code owners in `/foo/OWNERS`
 5. matching per-file code owners in `/OWNERS`
 6. folder code owners in `/OWNERS`
 7. matching per-file code owners in `/OWNERS` in `refs/meta/config`
    (contains [default code owners](backend-find-owners.html#defaultCodeOwnerConfiguration))
 8. folder code owners in `/OWNERS` in `refs/meta/config`
    (contains [default code owners](backend-find-owners.html#defaultCodeOwnerConfiguration))

 If any `set noparent` file-level rule is seen the evaluation is stopped and
 code owners on further levels are ignored. E.g. if `/foo/OWNERS` contains a
 matching per-file rule with `set noparent` the code owners mentioned at 4. to 8.
 are ignored.

 **NOTE:** When the [set noparent](backend-find-owners.html#setNoparent) rule is
 used on a per-file rule you should always define code owners which should be
 used instead of the folder code owners and the code owners from the parent
 directories.  Otherwise the matched files stay [without code
 owners](#noCodeOwners) and nobody can grant code owner approval on them. To
 [exempt matched files from requiring code owner approvals](#exemptFiles), assign
 the code ownership to [all users](backend-find-owners.html#allUsers) instead
 ([example](#exemptFiles)).

 **NOTE:** The syntax for path expressions / globs is explained
 [here](path-expressions.html#globs).

 ### <a id="defineCodeOwnersForAFileType">Define code owners for a certain file type

 This is the same as [defining code owners for a file](#defineCodeOwnersForAFile)
 only that the [per-file](backend-find-owners.html#perFile) line must have a path
 expression that matches all files of the wanted type, e.g. all '*.md' files:

 ```
   per-file *.md=tina.toe@example.com
 ```
 \
 This matches all '*.md' in the current directory and all its subdirectories.

 **NOTE**: Using '*.md' is the same as using '**.md' (both expressions match
 files in the current directory and in all subdirectories).

 **NOTE:** The syntax for path expressions / globs is explained
 [here](path-expressions.html#globs).

 ### <a id="defineCodeOwnersForAllFileInASubdirectory">Define code owners for all files in a subdirectory

 It is discouraged to use path expressions that explicitly name subdirectories
 such as `my-subdir/*` as they will break when the subdirectory gets
 renamed/moved. Instead prefer to define these code owners in `my-subdir/OWNERS`
 so that the code owners for the subdirectory stay intact when the subdirectory
 gets renamed/moved.

 Nontheless, it's possible to define code owners for all files in a subdirectory
 using a [per-file](backend-find-owners.html#perFile) line. This is the same as
 [defining code owners for a file](#defineCodeOwnersForAFile) only that the path
 expression matches all files in the subdirectory:

 ```
   per-file my-subdir/*=tina.toe@example.com
 ```

 ### <a id="defineAGroupAsCodeOwner">Define a group as code owner

 Groups are not supported in `OWNERS` files and assigning code ownership to them
 is not possible.

 Instead of using a group you may define a set of users in an `OWNERS` file with
 a prefix (`<prefix>_OWNERS`) or an extension (`OWNERS_<extension>`) and then
 [import](#importOtherOwnersFile) it into other `OWNERS` files via the
 [file](backend-find-owners.html#fileKeyword) keyword.

 `/OWNERS_BUILD`:
 ```
   jane.roe@example.com
   john.doe@example.com
   richard.roe@example.com
   per-file BUILD=tina.toe@example.com
 ```
 \
 other `OWNERS` file:
 ```
   per-file BUILD=file:/OWNERS_BUILD
 ```
 \
 This is equivalent to having:

 ```
   per-file BUILD=jane.roe@example.com,john.doe@example.com,richard.roe@example.com
 ```
 \
 **NOTE:** The `per-file` line from `/OWNERS_BUILD` is not imported, since the
 [file](backend-find-owners.html#fileKeyword) keyword only imports folder code
 owners. Using the [include](backend-find-owners.html#includeKeyword) keyword,
 that would also consider per-file code owners, is not supported for `per-file`
 lines.

 ### <a id="importOtherOwnersFile">Import code owners from other OWNERS file

 To import code owners from another `OWNERS` file the
 [file](backend-find-owners.html#fileKeyword) or
 [include](backend-find-owners.html#includeKeyword) keyword can be used:

 `java/com/example/foo/OWNERS`:
 ```
   jane.roe@example.com
   john.doe@example.com
   richard.roe@example.com
   per-file BUILD=tina.toe@example.com
 ```
 \
 `javatests/com/example/foo/OWNERS`:
 ```
   file:/java/com/example/foo/OWNERS
 ```
 \
 This is equivalent to having:

 ```
   jane.roe@example.com
   john.doe@example.com
   richard.roe@example.com
 ```
 \
 **NOTE:** The `per-file` line from `java/com/example/foo/OWNERS` is not
 imported, since the [file](backend-find-owners.html#fileKeyword) keyword only
 imports folder code owners. If also `per-line` lines should be imported the
 [include](backend-find-owners.html#includeKeyword) keyword can be used instead:

 `javatests/com/example/foo/OWNERS`:
 ```
   include /java/com/example/foo/OWNERS
 ```
 \
 This is equivalent to having:

 ```
   jane.roe@example.com
   john.doe@example.com
   richard.roe@example.com
   per-file BUILD=tina.toe@example.com
 ```

 ### <a id="importFromOtherRepository">Import code owners from other repository

 To import code owners from an `OWNERS` file in another repository the
 [file](backend-find-owners.html#fileKeyword) or
 [include](backend-find-owners.html#includeKeyword) keyword can be used:

 `/OWNERS` in the `master` branch of respository `my-project`:
 ```
   jane.roe@example.com
   john.doe@example.com
   richard.roe@example.com
 ```
 \
 `/OWNERS` in the `master` branch of respository `my-project/plugin-foo`:
 ```
   file:my-project:/OWNERS
 ```
 \
 This way `my-project/plugin-foo` always has the same code owners as
 `my-project`.

 **NOTE:** If a branch is not specified, the `OWNERS` file will always be
 imported from the same branch, in which the importing `OWNERS` file is stored.
 If `file:my-project:/OWNERS` is contained in an `OWNERS` file in the `master`
 branch, `my-project:master:/OWNERS` is imported. If `file:my-project:/OWNERS` is
 contained in an `OWNERS` file in the `stable-3.5` branch,
 `my-project:stable-3.5:/OWNERS` is imported.

 ### <a id="importFromOtherBranch">Import code owners from other branch

 To import code owners from an `OWNERS` file in another branch the
 [file](backend-find-owners.html#fileKeyword) or
 [include](backend-find-owners.html#includeKeyword) keyword can be used:

 `/OWNERS` in the `master` branch of respository `my-project`:
 ```
   jane.roe@example.com
   john.doe@example.com
   richard.roe@example.com
 ```
 \
 `/OWNERS` in the `stable-3.5` branch of respository `my-project`:
 ```
   file:my-project:master:/OWNERS
 ```
 \
 This way the `stable-3.5` branch of `my-project` always has the same global code
 owners as the `master` branch of `my-project`.

 **NOTE:** To import code owners from another branch it is mandatory to specify
 the repository, even if it is the same repository that contains the importing
 `OWNERS` file.

 ### <a id="exemptFiles">Exempt files from requiring code owner approval

 To exempt files from requiring code owner approval the code ownership can be
 assigned to [all users](backend-find-owners.html#allUsers) by using '*' as
 [user email](backend-find-owners.html#userEmails). Assigning the code ownership
 to all users effectively exempts the directory (or the matches files if used in
 combination with a [per-file](backend-find-owners.html#perFile) rule) from
 requiring code owner approvals on submit. This is because a code owner approval
 from the uploader is always implicit if the uploader is a code owner.

 `OWNERS` file that exempts the whole directory from requiring code owner
 approvals:
 ```
   *
 ```
 \
 `OWNERS` files that exempts all '*.md' files (in the current directory and all
 subdirectories) from requiring code owner approvals:
 ```
   per-file *.md=*
 ```
 \
 **NOTE:** Files that are not owned by anyone are **not** excluded from requiring
 code ower approvals, see [next section](#noCodeOwners).

 ### <a id="noCodeOwners">Avoid that files are not owned by anyone

 Files that are not owned by anyone cannot be approved since there is no code
 owner that can grant the approval. Hence submitting modifications to them is
 only possible with an override approval.

 Due to this it is recommended to avoid code owner configurations that leave
 files without code owners, e.g. the following configurations should be avoided:

 * an `OWNERS` file with only `set noparent` (ignores code owners from parent
   directories, but doesn't define code owners that should be used instead)
 * a `per-file` line with only `set noparent` (ignores folder code owners and
   code owners from parent directories, but doesn't define code owners that
   should be used instead)
 * no `OWNERS` file at root level

 **NOTE:** How to exempt files from requiring code owner approval is described
 [here](#exemptFiles).

 ---

 Back to [@PLUGIN@ documentation index](index.html)

 Part of [Gerrit Code Review](../../../Documentation/index.html)
	# find-owners: Cookbook for OWNERS files

	For the [find-owners](backend-find-owners.html) backend code owners are defined
	in `OWNERS` files. This cookbook provides examples of `OWNERS` files for various
	use cases.

	NOTE: The syntax of `OWNERS` files is described
	[here](backend-find-owners.html#syntax).

	NOTE: By default the `find-owners` backend uses
	[FIND_OWNERS_GLOB's](path-expressions.html) as path expressions, but it's
	possible that a different path expression syntax is
	[configured](config.html#pluginCodeOwnersPathExpressions). All examples on this
	page assume that `FIND_OWNERS_GLOB`'s are used as path expressions.

	### <a id="defineUsersAsCodeOwners">Define users as code owners

	To define a set of users as code owners, each user email must be placed in a
	separate line:

	```
	jane.roe@example.com
	john.doe@example.com
	richard.roe@example.com
	```
	\
	The order of the user emails is not important and doesn't have any effect, but
	for consistency an alphabetical order is recommended.

	The listed users own all files that are contained in the directory that contains
	this `OWNERS` file, except:

	* files in subdirectories that have an `OWNERS` file that disables inheriting
	code owners from parent directories via the
	[set noparent](backend-find-owners.html#setNoparent) file-level rule
	([example](#ignoreParentCodeOwners))
	* files that are matched by a path expression in a
	[per-file](backend-find-owners.html#perFile) line that uses
	[set noparent](backend-find-owners.html#setNoparent) (in this `OWNERS` file or
	in any `OWNERS` file in a subdirectory, [example](#perFileWithSetNoparent))

	In addition to the specified owners the files are also owned by the code owners
	that are inherited from the parent directories. To prevent this the
	[set noparent](backend-find-owners.html#setNoparent) file-level rule can be used
	(see [next example](#ignoreParentCodeOwners)).

	### <a id="ignoreParentCodeOwners">Ignore parent code owners

	To ignore code owners that are defined in the `OWNERS` files of the parent
	directories the [set noparent](backend-find-owners.html#setNoparent) file-level
	rule can be used:

	```
	set noparent
	jane.roe@example.com
	john.doe@example.com
	richard.roe@example.com
	```
	\
	For example, if code owners for the file '/foo/bar/baz.txt' are computed the
	`OWNERS` files are evaluated in this order:

	1. `/foo/bar/OWNERS`
	2. `/foo/OWNERS`
	3. `/OWNERS`
	4. `/OWNERS` in `refs/meta/config`
	(contains [default code owners](backend-find-owners.html#defaultCodeOwnerConfiguration))

	If any `set noparent` file-level rule is seen the evaluation is stopped and
	further `OWNERS` files are ignored. E.g. if `/foo/OWNERS` contains
	`set noparent` the `OWNERS` files mentioned at 3. and 4. are ignored.

	NOTE: When the [set noparent](backend-find-owners.html#setNoparent)
	file-level rule is used you should always define code owners which should be
	used instead of the code owners from the parent directories. Otherwise the files
	in the directory stay [without code owners](#noCodeOwners) and nobody can grant
	code owner approval on them. To [exempt a directory from requiring code owner
	approvals](#exemptFiles), assign the code ownership to [all
	users](backend-find-owners.html#allUsers) instead ([example](#exemptFiles)).

	NOTE: The usage of `set noparent` has no effect on `OWNERS` files in
	subfolders.

	### <a id="defineCodeOwnersForAFile">Define code owners for a certain file

	By using the [per-file](backend-find-owners.html#perFile) restriction prefix it
	is possible to define code owners for a certain file (in the current directory
	and all its subdirectories), e.g. for the `BUILD` file:

	```
	per-file BUILD=tina.toe@example.com
	```
	\
	Multiple code owners for the same file can be specified as comma-separated list:

	```
	per-file BUILD=tina.toe@example.com,martha.moe@example.com
	```
	\
	Alternatively it's also possible to repeat the per-file line multiple times:

	```
	per-file BUILD=tina.toe@example.com
	per-file BUILD=martha.moe@example.com
	```
	\
	If a file is matched by the path expressions of multiple
	[per-file](backend-find-owners.html#perFile) lines, the file is owned by all
	users that are mentioned in these [per-file](backend-find-owners.html#perFile)
	lines.

	If folder code owners are present, the file is also owned by any folder code
	owners:

	```
	jane.roe@example.com
	john.doe@example.com
	richard.roe@example.com
	per-file BUILD=tina.toe@example.com,martha.moe@example.com
	```
	\
	In addition, the file is also owned by code owners that are inherited from
	parent directories.

	#### <a id="perFileWithSetNoparent">
	Ignoring folder code owners and inherited parent code owners for a file is
	possible by using a matching [per-file](backend-find-owners.html#perFile) line
	with [set noparent](backend-find-owners.html#setNoparent).

	```
	jane.roe@example.com
	john.doe@example.com
	richard.roe@example.com
	per-file BUILD=set noparent
	per-file BUILD=tina.toe@example.com,martha.moe@example.com
	```
	\
	For example, if code owners for the file '/foo/bar/baz.txt' are computed the
	code owners in the `OWNERS` files are evaluated in this order:

	1. matching per-file code owners in `/foo/bar/OWNERS`
	2. folder code owners in `/foo/bar/OWNERS`
	3. matching per-file code owners in `/foo/OWNERS`
	4. folder code owners in `/foo/OWNERS`
	5. matching per-file code owners in `/OWNERS`
	6. folder code owners in `/OWNERS`
	7. matching per-file code owners in `/OWNERS` in `refs/meta/config`
	(contains [default code owners](backend-find-owners.html#defaultCodeOwnerConfiguration))
	8. folder code owners in `/OWNERS` in `refs/meta/config`
	(contains [default code owners](backend-find-owners.html#defaultCodeOwnerConfiguration))

	If any `set noparent` file-level rule is seen the evaluation is stopped and
	code owners on further levels are ignored. E.g. if `/foo/OWNERS` contains a
	matching per-file rule with `set noparent` the code owners mentioned at 4. to 8.
	are ignored.

	NOTE: When the [set noparent](backend-find-owners.html#setNoparent) rule is
	used on a per-file rule you should always define code owners which should be
	used instead of the folder code owners and the code owners from the parent
	directories. Otherwise the matched files stay [without code
	owners](#noCodeOwners) and nobody can grant code owner approval on them. To
	[exempt matched files from requiring code owner approvals](#exemptFiles), assign
	the code ownership to [all users](backend-find-owners.html#allUsers) instead
	([example](#exemptFiles)).

	NOTE: The syntax for path expressions / globs is explained
	[here](path-expressions.html#globs).

	### <a id="defineCodeOwnersForAFileType">Define code owners for a certain file type

	This is the same as [defining code owners for a file](#defineCodeOwnersForAFile)
	only that the [per-file](backend-find-owners.html#perFile) line must have a path
	expression that matches all files of the wanted type, e.g. all '*.md' files:

	```
	per-file *.md=tina.toe@example.com
	```
	\
	This matches all '*.md' in the current directory and all its subdirectories.

	NOTE: Using '.md' is the same as using '*.md' (both expressions match
	files in the current directory and in all subdirectories).

	NOTE: The syntax for path expressions / globs is explained
	[here](path-expressions.html#globs).

	### <a id="defineCodeOwnersForAllFileInASubdirectory">Define code owners for all files in a subdirectory

	It is discouraged to use path expressions that explicitly name subdirectories
	such as `my-subdir/*` as they will break when the subdirectory gets
	renamed/moved. Instead prefer to define these code owners in `my-subdir/OWNERS`
	so that the code owners for the subdirectory stay intact when the subdirectory
	gets renamed/moved.

	Nontheless, it's possible to define code owners for all files in a subdirectory
	using a [per-file](backend-find-owners.html#perFile) line. This is the same as
	[defining code owners for a file](#defineCodeOwnersForAFile) only that the path
	expression matches all files in the subdirectory:

	```
	per-file my-subdir/*=tina.toe@example.com
	```

	### <a id="defineAGroupAsCodeOwner">Define a group as code owner

	Groups are not supported in `OWNERS` files and assigning code ownership to them
	is not possible.

	Instead of using a group you may define a set of users in an `OWNERS` file with
	a prefix (`<prefix>_OWNERS`) or an extension (`OWNERS_<extension>`) and then
	[import](#importOtherOwnersFile) it into other `OWNERS` files via the
	[file](backend-find-owners.html#fileKeyword) keyword.

	`/OWNERS_BUILD`:
	```
	jane.roe@example.com
	john.doe@example.com
	richard.roe@example.com
	per-file BUILD=tina.toe@example.com
	```
	\
	other `OWNERS` file:
	```
	per-file BUILD=file:/OWNERS_BUILD
	```
	\
	This is equivalent to having:

	```
	per-file BUILD=jane.roe@example.com,john.doe@example.com,richard.roe@example.com
	```
	\
	NOTE: The `per-file` line from `/OWNERS_BUILD` is not imported, since the
	[file](backend-find-owners.html#fileKeyword) keyword only imports folder code
	owners. Using the [include](backend-find-owners.html#includeKeyword) keyword,
	that would also consider per-file code owners, is not supported for `per-file`
	lines.

	### <a id="importOtherOwnersFile">Import code owners from other OWNERS file

	To import code owners from another `OWNERS` file the
	[file](backend-find-owners.html#fileKeyword) or
	[include](backend-find-owners.html#includeKeyword) keyword can be used:

	`java/com/example/foo/OWNERS`:
	```
	jane.roe@example.com
	john.doe@example.com
	richard.roe@example.com
	per-file BUILD=tina.toe@example.com
	```
	\
	`javatests/com/example/foo/OWNERS`:
	```
	file:/java/com/example/foo/OWNERS
	```
	\
	This is equivalent to having:

	```
	jane.roe@example.com
	john.doe@example.com
	richard.roe@example.com
	```
	\
	NOTE: The `per-file` line from `java/com/example/foo/OWNERS` is not
	imported, since the [file](backend-find-owners.html#fileKeyword) keyword only
	imports folder code owners. If also `per-line` lines should be imported the
	[include](backend-find-owners.html#includeKeyword) keyword can be used instead:

	`javatests/com/example/foo/OWNERS`:
	```
	include /java/com/example/foo/OWNERS
	```
	\
	This is equivalent to having:

	```
	jane.roe@example.com
	john.doe@example.com
	richard.roe@example.com
	per-file BUILD=tina.toe@example.com
	```

	### <a id="importFromOtherRepository">Import code owners from other repository

	To import code owners from an `OWNERS` file in another repository the
	[file](backend-find-owners.html#fileKeyword) or
	[include](backend-find-owners.html#includeKeyword) keyword can be used:

	`/OWNERS` in the `master` branch of respository `my-project`:
	```
	jane.roe@example.com
	john.doe@example.com
	richard.roe@example.com
	```
	\
	`/OWNERS` in the `master` branch of respository `my-project/plugin-foo`:
	```
	file:my-project:/OWNERS
	```
	\
	This way `my-project/plugin-foo` always has the same code owners as
	`my-project`.

	NOTE: If a branch is not specified, the `OWNERS` file will always be
	imported from the same branch, in which the importing `OWNERS` file is stored.
	If `file:my-project:/OWNERS` is contained in an `OWNERS` file in the `master`
	branch, `my-project:master:/OWNERS` is imported. If `file:my-project:/OWNERS` is
	contained in an `OWNERS` file in the `stable-3.5` branch,
	`my-project:stable-3.5:/OWNERS` is imported.

	### <a id="importFromOtherBranch">Import code owners from other branch

	To import code owners from an `OWNERS` file in another branch the
	[file](backend-find-owners.html#fileKeyword) or
	[include](backend-find-owners.html#includeKeyword) keyword can be used:

	`/OWNERS` in the `master` branch of respository `my-project`:
	```
	jane.roe@example.com
	john.doe@example.com
	richard.roe@example.com
	```
	\
	`/OWNERS` in the `stable-3.5` branch of respository `my-project`:
	```
	file:my-project:master:/OWNERS
	```
	\
	This way the `stable-3.5` branch of `my-project` always has the same global code
	owners as the `master` branch of `my-project`.

	NOTE: To import code owners from another branch it is mandatory to specify
	the repository, even if it is the same repository that contains the importing
	`OWNERS` file.

	### <a id="exemptFiles">Exempt files from requiring code owner approval

	To exempt files from requiring code owner approval the code ownership can be
	assigned to [all users](backend-find-owners.html#allUsers) by using '*' as
	[user email](backend-find-owners.html#userEmails). Assigning the code ownership
	to all users effectively exempts the directory (or the matches files if used in
	combination with a [per-file](backend-find-owners.html#perFile) rule) from
	requiring code owner approvals on submit. This is because a code owner approval
	from the uploader is always implicit if the uploader is a code owner.

	`OWNERS` file that exempts the whole directory from requiring code owner
	approvals:
	```
	*
	```
	\
	`OWNERS` files that exempts all '*.md' files (in the current directory and all
	subdirectories) from requiring code owner approvals:
	```
	per-file .md=
	```
	\
	NOTE: Files that are not owned by anyone are not excluded from requiring
	code ower approvals, see [next section](#noCodeOwners).

	### <a id="noCodeOwners">Avoid that files are not owned by anyone

	Files that are not owned by anyone cannot be approved since there is no code
	owner that can grant the approval. Hence submitting modifications to them is
	only possible with an override approval.

	Due to this it is recommended to avoid code owner configurations that leave
	files without code owners, e.g. the following configurations should be avoided:

	* an `OWNERS` file with only `set noparent` (ignores code owners from parent
	directories, but doesn't define code owners that should be used instead)
	* a `per-file` line with only `set noparent` (ignores folder code owners and
	code owners from parent directories, but doesn't define code owners that
	should be used instead)
	* no `OWNERS` file at root level

	NOTE: How to exempt files from requiring code owner approval is described
	[here](#exemptFiles).

	---

	Back to [@PLUGIN@ documentation index](index.html)

	Part of [Gerrit Code Review](../../../Documentation/index.html)