[PATCH 2/3] Documentation/config: add includeIf "worktree"
From: Chen Linxuan <me@black-desk.cn>
Add documentation for the newly introduced `worktree` and `worktree/i`
conditional include keywords. Describe how they differ from `gitdir`
(matching the working tree checkout path instead of the `.git`
directory path), and list the supported pattern features: glob
wildcards, `**/` and `/**`, `~` expansion, `./` relative paths, and
trailing-`/` prefix matching. Note that the condition never matches
in a bare repository. Also add usage examples alongside the existing
`gitdir` examples.
---
Documentation/config.adoc | 50 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 50 insertions(+)
diff --git a/Documentation/config.adoc b/Documentation/config.adoc
index 62eebe7c5450..a4f3ec905098 100644
--- a/Documentation/config.adoc
+++ b/Documentation/config.adoc
@@ -146,6 +146,48 @@ refer to linkgit:gitignore[5] for details. For convenience:
This is the same as `gitdir` except that matching is done
case-insensitively (e.g. on case-insensitive file systems)
+`worktree`::
+ The data that follows the keyword `worktree` and a colon is used as a
+ glob pattern. If the working directory of the current worktree matches
+ the pattern, the include condition is met.
++
+The worktree location is the path where files are checked out (as returned
+by `git rev-parse --show-toplevel`). This is different from `gitdir`, which
+matches the `.git` directory path. In a linked worktree, the worktree path
+is the directory where that worktree's files are located, not the main
+repository's `.git` directory.
++
+The pattern can contain standard globbing wildcards and two additional
+ones, `**/` and `/**`, that can match multiple path components. Please
+refer to linkgit:gitignore[5] for details. For convenience:
+
+ * If the pattern starts with `~/`, `~` will be substituted with the
+ content of the environment variable `HOME`.
+
+ * If the pattern starts with `./`, it is replaced with the directory
+ containing the current config file.
+
+ * If the pattern does not start with either `~/`, `./` or `/`, `**/`
+ will be automatically prepended. For example, the pattern `foo/bar`
+ becomes `**/foo/bar` and would match `/any/path/to/foo/bar`.
+
+ * If the pattern ends with `/`, `**` will be automatically added. For
+ example, the pattern `foo/` becomes `foo/**`. In other words, it
+ matches "foo" and everything inside, recursively.
++
+This condition will never match in a bare repository (which has no worktree).
++
+This is useful when you need to use different `user.name`, `user.email`, or
+GPG keys in different worktrees of the same repository. While
+`extensions.worktreeConfig` also allows per-worktree configuration, it
+requires changes inside each repository. This condition can be set in the
+user's global configuration file (e.g. `~/.config/git/config`) and applies
+to multiple repositories at once.
+
+`worktree/i`::
+ This is the same as `worktree` except that matching is done
+ case-insensitively (e.g. on case-insensitive file systems)
+
`onbranch`::
The data that follows the keyword `onbranch` and a colon is taken to be a
pattern with standard globbing wildcards and two additional
@@ -244,6 +286,14 @@ Example
[includeIf "gitdir:~/to/group/"]
path = /path/to/foo.inc
+; include if the worktree is at /path/to/project-build
+[includeIf "worktree:/path/to/project-build"]
+ path = build-config.inc
+
+; include for all worktrees inside /path/to/group
+[includeIf "worktree:/path/to/group/"]
+ path = group-config.inc
+
; relative paths are always relative to the including
; file (if the condition is true); their location is not
; affected by the condition
--
2.53.0
Chen Linxuan via B4 Relay <devnull+me.black-desk.cn@kernel.org>