From c8bae7493d2f2910b57f13ded012e86bdcfb0532 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 16:47:53 +0200 Subject: Adding upstream version 1:2.39.2. Signed-off-by: Daniel Baumann --- Documentation/git-config.txt | 592 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 592 insertions(+) create mode 100644 Documentation/git-config.txt (limited to 'Documentation/git-config.txt') diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt new file mode 100644 index 0000000..7a2bcb2 --- /dev/null +++ b/Documentation/git-config.txt @@ -0,0 +1,592 @@ +git-config(1) +============= + +NAME +---- +git-config - Get and set repository or global options + + +SYNOPSIS +-------- +[verse] +'git config' [] [--type=] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] [ []] +'git config' [] [--type=] --add +'git config' [] [--type=] [--fixed-value] --replace-all [] +'git config' [] [--type=] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get [] +'git config' [] [--type=] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all [] +'git config' [] [--type=] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp [] +'git config' [] [--type=] [-z|--null] --get-urlmatch +'git config' [] [--fixed-value] --unset [] +'git config' [] [--fixed-value] --unset-all [] +'git config' [] --rename-section +'git config' [] --remove-section +'git config' [] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list +'git config' [] --get-color [] +'git config' [] --get-colorbool [] +'git config' [] -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 `value-pattern` (which is an extended regular expression, +unless the `--fixed-value` option is given) needs to be given. Only the +existing values that match the pattern are updated or unset. If +you want to handle the lines that do *not* match the pattern, just +prepend a single exclamation mark in front (see also <>), +but note that this only works when the `--fixed-value` option is not +in use. + +The `--type=` option instructs 'git config' to ensure that incoming and +outgoing values are canonicalize-able under the given . If no +`--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 ` can be used to tell the command to read from only +that location (see <>). + +When writing, the new value is written to the repository local +configuration file by default, and options `--system`, `--global`, +`--worktree`, `--file ` 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. + +A list of all available configuration variables can be obtained using the +`git help --config` command. + +[[OPTIONS]] +OPTIONS +------- + +--replace-all:: + Default behavior is to replace at most one line. This replaces + all lines matching the key (and optionally the `value-pattern`). + +--add:: + Adds a new line to the option without altering any existing + values. This is the same as providing '^$' as the `value-pattern` + 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 :: + When given a two-part name section.key, the value for + section..key whose 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 <>. + +--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 <>. + +--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 <>. + +--worktree:: + Similar to `--local` except that `$GIT_DIR/config.worktree` is + read from or written to if `extensions.worktreeConfig` is + enabled. If not it's the same as `--local`. Note that `$GIT_DIR` + is equal to `$GIT_COMMON_DIR` for the main working tree, but is of + the form `$GIT_DIR/worktrees//` for other working trees. See + linkgit:git-worktree[1] to learn how to enable + `extensions.worktreeConfig`. + +-f :: +--file :: + For writing options: write to the specified file rather than the + repository `.git/config`. ++ +For reading options: read only from the specified file rather than from all +available files. ++ +See also <>. + +--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. + +--fixed-value:: + When used with the `value-pattern` argument, treat `value-pattern` as + an exact string instead of a regular expression. This will restrict + the name/value pairs that are matched to only those where the value + is exactly equal to the `value-pattern`. + +--type :: + 'git config' will ensure that any input or output is valid under the given + type constraint(s), and will canonicalize outgoing values in ``'s + canonical form. ++ +Valid ``'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=` or `--`. + +-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). + +--show-scope:: + Similar to `--show-origin` in that it augments the output of + all queried config options with the scope of that value + (worktree, local, global, system, command). + +--get-colorbool []:: + + Find the color setting for `` (e.g. `color.diff`) and output + "true" or "false". `` should be either "true" or + "false", and is taken into account when configuration says + "auto". If `` 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 []:: + + 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=]` 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 :: + When using `--get`, and the requested variable is not found, behave as if + 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 +----- + +By default, 'git config' will read configuration options from multiple +files: + +$(prefix)/etc/gitconfig:: + System-wide configuration file. + +$XDG_CONFIG_HOME/git/config:: +~/.gitconfig:: + User-specific configuration files. When the XDG_CONFIG_HOME environment + variable is not set or empty, $HOME/.config/ is used as + $XDG_CONFIG_HOME. ++ +These are also called "global" configuration files. If both files exist, both +files are read in the order given above. + +$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. + +You may also provide additional configuration parameters when running any +git command by using the `-c` option. See linkgit:git[1] for details. + +Options will be read from all of these files that are available. If the +global or the system-wide configuration files are missing or unreadable they +will be ignored. If the repository configuration file is missing or unreadable, +'git config' will exit with a non-zero error code. An error message is produced +if the file is unreadable, but not if it is missing. + +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. + +By default, options are only written 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 limit which configuration sources are read from or written to by +specifying the path of a file with the `--file` option, or by specifying a +configuration scope with `--system`, `--global`, `--local`, or `--worktree`. +For more, see <> above. + +[[SCOPES]] +SCOPES +------ + +Each configuration source falls within a configuration scope. The scopes +are: + +system:: + $(prefix)/etc/gitconfig + +global:: + $XDG_CONFIG_HOME/git/config ++ +~/.gitconfig + +local:: + $GIT_DIR/config + +worktree:: + $GIT_DIR/config.worktree + +command:: + GIT_CONFIG_{COUNT,KEY,VALUE} environment variables (see <> + below) ++ +the `-c` option + +With the exception of 'command', each scope corresponds to a command line +option: `--system`, `--global`, `--local`, `--worktree`. + +When reading options, specifying a scope will only read options from the +files within that scope. When writing options, specifying a scope will write +to the files within that scope (instead of the repository specific +configuration file). See <> above for a complete description. + +Most configuration options are respected regardless of the scope it is +defined in, but some options are only respected in certain scopes. See the +respective option's documentation for the full details. + +Protected configuration +~~~~~~~~~~~~~~~~~~~~~~~ + +Protected configuration refers to the 'system', 'global', and 'command' scopes. +For security reasons, certain options are only respected when they are +specified in protected configuration, and ignored otherwise. + +Git treats these scopes as if they are controlled by the user or a trusted +administrator. This is because an attacker who controls these scopes can do +substantial harm without using Git, so it is assumed that the user's environment +protects these scopes against attackers. + +[[ENVIRONMENT]] +ENVIRONMENT +----------- + +GIT_CONFIG_GLOBAL:: +GIT_CONFIG_SYSTEM:: + Take the configuration from the given files instead from global or + system-level configuration. See linkgit:git[1] for details. + +GIT_CONFIG_NOSYSTEM:: + Whether to skip reading settings from the system-wide + $(prefix)/etc/gitconfig file. See linkgit:git[1] for details. + +See also <>. + +GIT_CONFIG_COUNT:: +GIT_CONFIG_KEY_:: +GIT_CONFIG_VALUE_:: + If GIT_CONFIG_COUNT is set to a positive number, all environment pairs + GIT_CONFIG_KEY_ and GIT_CONFIG_VALUE_ up to that number will be + added to the process's runtime configuration. The config pairs are + zero-indexed. Any missing key or value is treated as an error. An empty + GIT_CONFIG_COUNT is treated the same as GIT_CONFIG_COUNT=0, namely no + pairs are processed. These environment variables will override values + in configuration files, but will be overridden by any explicit options + passed via `git -c`. ++ +This is useful for cases where you want to spawn multiple git commands +with a common configuration but cannot depend on a configuration file, +for example when writing scripts. + +GIT_CONFIG:: + If no `--file` option is provided to `git config`, use the file + given by `GIT_CONFIG` as if it were provided via `--file`. This + variable has no effect on other Git commands, and is mostly for + historical compatibility; there is generally no reason to use it + instead of the `--file` option. + +[[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 -- cgit v1.2.3