merge(third_party/git): Merge squashed git subtree at v2.23.0
Merge commit '1b593e1ea4' as 'third_party/git'
This commit is contained in:
Vincent Ambo
commit
7ef0d62730
3629 changed files with 1139935 additions and 0 deletions
493
third_party/git/Documentation/git-config.txt
vendored
Normal file
493
third_party/git/Documentation/git-config.txt
vendored
Normal file
|
|
@ -0,0 +1,493 @@
|
|||
git-config(1)
|
||||
=============
|
||||
|
||||
NAME
|
||||
----
|
||||
git-config - Get and set repository or global options
|
||||
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
[verse]
|
||||
'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] name [value [value_regex]]
|
||||
'git config' [<file-option>] [--type=<type>] --add name value
|
||||
'git config' [<file-option>] [--type=<type>] --replace-all name value [value_regex]
|
||||
'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] --get name [value_regex]
|
||||
'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] --get-all name [value_regex]
|
||||
'git config' [<file-option>] [--type=<type>] [--show-origin] [-z|--null] [--name-only] --get-regexp name_regex [value_regex]
|
||||
'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL
|
||||
'git config' [<file-option>] --unset name [value_regex]
|
||||
'git config' [<file-option>] --unset-all name [value_regex]
|
||||
'git config' [<file-option>] --rename-section old_name new_name
|
||||
'git config' [<file-option>] --remove-section name
|
||||
'git config' [<file-option>] [--show-origin] [-z|--null] [--name-only] -l | --list
|
||||
'git config' [<file-option>] --get-color name [default]
|
||||
'git config' [<file-option>] --get-colorbool name [stdout-is-tty]
|
||||
'git config' [<file-option>] -e | --edit
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
You can query/set/replace/unset options with this command. The name is
|
||||
actually the section and the key separated by a dot, and the value will be
|
||||
escaped.
|
||||
|
||||
Multiple lines can be added to an option by using the `--add` option.
|
||||
If you want to update or unset an option which can occur on multiple
|
||||
lines, a POSIX regexp `value_regex` needs to be given. Only the
|
||||
existing values that match the regexp are updated or unset. If
|
||||
you want to handle the lines that do *not* match the regex, just
|
||||
prepend a single exclamation mark in front (see also <<EXAMPLES>>).
|
||||
|
||||
The `--type=<type>` option instructs 'git config' to ensure that incoming and
|
||||
outgoing values are canonicalize-able under the given <type>. If no
|
||||
`--type=<type>` is given, no canonicalization will be performed. Callers may
|
||||
unset an existing `--type` specifier with `--no-type`.
|
||||
|
||||
When reading, the values are read from the system, global and
|
||||
repository local configuration files by default, and options
|
||||
`--system`, `--global`, `--local`, `--worktree` and
|
||||
`--file <filename>` can be used to tell the command to read from only
|
||||
that location (see <<FILES>>).
|
||||
|
||||
When writing, the new value is written to the repository local
|
||||
configuration file by default, and options `--system`, `--global`,
|
||||
`--worktree`, `--file <filename>` can be used to tell the command to
|
||||
write to that location (you can say `--local` but that is the
|
||||
default).
|
||||
|
||||
This command will fail with non-zero status upon error. Some exit
|
||||
codes are:
|
||||
|
||||
- The section or key is invalid (ret=1),
|
||||
- no section or name was provided (ret=2),
|
||||
- the config file is invalid (ret=3),
|
||||
- the config file cannot be written (ret=4),
|
||||
- you try to unset an option which does not exist (ret=5),
|
||||
- you try to unset/set an option for which multiple lines match (ret=5), or
|
||||
- you try to use an invalid regexp (ret=6).
|
||||
|
||||
On success, the command returns the exit code 0.
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
|
||||
--replace-all::
|
||||
Default behavior is to replace at most one line. This replaces
|
||||
all lines matching the key (and optionally the value_regex).
|
||||
|
||||
--add::
|
||||
Adds a new line to the option without altering any existing
|
||||
values. This is the same as providing '^$' as the value_regex
|
||||
in `--replace-all`.
|
||||
|
||||
--get::
|
||||
Get the value for a given key (optionally filtered by a regex
|
||||
matching the value). Returns error code 1 if the key was not
|
||||
found and the last value if multiple key values were found.
|
||||
|
||||
--get-all::
|
||||
Like get, but returns all values for a multi-valued key.
|
||||
|
||||
--get-regexp::
|
||||
Like --get-all, but interprets the name as a regular expression and
|
||||
writes out the key names. Regular expression matching is currently
|
||||
case-sensitive and done against a canonicalized version of the key
|
||||
in which section and variable names are lowercased, but subsection
|
||||
names are not.
|
||||
|
||||
--get-urlmatch name URL::
|
||||
When given a two-part name section.key, the value for
|
||||
section.<url>.key whose <url> part matches the best to the
|
||||
given URL is returned (if no such key exists, the value for
|
||||
section.key is used as a fallback). When given just the
|
||||
section as name, do so for all the keys in the section and
|
||||
list them. Returns error code 1 if no value is found.
|
||||
|
||||
--global::
|
||||
For writing options: write to global `~/.gitconfig` file
|
||||
rather than the repository `.git/config`, write to
|
||||
`$XDG_CONFIG_HOME/git/config` file if this file exists and the
|
||||
`~/.gitconfig` file doesn't.
|
||||
+
|
||||
For reading options: read only from global `~/.gitconfig` and from
|
||||
`$XDG_CONFIG_HOME/git/config` rather than from all available files.
|
||||
+
|
||||
See also <<FILES>>.
|
||||
|
||||
--system::
|
||||
For writing options: write to system-wide
|
||||
`$(prefix)/etc/gitconfig` rather than the repository
|
||||
`.git/config`.
|
||||
+
|
||||
For reading options: read only from system-wide `$(prefix)/etc/gitconfig`
|
||||
rather than from all available files.
|
||||
+
|
||||
See also <<FILES>>.
|
||||
|
||||
--local::
|
||||
For writing options: write to the repository `.git/config` file.
|
||||
This is the default behavior.
|
||||
+
|
||||
For reading options: read only from the repository `.git/config` rather than
|
||||
from all available files.
|
||||
+
|
||||
See also <<FILES>>.
|
||||
|
||||
--worktree::
|
||||
Similar to `--local` except that `.git/config.worktree` is
|
||||
read from or written to if `extensions.worktreeConfig` is
|
||||
present. If not it's the same as `--local`.
|
||||
|
||||
-f config-file::
|
||||
--file config-file::
|
||||
Use the given config file instead of the one specified by GIT_CONFIG.
|
||||
|
||||
--blob blob::
|
||||
Similar to `--file` but use the given blob instead of a file. E.g.
|
||||
you can use 'master:.gitmodules' to read values from the file
|
||||
'.gitmodules' in the master branch. See "SPECIFYING REVISIONS"
|
||||
section in linkgit:gitrevisions[7] for a more complete list of
|
||||
ways to spell blob names.
|
||||
|
||||
--remove-section::
|
||||
Remove the given section from the configuration file.
|
||||
|
||||
--rename-section::
|
||||
Rename the given section to a new name.
|
||||
|
||||
--unset::
|
||||
Remove the line matching the key from config file.
|
||||
|
||||
--unset-all::
|
||||
Remove all lines matching the key from config file.
|
||||
|
||||
-l::
|
||||
--list::
|
||||
List all variables set in config file, along with their values.
|
||||
|
||||
--type <type>::
|
||||
'git config' will ensure that any input or output is valid under the given
|
||||
type constraint(s), and will canonicalize outgoing values in `<type>`'s
|
||||
canonical form.
|
||||
+
|
||||
Valid `<type>`'s include:
|
||||
+
|
||||
- 'bool': canonicalize values as either "true" or "false".
|
||||
- 'int': canonicalize values as simple decimal numbers. An optional suffix of
|
||||
'k', 'm', or 'g' will cause the value to be multiplied by 1024, 1048576, or
|
||||
1073741824 upon input.
|
||||
- 'bool-or-int': canonicalize according to either 'bool' or 'int', as described
|
||||
above.
|
||||
- 'path': canonicalize by adding a leading `~` to the value of `$HOME` and
|
||||
`~user` to the home directory for the specified user. This specifier has no
|
||||
effect when setting the value (but you can use `git config section.variable
|
||||
~/` from the command line to let your shell do the expansion.)
|
||||
- 'expiry-date': canonicalize by converting from a fixed or relative date-string
|
||||
to a timestamp. This specifier has no effect when setting the value.
|
||||
- 'color': When getting a value, canonicalize by converting to an ANSI color
|
||||
escape sequence. When setting a value, a sanity-check is performed to ensure
|
||||
that the given value is canonicalize-able as an ANSI color, but it is written
|
||||
as-is.
|
||||
+
|
||||
|
||||
--bool::
|
||||
--int::
|
||||
--bool-or-int::
|
||||
--path::
|
||||
--expiry-date::
|
||||
Historical options for selecting a type specifier. Prefer instead `--type`
|
||||
(see above).
|
||||
|
||||
--no-type::
|
||||
Un-sets the previously set type specifier (if one was previously set). This
|
||||
option requests that 'git config' not canonicalize the retrieved variable.
|
||||
`--no-type` has no effect without `--type=<type>` or `--<type>`.
|
||||
|
||||
-z::
|
||||
--null::
|
||||
For all options that output values and/or keys, always
|
||||
end values with the null character (instead of a
|
||||
newline). Use newline instead as a delimiter between
|
||||
key and value. This allows for secure parsing of the
|
||||
output without getting confused e.g. by values that
|
||||
contain line breaks.
|
||||
|
||||
--name-only::
|
||||
Output only the names of config variables for `--list` or
|
||||
`--get-regexp`.
|
||||
|
||||
--show-origin::
|
||||
Augment the output of all queried config options with the
|
||||
origin type (file, standard input, blob, command line) and
|
||||
the actual origin (config file path, ref, or blob id if
|
||||
applicable).
|
||||
|
||||
--get-colorbool name [stdout-is-tty]::
|
||||
|
||||
Find the color setting for `name` (e.g. `color.diff`) and output
|
||||
"true" or "false". `stdout-is-tty` should be either "true" or
|
||||
"false", and is taken into account when configuration says
|
||||
"auto". If `stdout-is-tty` is missing, then checks the standard
|
||||
output of the command itself, and exits with status 0 if color
|
||||
is to be used, or exits with status 1 otherwise.
|
||||
When the color setting for `name` is undefined, the command uses
|
||||
`color.ui` as fallback.
|
||||
|
||||
--get-color name [default]::
|
||||
|
||||
Find the color configured for `name` (e.g. `color.diff.new`) and
|
||||
output it as the ANSI color escape sequence to the standard
|
||||
output. The optional `default` parameter is used instead, if
|
||||
there is no color configured for `name`.
|
||||
+
|
||||
`--type=color [--default=<default>]` is preferred over `--get-color`
|
||||
(but note that `--get-color` will omit the trailing newline printed by
|
||||
`--type=color`).
|
||||
|
||||
-e::
|
||||
--edit::
|
||||
Opens an editor to modify the specified config file; either
|
||||
`--system`, `--global`, or repository (default).
|
||||
|
||||
--[no-]includes::
|
||||
Respect `include.*` directives in config files when looking up
|
||||
values. Defaults to `off` when a specific file is given (e.g.,
|
||||
using `--file`, `--global`, etc) and `on` when searching all
|
||||
config files.
|
||||
|
||||
--default <value>::
|
||||
When using `--get`, and the requested variable is not found, behave as if
|
||||
<value> were the value assigned to the that variable.
|
||||
|
||||
CONFIGURATION
|
||||
-------------
|
||||
`pager.config` is only respected when listing configuration, i.e., when
|
||||
using `--list` or any of the `--get-*` which may return multiple results.
|
||||
The default is to use a pager.
|
||||
|
||||
[[FILES]]
|
||||
FILES
|
||||
-----
|
||||
|
||||
If not set explicitly with `--file`, there are four files where
|
||||
'git config' will search for configuration options:
|
||||
|
||||
$(prefix)/etc/gitconfig::
|
||||
System-wide configuration file.
|
||||
|
||||
$XDG_CONFIG_HOME/git/config::
|
||||
Second user-specific configuration file. If $XDG_CONFIG_HOME is not set
|
||||
or empty, `$HOME/.config/git/config` will be used. Any single-valued
|
||||
variable set in this file will be overwritten by whatever is in
|
||||
`~/.gitconfig`. It is a good idea not to create this file if
|
||||
you sometimes use older versions of Git, as support for this
|
||||
file was added fairly recently.
|
||||
|
||||
~/.gitconfig::
|
||||
User-specific configuration file. Also called "global"
|
||||
configuration file.
|
||||
|
||||
$GIT_DIR/config::
|
||||
Repository specific configuration file.
|
||||
|
||||
$GIT_DIR/config.worktree::
|
||||
This is optional and is only searched when
|
||||
`extensions.worktreeConfig` is present in $GIT_DIR/config.
|
||||
|
||||
If no further options are given, all reading options will read all of these
|
||||
files that are available. If the global or the system-wide configuration
|
||||
file are not available they will be ignored. If the repository configuration
|
||||
file is not available or readable, 'git config' will exit with a non-zero
|
||||
error code. However, in neither case will an error message be issued.
|
||||
|
||||
The files are read in the order given above, with last value found taking
|
||||
precedence over values read earlier. When multiple values are taken then all
|
||||
values of a key from all files will be used.
|
||||
|
||||
You may override individual configuration parameters when running any git
|
||||
command by using the `-c` option. See linkgit:git[1] for details.
|
||||
|
||||
All writing options will per default write to the repository specific
|
||||
configuration file. Note that this also affects options like `--replace-all`
|
||||
and `--unset`. *'git config' will only ever change one file at a time*.
|
||||
|
||||
You can override these rules either by command-line options or by environment
|
||||
variables. The `--global`, `--system` and `--worktree` options will limit
|
||||
the file used to the global, system-wide or per-worktree file respectively.
|
||||
The `GIT_CONFIG` environment variable has a similar effect, but you
|
||||
can specify any filename you want.
|
||||
|
||||
|
||||
ENVIRONMENT
|
||||
-----------
|
||||
|
||||
GIT_CONFIG::
|
||||
Take the configuration from the given file instead of .git/config.
|
||||
Using the "--global" option forces this to ~/.gitconfig. Using the
|
||||
"--system" option forces this to $(prefix)/etc/gitconfig.
|
||||
|
||||
GIT_CONFIG_NOSYSTEM::
|
||||
Whether to skip reading settings from the system-wide
|
||||
$(prefix)/etc/gitconfig file. See linkgit:git[1] for details.
|
||||
|
||||
See also <<FILES>>.
|
||||
|
||||
|
||||
[[EXAMPLES]]
|
||||
EXAMPLES
|
||||
--------
|
||||
|
||||
Given a .git/config like this:
|
||||
|
||||
#
|
||||
# This is the config file, and
|
||||
# a '#' or ';' character indicates
|
||||
# a comment
|
||||
#
|
||||
|
||||
; core variables
|
||||
[core]
|
||||
; Don't trust file modes
|
||||
filemode = false
|
||||
|
||||
; Our diff algorithm
|
||||
[diff]
|
||||
external = /usr/local/bin/diff-wrapper
|
||||
renames = true
|
||||
|
||||
; Proxy settings
|
||||
[core]
|
||||
gitproxy=proxy-command for kernel.org
|
||||
gitproxy=default-proxy ; for all the rest
|
||||
|
||||
; HTTP
|
||||
[http]
|
||||
sslVerify
|
||||
[http "https://weak.example.com"]
|
||||
sslVerify = false
|
||||
cookieFile = /tmp/cookie.txt
|
||||
|
||||
you can set the filemode to true with
|
||||
|
||||
------------
|
||||
% git config core.filemode true
|
||||
------------
|
||||
|
||||
The hypothetical proxy command entries actually have a postfix to discern
|
||||
what URL they apply to. Here is how to change the entry for kernel.org
|
||||
to "ssh".
|
||||
|
||||
------------
|
||||
% git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$'
|
||||
------------
|
||||
|
||||
This makes sure that only the key/value pair for kernel.org is replaced.
|
||||
|
||||
To delete the entry for renames, do
|
||||
|
||||
------------
|
||||
% git config --unset diff.renames
|
||||
------------
|
||||
|
||||
If you want to delete an entry for a multivar (like core.gitproxy above),
|
||||
you have to provide a regex matching the value of exactly one line.
|
||||
|
||||
To query the value for a given key, do
|
||||
|
||||
------------
|
||||
% git config --get core.filemode
|
||||
------------
|
||||
|
||||
or
|
||||
|
||||
------------
|
||||
% git config core.filemode
|
||||
------------
|
||||
|
||||
or, to query a multivar:
|
||||
|
||||
------------
|
||||
% git config --get core.gitproxy "for kernel.org$"
|
||||
------------
|
||||
|
||||
If you want to know all the values for a multivar, do:
|
||||
|
||||
------------
|
||||
% git config --get-all core.gitproxy
|
||||
------------
|
||||
|
||||
If you like to live dangerously, you can replace *all* core.gitproxy by a
|
||||
new one with
|
||||
|
||||
------------
|
||||
% git config --replace-all core.gitproxy ssh
|
||||
------------
|
||||
|
||||
However, if you really only want to replace the line for the default proxy,
|
||||
i.e. the one without a "for ..." postfix, do something like this:
|
||||
|
||||
------------
|
||||
% git config core.gitproxy ssh '! for '
|
||||
------------
|
||||
|
||||
To actually match only values with an exclamation mark, you have to
|
||||
|
||||
------------
|
||||
% git config section.key value '[!]'
|
||||
------------
|
||||
|
||||
To add a new proxy, without altering any of the existing ones, use
|
||||
|
||||
------------
|
||||
% git config --add core.gitproxy '"proxy-command" for example.com'
|
||||
------------
|
||||
|
||||
An example to use customized color from the configuration in your
|
||||
script:
|
||||
|
||||
------------
|
||||
#!/bin/sh
|
||||
WS=$(git config --get-color color.diff.whitespace "blue reverse")
|
||||
RESET=$(git config --get-color "" "reset")
|
||||
echo "${WS}your whitespace color or blue reverse${RESET}"
|
||||
------------
|
||||
|
||||
For URLs in `https://weak.example.com`, `http.sslVerify` is set to
|
||||
false, while it is set to `true` for all others:
|
||||
|
||||
------------
|
||||
% git config --type=bool --get-urlmatch http.sslverify https://good.example.com
|
||||
true
|
||||
% git config --type=bool --get-urlmatch http.sslverify https://weak.example.com
|
||||
false
|
||||
% git config --get-urlmatch http https://weak.example.com
|
||||
http.cookieFile /tmp/cookie.txt
|
||||
http.sslverify false
|
||||
------------
|
||||
|
||||
include::config.txt[]
|
||||
|
||||
BUGS
|
||||
----
|
||||
When using the deprecated `[section.subsection]` syntax, changing a value
|
||||
will result in adding a multi-line key instead of a change, if the subsection
|
||||
is given with at least one uppercase character. For example when the config
|
||||
looks like
|
||||
|
||||
--------
|
||||
[section.subsection]
|
||||
key = value1
|
||||
--------
|
||||
|
||||
and running `git config section.Subsection.key value2` will result in
|
||||
|
||||
--------
|
||||
[section.subsection]
|
||||
key = value1
|
||||
key = value2
|
||||
--------
|
||||
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the linkgit:git[1] suite
|
||||
Loading…
Add table
Add a link
Reference in a new issue