From 9d71d94d34fb3d3bb206ab9d5dbe08eb529ca729 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 11 May 2017 05:10:47 -0400 Subject: docs/config: clarify include/includeIf relationship MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "includeIf" directives behave exactly like include ones, except they only kick in when the conditional is true. That was mentioned in the "conditional" section, but let's make it more clear for the whole "includes" section, since people don't necessarily read the documentation top to bottom. Signed-off-by: Jeff King Reviewed-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/config.txt | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/config.txt b/Documentation/config.txt index 475e874d51..7e7a358aea 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 +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..path` variable to the name of the file to be -included. The variable's value is treated the same way as -`include.path`. `includeIf..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 -- cgit v1.2.1 From 994cd6c7ca2da9bf09582ba08cbad583cba76968 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 11 May 2017 05:11:06 -0400 Subject: docs/config: give a relative includeIf example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The changes in the previous commit hopefully clarify that the evaluation of an include "path" variable is the same no matter if it's in a conditional section or not. But since this question came up on the list, let's add an example that makes it obvious. Signed-off-by: Jeff King Reviewed-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/config.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation') diff --git a/Documentation/config.txt b/Documentation/config.txt index 7e7a358aea..cc6d79e537 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -187,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 ~~~~~~ -- cgit v1.2.1 From a076df2813a4f1c93b22ca586865b32b3e3a08a7 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 11 May 2017 05:13:04 -0400 Subject: docs/config: avoid the term "expand" for includes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Using the word "expand" to refer to including the contents of another config file isn't really accurate, since it's a verbatim insertion. And it can cause confusion with the expanding of the path itself via things like "~". Let's clarify when we are referring to the contents versus the filename, and use appropriate verbs in each case. Signed-off-by: Jeff King Reviewed-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/config.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/config.txt b/Documentation/config.txt index cc6d79e537..be75f70055 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -90,8 +90,8 @@ You can include a config file from another by setting the special 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 +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. @@ -172,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 ; find "foo" relative to the current file + path = ~/foo ; find "foo" in your `$HOME` directory ; include if $GIT_DIR is /path/to/foo/.git [includeIf "gitdir:/path/to/foo/.git"] -- cgit v1.2.1 From ce933ebd5a4a68a1042661499c05368bb60fd523 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 11 May 2017 05:14:30 -0400 Subject: docs/config: consistify include.path examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Most of the include examples use "foo.inc", but some use "foo". Since the string of examples are meant to show variations and how they differ, it's a good idea to change only one thing at a time. The filename differences are not relevant to what we're trying to show. Signed-off-by: Jeff King Reviewed-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/config.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/config.txt b/Documentation/config.txt index be75f70055..c398d9a846 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -172,8 +172,8 @@ Example [include] path = /path/to/foo.inc ; include by absolute path - path = foo ; find "foo" relative to the current file - path = ~/foo ; find "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"] -- cgit v1.2.1