From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 29 May 2017 03:34:47 +0000 (+0900)
Subject: Merge branch 'jk/doc-config-include'
X-Git-Tag: v2.14.0-rc0~159
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/ed9806014d06fb1757a45d7f789859b91d9fb765?hp=-c

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
---

ed9806014d06fb1757a45d7f789859b91d9fb765
diff --combined Documentation/config.txt
index 51143b624a,c398d9a846..ab3ed72d34
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@@ -79,14 -79,20 +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 +101,7 @@@ Conditional include
  
  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 +172,8 @@@ Exampl
  
  	[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 +187,12 @@@
  	[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
  ~~~~~~
  
@@@ -334,7 -345,7 +345,7 @@@ core.fileMode:
  	is to be honored.
  +
  Some filesystems lose the executable bit when a file that is
 -marked as executable is checked out, or checks out an
 +marked as executable is checked out, or checks out a
  non-executable file with executable bit on.
  linkgit:git-clone[1] or linkgit:git-init[1] probe the filesystem
  to see if it handles the executable bit correctly
@@@ -1137,10 -1148,7 +1148,10 @@@ color.status.<slot>:
  	`untracked` (files which are not tracked by Git),
  	`branch` (the current branch),
  	`nobranch` (the color the 'no branch' warning is shown in, defaulting
 -	to red), or
 +	to red),
 +	`localBranch` or `remoteBranch` (the local and remote branch names,
 +	respectively, when branch and tracking information is displayed in the
 +	status short-format), or
  	`unmerged` (files which have unmerged changes).
  
  color.ui::
@@@ -2623,8 -2631,9 +2634,8 @@@ receive.advertiseAtomic:
  	capability, set this variable to false.
  
  receive.advertisePushOptions::
 -	By default, git-receive-pack will advertise the push options
 -	capability to its clients. If you don't want to advertise this
 -	capability, set this variable to false.
 +	When set to true, git-receive-pack will advertise the push options
 +	capability to its clients. False by default.
  
  receive.autogc::
  	By default, git-receive-pack will run "git-gc --auto" after