summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLibravatar Junio C Hamano <gitster@pobox.com>2017-05-29 12:34:47 +0900
committerLibravatar Junio C Hamano <gitster@pobox.com>2017-05-29 12:34:47 +0900
commited9806014d06fb1757a45d7f789859b91d9fb765 (patch)
tree577a175c0fc199fd5f7c2c9d4645da85e1ca79df
parentMerge branch 'sg/core-filemode-doc-typofix' (diff)
parentdocs/config: consistify include.path examples (diff)
downloadtgif-ed9806014d06fb1757a45d7f789859b91d9fb765.tar.xz
Merge branch 'jk/doc-config-include'
Clarify documentation for include.path and includeIf.<condition>.path configuration variables. * jk/doc-config-include: docs/config: consistify include.path examples docs/config: avoid the term "expand" for includes docs/config: give a relative includeIf example docs/config: clarify include/includeIf relationship
-rw-r--r--Documentation/config.txt31
1 files changed, 21 insertions, 10 deletions
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 51143b624a..ab3ed72d34 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -79,14 +79,20 @@ escape sequences) are invalid.
Includes
~~~~~~~~
+The `include` and `includeIf` sections allow you to include config
+directives from another source. These sections behave identically to
+each other with the exception that `includeIf` sections may be ignored
+if their condition does not evaluate to true; see "Conditional includes"
+below.
+
You can include a config file from another by setting the special
-`include.path` variable to the name of the file to be included. The
-variable takes a pathname as its value, and is subject to tilde
-expansion. `include.path` can be given multiple times.
+`include.path` (or `includeIf.*.path`) variable to the name of the file
+to be included. The variable takes a pathname as its value, and is
+subject to tilde expansion. These variables can be given multiple times.
-The included file is expanded immediately, as if its contents had been
-found at the location of the include directive. If the value of the
-`include.path` variable is a relative path, the path is considered to
+The contents of the included file are inserted immediately, as if they
+had been found at the location of the include directive. If the value of the
+variable is a relative path, the path is considered to
be relative to the configuration file in which the include directive
was found. See below for examples.
@@ -95,8 +101,7 @@ Conditional includes
You can include a config file from another conditionally by setting a
`includeIf.<condition>.path` variable to the name of the file to be
-included. The variable's value is treated the same way as
-`include.path`. `includeIf.<condition>.path` can be given multiple times.
+included.
The condition starts with a keyword followed by a colon and some data
whose format and meaning depends on the keyword. Supported keywords
@@ -167,8 +172,8 @@ Example
[include]
path = /path/to/foo.inc ; include by absolute path
- path = foo ; expand "foo" relative to the current file
- path = ~/foo ; expand "foo" in your `$HOME` directory
+ path = foo.inc ; find "foo.inc" relative to the current file
+ path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory
; include if $GIT_DIR is /path/to/foo/.git
[includeIf "gitdir:/path/to/foo/.git"]
@@ -182,6 +187,12 @@ Example
[includeIf "gitdir:~/to/group/"]
path = /path/to/foo.inc
+ ; relative paths are always relative to the including
+ ; file (if the condition is true); their location is not
+ ; affected by the condition
+ [includeIf "gitdir:/path/to/group/"]
+ path = foo.inc
+
Values
~~~~~~