Merge branch 'jk/doc-the-this' into maint
authorJunio C Hamano <gitster@pobox.com>
Sun, 10 Sep 2017 08:03:07 +0000 (17:03 +0900)
committerJunio C Hamano <gitster@pobox.com>
Sun, 10 Sep 2017 08:03:07 +0000 (17:03 +0900)
Doc clean-up.

* jk/doc-the-this:
  doc: fix typo in sendemail.identity

1  2 
Documentation/config.txt

diff --combined Documentation/config.txt
@@@ -79,84 -79,18 +79,84 @@@ escape sequences) are invalid
  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
 -variable takes a pathname as its value, and is subject to tilde
 -expansion.
 +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.
  
 -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.
 +You can include a config file from another by setting the special
 +`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 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.
 +
 +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 condition starts with a keyword followed by a colon and some data
 +whose format and meaning depends on the keyword. Supported keywords
 +are:
 +
 +`gitdir`::
 +
 +      The data that follows the keyword `gitdir:` is used as a glob
 +      pattern. If the location of the .git directory matches the
 +      pattern, the include condition is met.
 ++
 +The .git location may be auto-discovered, or come from `$GIT_DIR`
 +environment variable. If the repository is auto discovered via a .git
 +file (e.g. from submodules, or a linked worktree), the .git location
 +would be the final location where the .git directory is, not where the
 +.git file is.
 ++
 +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.
 +
 +`gitdir/i`::
 +      This is the same as `gitdir` except that matching is done
 +      case-insensitively (e.g. on case-insensitive file sytems)
 +
 +A few more notes on matching via `gitdir` and `gitdir/i`:
 +
 + * Symlinks in `$GIT_DIR` are not resolved before matching.
 +
 + * Both the symlink & realpath versions of paths will be matched
 +   outside of `$GIT_DIR`. E.g. if ~/git is a symlink to
 +   /mnt/storage/git, both `gitdir:~/git` and `gitdir:/mnt/storage/git`
 +   will match.
 ++
 +This was not the case in the initial release of this feature in
 +v2.13.0, which only matched the realpath version. Configuration that
 +wants to be compatible with the initial release of this feature needs
 +to either specify only the realpath version, or both versions.
 +
 + * Note that "../" is not special and will match literally, which is
 +   unlikely what you want.
  
  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"]
 +              path = /path/to/foo.inc
 +
 +      ; include for all repositories inside /path/to/group
 +      [includeIf "gitdir:/path/to/group/"]
 +              path = /path/to/foo.inc
 +
 +      ; include for all repositories inside $HOME/to/group
 +      [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
  ~~~~~~
@@@ -216,15 -133,15 +216,15 @@@ boolean:
         synonyms are accepted for 'true' and 'false'; these are all
         case-insensitive.
  
 -       true;; Boolean true can be spelled as `yes`, `on`, `true`,
 -              or `1`.  Also, a variable defined without `= <value>`
 +      true;; Boolean true literals are `yes`, `on`, `true`,
 +              and `1`.  Also, a variable defined without `= <value>`
                is taken as true.
  
 -       false;; Boolean false can be spelled as `no`, `off`,
 -              `false`, or `0`.
 +      false;; Boolean false literals are `no`, `off`, `false`,
 +              `0` and the empty string.
  +
  When converting value to the canonical form using `--bool` type
 -specifier; 'git config' will ensure that the output is "true" or
 +specifier, 'git config' will ensure that the output is "true" or
  "false" (spelled in lowercase).
  
  integer::
@@@ -348,9 -265,6 +348,9 @@@ advice.*:
        rmHints::
                In case of failure in the output of linkgit:git-rm[1],
                show directions on how to proceed from the current state.
 +      addEmbeddedRepo::
 +              Advice on what to do when you've accidentally added one
 +              git repo inside of another.
  --
  
  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
@@@ -420,10 -334,6 +420,10 @@@ core.trustctime:
        crawlers and some backup systems).
        See linkgit:git-update-index[1]. True by default.
  
 +core.splitIndex::
 +      If true, the split-index feature of the index will be used.
 +      See linkgit:git-update-index[1]. False by default.
 +
  core.untrackedCache::
        Determines what to do about the untracked cache feature of the
        index. It will be kept, if this variable is unset or set to
@@@ -440,19 -350,16 +440,19 @@@ core.checkStat:
        all fields, including the sub-second part of mtime and ctime.
  
  core.quotePath::
 -      The commands that output paths (e.g. 'ls-files',
 -      'diff'), when not given the `-z` option, will quote
 -      "unusual" characters in the pathname by enclosing the
 -      pathname in a double-quote pair and with backslashes the
 -      same way strings in C source code are quoted.  If this
 -      variable is set to false, the bytes higher than 0x80 are
 -      not quoted but output as verbatim.  Note that double
 -      quote, backslash and control characters are always
 -      quoted without `-z` regardless of the setting of this
 -      variable.
 +      Commands that output paths (e.g. 'ls-files', 'diff'), will
 +      quote "unusual" characters in the pathname by enclosing the
 +      pathname in double-quotes and escaping those characters with
 +      backslashes in the same way C escapes control characters (e.g.
 +      `\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with
 +      values larger than 0x80 (e.g. octal `\302\265` for "micro" in
 +      UTF-8).  If this variable is set to false, bytes higher than
 +      0x80 are not considered "unusual" any more. Double-quotes,
 +      backslash and control characters are always escaped regardless
 +      of the setting of this variable.  A simple space character is
 +      not considered "unusual".  Many commands can output pathnames
 +      completely verbatim using the `-z` option. The default value
 +      is true.
  
  core.eol::
        Sets the line ending type to use in the working directory for
@@@ -686,8 -593,7 +686,8 @@@ core.packedGitLimit:
        bytes at once to complete an operation it will unmap existing
        regions to reclaim virtual address space within the process.
  +
 -Default is 256 MiB on 32 bit platforms and 8 GiB on 64 bit platforms.
 +Default is 256 MiB on 32 bit platforms and 32 TiB (effectively
 +unlimited) on 64 bit platforms.
  This should be reasonable for all users/operating systems, except on
  the largest projects.  You probably do not need to adjust this value.
  +
@@@ -887,7 -793,6 +887,7 @@@ core.abbrev:
        computed based on the approximate number of packed objects
        in your repository, which hopefully is enough for
        abbreviated object names to stay unique for some time.
 +      The minimum length is 4.
  
  add.ignoreErrors::
  add.ignore-errors (deprecated)::
@@@ -1163,10 -1068,7 +1163,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::
@@@ -2023,10 -1925,7 +2023,10 @@@ http.<url>.*:
    must match exactly between the config key and the URL.
  
  . Host/domain name (e.g., `example.com` in `https://example.com/`).
 -  This field must match exactly between the config key and the URL.
 +  This field must match between the config key and the URL. It is
 +  possible to specify a `*` as part of the host name to match all subdomains
 +  at this level. `https://*.example.com/` for example would match
 +  `https://foo.example.com/`, but not `https://foo.bar.example.com/`.
  
  . Port number (e.g., `8080` in `http://example.com:8080/`).
    This field must match exactly between the config key and the URL.
@@@ -2061,17 -1960,6 +2061,17 @@@ Environment variable settings always ov
  matched against are those given directly to Git commands.  This means any URLs
  visited as a result of a redirection do not participate in matching.
  
 +ssh.variant::
 +      Depending on the value of the environment variables `GIT_SSH` or
 +      `GIT_SSH_COMMAND`, or the config setting `core.sshCommand`, Git
 +      auto-detects whether to adjust its command-line parameters for use
 +      with plink or tortoiseplink, as opposed to the default (OpenSSH).
 ++
 +The config variable `ssh.variant` can be set to override this auto-detection;
 +valid values are `ssh`, `plink`, `putty` or `tortoiseplink`. Any other value
 +will be treated as normal ssh. This setting can be overridden via the
 +environment variable `GIT_SSH_VARIANT`.
 +
  i18n.commitEncoding::
        Character encoding the commit messages are stored in; Git itself
        does not care per se, but this information is necessary e.g. when
@@@ -2169,10 -2057,6 +2169,10 @@@ log.showRoot:
        Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which
        normally hide the root commit will now show it. True by default.
  
 +log.showSignature::
 +      If true, makes linkgit:git-log[1], linkgit:git-show[1], and
 +      linkgit:git-whatchanged[1] assume `--show-signature`.
 +
  log.mailmap::
        If true, makes linkgit:git-log[1], linkgit:git-show[1], and
        linkgit:git-whatchanged[1] assume `--use-mailmap`.
@@@ -2624,7 -2508,7 +2624,7 @@@ rebase.autoSquash:
        If set to true enable `--autosquash` option by default.
  
  rebase.autoStash::
 -      When set to true, automatically create a temporary stash
 +      When set to true, automatically create a temporary stash entry
        before the operation begins, and apply it after the operation
        ends.  This means that you can run rebase on a dirty worktree.
        However, use with care: the final stash application after a
@@@ -2653,8 -2537,9 +2653,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
@@@ -2912,8 -2797,8 +2912,8 @@@ sendemail.smtpsslcertpath:
  
  sendemail.<identity>.*::
        Identity-specific versions of the 'sendemail.*' parameters
-       found below, taking precedence over those when the this
-       identity is selected, through command-line or
+       found below, taking precedence over those when this
+       identity is selected, through either the command-line or
        `sendemail.identity`.
  
  sendemail.aliasesFile::
@@@ -2946,45 -2831,10 +2946,45 @@@ sendemail.xmailer:
  sendemail.signedoffcc (deprecated)::
        Deprecated alias for `sendemail.signedoffbycc`.
  
 +sendemail.smtpBatchSize::
 +      Number of messages to be sent per connection, after that a relogin
 +      will happen.  If the value is 0 or undefined, send all messages in
 +      one connection.
 +      See also the `--batch-size` option of linkgit:git-send-email[1].
 +
 +sendemail.smtpReloginDelay::
 +      Seconds wait before reconnecting to smtp server.
 +      See also the `--relogin-delay` option of linkgit:git-send-email[1].
 +
  showbranch.default::
        The default set of branches for linkgit:git-show-branch[1].
        See linkgit:git-show-branch[1].
  
 +splitIndex.maxPercentChange::
 +      When the split index feature is used, this specifies the
 +      percent of entries the split index can contain compared to the
 +      total number of entries in both the split index and the shared
 +      index before a new shared index is written.
 +      The value should be between 0 and 100. If the value is 0 then
 +      a new shared index is always written, if it is 100 a new
 +      shared index is never written.
 +      By default the value is 20, so a new shared index is written
 +      if the number of entries in the split index would be greater
 +      than 20 percent of the total number of entries.
 +      See linkgit:git-update-index[1].
 +
 +splitIndex.sharedIndexExpire::
 +      When the split index feature is used, shared index files that
 +      were not modified since the time this variable specifies will
 +      be removed when a new shared index file is created. The value
 +      "now" expires all entries immediately, and "never" suppresses
 +      expiration altogether.
 +      The default value is "2.weeks.ago".
 +      Note that a shared index file is considered modified (for the
 +      purpose of expiration) each time a new split-index file is
 +      either created based on it or read from it.
 +      See linkgit:git-update-index[1].
 +
  status.relativePaths::
        By default, linkgit:git-status[1] shows paths relative to the
        current directory. Setting this variable to `false` shows paths
@@@ -3006,11 -2856,6 +3006,11 @@@ status.displayCommentPrefix:
        behavior of linkgit:git-status[1] in Git 1.8.4 and previous.
        Defaults to false.
  
 +status.showStash::
 +      If set to true, linkgit:git-status[1] will display the number of
 +      entries currently stashed away.
 +      Defaults to false.
 +
  status.showUntrackedFiles::
        By default, linkgit:git-status[1] and linkgit:git-commit[1] show
        files which are not currently tracked by Git. Directories which
@@@ -3048,21 -2893,20 +3048,21 @@@ status.submoduleSummary:
  
  stash.showPatch::
        If this is set to true, the `git stash show` command without an
 -      option will show the stash in patch form.  Defaults to false.
 +      option will show the stash entry in patch form.  Defaults to false.
        See description of 'show' command in linkgit:git-stash[1].
  
  stash.showStat::
        If this is set to true, the `git stash show` command without an
 -      option will show diffstat of the stash.  Defaults to true.
 +      option will show diffstat of the stash entry.  Defaults to true.
        See description of 'show' command in linkgit:git-stash[1].
  
  submodule.<name>.url::
        The URL for a submodule. This variable is copied from the .gitmodules
        file to the git config via 'git submodule init'. The user can change
        the configured URL before obtaining the submodule via 'git submodule
 -      update'. After obtaining the submodule, the presence of this variable
 -      is used as a sign whether the submodule is of interest to git commands.
 +      update'. If neither submodule.<name>.active or submodule.active are
 +      set, the presence of this variable is used as a fallback to indicate
 +      whether the submodule is of interest to git commands.
        See linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.
  
  submodule.<name>.update::
@@@ -3100,21 -2944,6 +3100,21 @@@ submodule.<name>.ignore:
        "--ignore-submodules" option. The 'git submodule' commands are not
        affected by this setting.
  
 +submodule.<name>.active::
 +      Boolean value indicating if the submodule is of interest to git
 +      commands.  This config option takes precedence over the
 +      submodule.active config option.
 +
 +submodule.active::
 +      A repeated field which contains a pathspec used to match against a
 +      submodule's path to determine if the submodule is of interest to git
 +      commands.
 +
 +submodule.recurse::
 +      Specifies if commands recurse into submodules by default. This
 +      applies to all commands that have a `--recurse-submodules` option.
 +      Defaults to false.
 +
  submodule.fetchJobs::
        Specifies how many submodules are fetched/cloned at the same time.
        A positive integer allows up to that number of submodules fetched
@@@ -3260,13 -3089,6 +3260,13 @@@ url.<base>.insteadOf:
        the best alternative for the particular user, even for a
        never-before-seen repository on the site.  When more than one
        insteadOf strings match a given URL, the longest match is used.
 ++
 +Note that any protocol restrictions will be applied to the rewritten
 +URL. If the rewrite changes the URL to use a custom protocol or remote
 +helper, you may need to adjust the `protocol.*.allow` config to permit
 +the request.  In particular, protocols you expect to use for submodules
 +must be set to `always` rather than the default of `user`. See the
 +description of `protocol.allow` above.
  
  url.<base>.pushInsteadOf::
        Any URL that starts with this value will not be pushed to;