git-format-patch.txt: document --no-notes option
[gitweb.git] / Documentation / config.txt
index 966e82e851ee2639b4935edb7c61f528d84deb15..d87846faa6c3ffad7cba97fe7348ef97e0112899 100644 (file)
@@ -2,8 +2,9 @@ CONFIGURATION FILE
 ------------------
 
 The Git configuration file contains a number of variables that affect
-the Git commands' behavior. The `.git/config` file in each repository
-is used to store the configuration for that repository, and
+the Git commands' behavior. The files `.git/config` and optionally
+`config.worktree` (see `extensions.worktreeConfig` below) in each
+repository are used to store the configuration for that repository, and
 `$HOME/.gitconfig` is used to store a per-user configuration as
 fallback values for the `.git/config` file. The file `/etc/gitconfig`
 can be used to store a system-wide default configuration.
@@ -419,271 +420,20 @@ include::config/stash.txt[]
 
 include::config/submodule.txt[]
 
-tag.forceSignAnnotated::
-       A boolean to specify whether annotated tags created should be GPG signed.
-       If `--annotate` is specified on the command line, it takes
-       precedence over this option.
-
-tag.sort::
-       This variable controls the sort ordering of tags when displayed by
-       linkgit:git-tag[1]. Without the "--sort=<value>" option provided, the
-       value of this variable will be used as the default.
-
-tar.umask::
-       This variable can be used to restrict the permission bits of
-       tar archive entries.  The default is 0002, which turns off the
-       world write bit.  The special value "user" indicates that the
-       archiving user's umask will be used instead.  See umask(2) and
-       linkgit:git-archive[1].
-
-transfer.fsckObjects::
-       When `fetch.fsckObjects` or `receive.fsckObjects` are
-       not set, the value of this variable is used instead.
-       Defaults to false.
-+
-When set, the fetch or receive will abort in the case of a malformed
-object or a link to a nonexistent object. In addition, various other
-issues are checked for, including legacy issues (see `fsck.<msg-id>`),
-and potential security issues like the existence of a `.GIT` directory
-or a malicious `.gitmodules` file (see the release notes for v2.2.1
-and v2.17.1 for details). Other sanity and security checks may be
-added in future releases.
-+
-On the receiving side, failing fsckObjects will make those objects
-unreachable, see "QUARANTINE ENVIRONMENT" in
-linkgit:git-receive-pack[1]. On the fetch side, malformed objects will
-instead be left unreferenced in the repository.
-+
-Due to the non-quarantine nature of the `fetch.fsckObjects`
-implementation it can not be relied upon to leave the object store
-clean like `receive.fsckObjects` can.
-+
-As objects are unpacked they're written to the object store, so there
-can be cases where malicious objects get introduced even though the
-"fetch" failed, only to have a subsequent "fetch" succeed because only
-new incoming objects are checked, not those that have already been
-written to the object store. That difference in behavior should not be
-relied upon. In the future, such objects may be quarantined for
-"fetch" as well.
-+
-For now, the paranoid need to find some way to emulate the quarantine
-environment if they'd like the same protection as "push". E.g. in the
-case of an internal mirror do the mirroring in two steps, one to fetch
-the untrusted objects, and then do a second "push" (which will use the
-quarantine) to another internal repo, and have internal clients
-consume this pushed-to repository, or embargo internal fetches and
-only allow them once a full "fsck" has run (and no new fetches have
-happened in the meantime).
-
-transfer.hideRefs::
-       String(s) `receive-pack` and `upload-pack` use to decide which
-       refs to omit from their initial advertisements.  Use more than
-       one definition to specify multiple prefix strings. A ref that is
-       under the hierarchies listed in the value of this variable is
-       excluded, and is hidden when responding to `git push` or `git
-       fetch`.  See `receive.hideRefs` and `uploadpack.hideRefs` for
-       program-specific versions of this config.
-+
-You may also include a `!` in front of the ref name to negate the entry,
-explicitly exposing it, even if an earlier entry marked it as hidden.
-If you have multiple hideRefs values, later entries override earlier ones
-(and entries in more-specific config files override less-specific ones).
-+
-If a namespace is in use, the namespace prefix is stripped from each
-reference before it is matched against `transfer.hiderefs` patterns.
-For example, if `refs/heads/master` is specified in `transfer.hideRefs` and
-the current namespace is `foo`, then `refs/namespaces/foo/refs/heads/master`
-is omitted from the advertisements but `refs/heads/master` and
-`refs/namespaces/bar/refs/heads/master` are still advertised as so-called
-"have" lines. In order to match refs before stripping, add a `^` in front of
-the ref name. If you combine `!` and `^`, `!` must be specified first.
-+
-Even if you hide refs, a client may still be able to steal the target
-objects via the techniques described in the "SECURITY" section of the
-linkgit:gitnamespaces[7] man page; it's best to keep private data in a
-separate repository.
-
-transfer.unpackLimit::
-       When `fetch.unpackLimit` or `receive.unpackLimit` are
-       not set, the value of this variable is used instead.
-       The default value is 100.
-
-uploadarchive.allowUnreachable::
-       If true, allow clients to use `git archive --remote` to request
-       any tree, whether reachable from the ref tips or not. See the
-       discussion in the "SECURITY" section of
-       linkgit:git-upload-archive[1] for more details. Defaults to
-       `false`.
-
-uploadpack.hideRefs::
-       This variable is the same as `transfer.hideRefs`, but applies
-       only to `upload-pack` (and so affects only fetches, not pushes).
-       An attempt to fetch a hidden ref by `git fetch` will fail.  See
-       also `uploadpack.allowTipSHA1InWant`.
-
-uploadpack.allowTipSHA1InWant::
-       When `uploadpack.hideRefs` is in effect, allow `upload-pack`
-       to accept a fetch request that asks for an object at the tip
-       of a hidden ref (by default, such a request is rejected).
-       See also `uploadpack.hideRefs`.  Even if this is false, a client
-       may be able to steal objects via the techniques described in the
-       "SECURITY" section of the linkgit:gitnamespaces[7] man page; it's
-       best to keep private data in a separate repository.
-
-uploadpack.allowReachableSHA1InWant::
-       Allow `upload-pack` to accept a fetch request that asks for an
-       object that is reachable from any ref tip. However, note that
-       calculating object reachability is computationally expensive.
-       Defaults to `false`.  Even if this is false, a client may be able
-       to steal objects via the techniques described in the "SECURITY"
-       section of the linkgit:gitnamespaces[7] man page; it's best to
-       keep private data in a separate repository.
-
-uploadpack.allowAnySHA1InWant::
-       Allow `upload-pack` to accept a fetch request that asks for any
-       object at all.
-       Defaults to `false`.
-
-uploadpack.keepAlive::
-       When `upload-pack` has started `pack-objects`, there may be a
-       quiet period while `pack-objects` prepares the pack. Normally
-       it would output progress information, but if `--quiet` was used
-       for the fetch, `pack-objects` will output nothing at all until
-       the pack data begins. Some clients and networks may consider
-       the server to be hung and give up. Setting this option instructs
-       `upload-pack` to send an empty keepalive packet every
-       `uploadpack.keepAlive` seconds. Setting this option to 0
-       disables keepalive packets entirely. The default is 5 seconds.
-
-uploadpack.packObjectsHook::
-       If this option is set, when `upload-pack` would run
-       `git pack-objects` to create a packfile for a client, it will
-       run this shell command instead.  The `pack-objects` command and
-       arguments it _would_ have run (including the `git pack-objects`
-       at the beginning) are appended to the shell command. The stdin
-       and stdout of the hook are treated as if `pack-objects` itself
-       was run. I.e., `upload-pack` will feed input intended for
-       `pack-objects` to the hook, and expects a completed packfile on
-       stdout.
-+
-Note that this configuration variable is ignored if it is seen in the
-repository-level config (this is a safety measure against fetching from
-untrusted repositories).
-
-uploadpack.allowFilter::
-       If this option is set, `upload-pack` will support partial
-       clone and partial fetch object filtering.
-
-uploadpack.allowRefInWant::
-       If this option is set, `upload-pack` will support the `ref-in-want`
-       feature of the protocol version 2 `fetch` command.  This feature
-       is intended for the benefit of load-balanced servers which may
-       not have the same view of what OIDs their refs point to due to
-       replication delay.
-
-url.<base>.insteadOf::
-       Any URL that starts with this value will be rewritten to
-       start, instead, with <base>. In cases where some site serves a
-       large number of repositories, and serves them with multiple
-       access methods, and some users need to use different access
-       methods, this feature allows people to specify any of the
-       equivalent URLs and have Git automatically rewrite the URL to
-       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;
-       instead, it will be rewritten to start with <base>, and the
-       resulting URL will be pushed to. In cases where some site serves
-       a large number of repositories, and serves them with multiple
-       access methods, some of which do not allow push, this feature
-       allows people to specify a pull-only URL and have Git
-       automatically use an appropriate URL to push, even for a
-       never-before-seen repository on the site.  When more than one
-       pushInsteadOf strings match a given URL, the longest match is
-       used.  If a remote has an explicit pushurl, Git will ignore this
-       setting for that remote.
-
-user.email::
-       Your email address to be recorded in any newly created commits.
-       Can be overridden by the `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_EMAIL`, and
-       `EMAIL` environment variables.  See linkgit:git-commit-tree[1].
-
-user.name::
-       Your full name to be recorded in any newly created commits.
-       Can be overridden by the `GIT_AUTHOR_NAME` and `GIT_COMMITTER_NAME`
-       environment variables.  See linkgit:git-commit-tree[1].
-
-user.useConfigOnly::
-       Instruct Git to avoid trying to guess defaults for `user.email`
-       and `user.name`, and instead retrieve the values only from the
-       configuration. For example, if you have multiple email addresses
-       and would like to use a different one for each repository, then
-       with this configuration option set to `true` in the global config
-       along with a name, Git will prompt you to set up an email before
-       making new commits in a newly cloned repository.
-       Defaults to `false`.
-
-user.signingKey::
-       If linkgit:git-tag[1] or linkgit:git-commit[1] is not selecting the
-       key you want it to automatically when creating a signed tag or
-       commit, you can override the default selection with this variable.
-       This option is passed unchanged to gpg's --local-user parameter,
-       so you may specify a key using any method that gpg supports.
-
-versionsort.prereleaseSuffix (deprecated)::
-       Deprecated alias for `versionsort.suffix`.  Ignored if
-       `versionsort.suffix` is set.
-
-versionsort.suffix::
-       Even when version sort is used in linkgit:git-tag[1], tagnames
-       with the same base version but different suffixes are still sorted
-       lexicographically, resulting e.g. in prerelease tags appearing
-       after the main release (e.g. "1.0-rc1" after "1.0").  This
-       variable can be specified to determine the sorting order of tags
-       with different suffixes.
-+
-By specifying a single suffix in this variable, any tagname containing
-that suffix will appear before the corresponding main release.  E.g. if
-the variable is set to "-rc", then all "1.0-rcX" tags will appear before
-"1.0".  If specified multiple times, once per suffix, then the order of
-suffixes in the configuration will determine the sorting order of tagnames
-with those suffixes.  E.g. if "-pre" appears before "-rc" in the
-configuration, then all "1.0-preX" tags will be listed before any
-"1.0-rcX" tags.  The placement of the main release tag relative to tags
-with various suffixes can be determined by specifying the empty suffix
-among those other suffixes.  E.g. if the suffixes "-rc", "", "-ck" and
-"-bfs" appear in the configuration in this order, then all "v4.8-rcX" tags
-are listed first, followed by "v4.8", then "v4.8-ckX" and finally
-"v4.8-bfsX".
-+
-If more than one suffixes match the same tagname, then that tagname will
-be sorted according to the suffix which starts at the earliest position in
-the tagname.  If more than one different matching suffixes start at
-that earliest position, then that tagname will be sorted according to the
-longest of those suffixes.
-The sorting order between different suffixes is undefined if they are
-in multiple config files.
-
-web.browser::
-       Specify a web browser that may be used by some commands.
-       Currently only linkgit:git-instaweb[1] and linkgit:git-help[1]
-       may use it.
-
-worktree.guessRemote::
-       With `add`, if no branch argument, and neither of `-b` nor
-       `-B` nor `--detach` are given, the command defaults to
-       creating a new branch from HEAD.  If `worktree.guessRemote` is
-       set to true, `worktree add` tries to find a remote-tracking
-       branch whose name uniquely matches the new branch name.  If
-       such a branch exists, it is checked out and set as "upstream"
-       for the new branch.  If no such match can be found, it falls
-       back to creating a new branch from the current HEAD.
+include::config/tag.txt[]
+
+include::config/transfer.txt[]
+
+include::config/uploadarchive.txt[]
+
+include::config/uploadpack.txt[]
+
+include::config/url.txt[]
+
+include::config/user.txt[]
+
+include::config/versionsort.txt[]
+
+include::config/web.txt[]
+
+include::config/worktree.txt[]