Merge branch 'hv/submodule-recurse-push'
[gitweb.git] / Documentation / config.txt
index c6630c73e88cc9c43e2f51542c1422d21d5dfc95..fb386abc514efef6cb94521c4f5546b5c51ab296 100644 (file)
@@ -12,8 +12,9 @@ The configuration variables are used by both the git plumbing
 and the porcelains. The variables are divided into sections, wherein
 the fully qualified variable name of the variable itself is the last
 dot-separated segment and the section name is everything before the last
-dot. The variable names are case-insensitive and only alphanumeric
-characters are allowed. Some variables may appear multiple times.
+dot. The variable names are case-insensitive, allow only alphanumeric
+characters and `-`, and must start with an alphabetic character.  Some
+variables may appear multiple times.
 
 Syntax
 ~~~~~~
@@ -54,9 +55,10 @@ All the other lines (and the remainder of the line after the section
 header) are recognized as setting variables, in the form
 'name = value'.  If there is no equal sign on the line, the entire line
 is taken as 'name' and the variable is recognized as boolean "true".
-The variable names are case-insensitive and only alphanumeric
-characters and `-` are allowed.  There can be more than one value
-for a given variable; we say then that variable is multivalued.
+The variable names are case-insensitive, allow only alphanumeric characters
+and `-`, and must start with an alphabetic character.  There can be more
+than one value for a given variable; we say then that the variable is
+multivalued.
 
 Leading and trailing whitespace in a variable value is discarded.
 Internal whitespace within a variable value is retained verbatim.
@@ -84,6 +86,17 @@ customary UNIX fashion.
 
 Some variables may require a special value format.
 
+Includes
+~~~~~~~~
+
+You can include one config file from another by setting the special
+`include.path` variable to the name of the file to be included. 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 be
+relative to the configuration file in which the include directive was
+found. See below for examples.
+
 Example
 ~~~~~~~
 
@@ -106,6 +119,10 @@ Example
                gitProxy="ssh" for "kernel.org"
                gitProxy=default-proxy ; for the rest
 
+       [include]
+               path = /path/to/foo.inc ; include by absolute path
+               path = foo ; expand "foo" relative to the current file
+
 Variables
 ~~~~~~~~~
 
@@ -115,35 +132,47 @@ in the appropriate manual page. You will find a description of non-core
 porcelain configuration variables in the respective porcelain documentation.
 
 advice.*::
-       When set to 'true', display the given optional help message.
-       When set to 'false', do not display. The configuration variables
-       are:
+       These variables control various optional help messages designed to
+       aid new users. All 'advice.*' variables default to 'true', and you
+       can tell Git that you do not need help by setting these to 'false':
 +
 --
        pushNonFastForward::
-               Advice shown when linkgit:git-push[1] refuses
-               non-fast-forward refs. Default: true.
+               Set this variable to 'false' if you want to disable
+               'pushNonFFCurrent', 'pushNonFFDefault', and
+               'pushNonFFMatching' simultaneously.
+       pushNonFFCurrent::
+               Advice shown when linkgit:git-push[1] fails due to a
+               non-fast-forward update to the current branch.
+       pushNonFFDefault::
+               Advice to set 'push.default' to 'upstream' or 'current'
+               when you ran linkgit:git-push[1] and pushed 'matching
+               refs' by default (i.e. you did not provide an explicit
+               refspec, and no 'push.default' configuration was set)
+               and it resulted in a non-fast-forward error.
+       pushNonFFMatching::
+               Advice shown when you ran linkgit:git-push[1] and pushed
+               'matching refs' explicitly (i.e. you used ':', or
+               specified a refspec that isn't your current branch) and
+               it resulted in a non-fast-forward error.
        statusHints::
                Directions on how to stage/unstage/add shown in the
                output of linkgit:git-status[1] and the template shown
-               when writing commit messages. Default: true.
+               when writing commit messages.
        commitBeforeMerge::
                Advice shown when linkgit:git-merge[1] refuses to
                merge to avoid overwriting local changes.
-               Default: true.
        resolveConflict::
                Advices shown by various commands when conflicts
                prevent the operation from being performed.
-               Default: true.
        implicitIdentity::
                Advice on how to set your identity configuration when
                your information is guessed from the system username and
-               domain name. Default: true.
-
+               domain name.
        detachedHead::
-               Advice shown when you used linkgit::git-checkout[1] to
+               Advice shown when you used linkgit:git-checkout[1] to
                move to the detach HEAD state, to instruct how to create
-               a local branch after the fact.  Default: true.
+               a local branch after the fact.
 --
 
 core.fileMode::
@@ -1126,6 +1155,17 @@ grep.lineNumber::
 grep.extendedRegexp::
        If set to true, enable '--extended-regexp' option by default.
 
+gpg.program::
+       Use this custom program instead of "gpg" found on $PATH when
+       making or verifying a PGP signature. The program must support the
+       same command line interface as GPG, namely, to verify a detached
+       signature, "gpg --verify $file - <$signature" is run, and the
+       program is expected to signal a good signature by exiting with
+       code 0, and to generate an ascii-armored detached signature, the
+       standard input of "gpg -bsau $key" is fed with the contents to be
+       signed, and the program is expected to send the result to its
+       standard output.
+
 gui.commitmsgwidth::
        Defines how wide the commit message window is in the
        linkgit:git-gui[1]. "75" is the default.
@@ -1250,9 +1290,10 @@ help.autocorrect::
        This is the default.
 
 http.proxy::
-       Override the HTTP proxy, normally configured using the 'http_proxy'
-       environment variable (see linkgit:curl[1]).  This can be overridden
-       on a per-remote basis; see remote.<name>.proxy
+       Override the HTTP proxy, normally configured using the 'http_proxy',
+       'https_proxy', and 'all_proxy' environment variables (see
+       `curl(1)`).  This can be overridden on a per-remote basis; see
+       remote.<name>.proxy
 
 http.cookiefile::
        File containing previously stored cookie lines which should be used
@@ -1775,10 +1816,11 @@ rerere.autoupdate::
 
 rerere.enabled::
        Activate recording of resolved conflicts, so that identical
-       conflict hunks can be resolved automatically, should they
-       be encountered again.  linkgit:git-rerere[1] command is by
-       default enabled if you create `rr-cache` directory under
-       `$GIT_DIR`, but can be disabled by setting this option to false.
+       conflict hunks can be resolved automatically, should they be
+       encountered again.  By default, linkgit:git-rerere[1] is
+       enabled if there is an `rr-cache` directory under the
+       `$GIT_DIR`, e.g. if "rerere" was previously used in the
+       repository.
 
 sendemail.identity::
        A configuration identity. When given, causes values in the