diff options
Diffstat (limited to 'third_party/git/Documentation/git-config.txt')
| -rw-r--r-- | third_party/git/Documentation/git-config.txt | 493 |
1 files changed, 0 insertions, 493 deletions
diff --git a/third_party/git/Documentation/git-config.txt b/third_party/git/Documentation/git-config.txt deleted file mode 100644 index ff9310f958..0000000000 --- a/third_party/git/Documentation/git-config.txt +++ /dev/null @@ -1,493 +0,0 @@ -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 |