summaryrefslogtreecommitdiff
path: root/Documentation/git-config.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-config.txt')
-rw-r--r--Documentation/git-config.txt239
1 files changed, 239 insertions, 0 deletions
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
new file mode 100644
index 0000000..280ef20
--- /dev/null
+++ b/Documentation/git-config.txt
@@ -0,0 +1,239 @@
+git-config(1)
+=============
+
+NAME
+----
+git-config - Get and set repository or global options
+
+
+SYNOPSIS
+--------
+[verse]
+'git-config' [--system | --global] [type] name [value [value_regex]]
+'git-config' [--system | --global] [type] --add name value
+'git-config' [--system | --global] [type] --replace-all name [value [value_regex]]
+'git-config' [--system | --global] [type] --get name [value_regex]
+'git-config' [--system | --global] [type] --get-all name [value_regex]
+'git-config' [--system | --global] [type] --unset name [value_regex]
+'git-config' [--system | --global] [type] --unset-all name [value_regex]
+'git-config' [--system | --global] [type] --rename-section old_name new_name
+'git-config' [--system | --global] [type] --remove-section name
+'git-config' [--system | --global] -l | --list
+
+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 EXAMPLES).
+
+The type specifier can be either '--int' or '--bool', which will make
+'git-config' ensure that the variable(s) are of the given type and
+convert the value to the canonical form (simple decimal number for int,
+a "true" or "false" string for bool). If no type specifier is passed,
+no checks or transformations are performed on the value.
+
+This command will fail if:
+
+. The .git/config file is invalid,
+. Can not write to .git/config,
+. no section was provided,
+. the section or key is invalid,
+. you try to unset an option which does not exist,
+. you try to unset/set an option for which multiple lines match, or
+. you use --global option without $HOME being properly set.
+
+
+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.
+
+--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 error code 2 if multiple key values were found.
+
+--get-all::
+ Like get, but does not fail if the number of values for the key
+ is not exactly one.
+
+--get-regexp::
+ Like --get-all, but interprets the name as a regular expression.
+
+--global::
+ Use global ~/.gitconfig file rather than the repository .git/config.
+
+--system::
+ Use system-wide $(prefix)/etc/gitconfig rather than the repository
+ .git/config.
+
+--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.
+
+--bool::
+ git-config will ensure that the output is "true" or "false"
+
+--int::
+ git-config will ensure that the output is a simple
+ decimal number. An optional value suffix of 'k', 'm', or 'g'
+ in the config file will cause the value to be multiplied
+ by 1024, 1048576, or 1073741824 prior to output.
+
+
+ENVIRONMENT
+-----------
+
+GIT_CONFIG::
+ Take the configuration from the given file instead of .git/config.
+ Using the "--global" option forces this to ~/.gitconfig.
+
+GIT_CONFIG_LOCAL::
+ Currently the same as $GIT_CONFIG; when Git will support global
+ configuration files, this will cause it to take the configuration
+ from the global configuration file in addition to the given file.
+
+
+EXAMPLE
+-------
+
+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/gnu-diff -u"
+ renames = true
+
+ ; Proxy settings
+ [core]
+ gitproxy="ssh" for "ssh://kernel.org/"
+ gitproxy="proxy-command" for kernel.org
+ gitproxy="myprotocol-command" for "my://"
+ gitproxy=default-proxy ; for all the rest
+
+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 dangerous, 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 core.gitproxy '"proxy" for example.com'
+------------
+
+
+include::config.txt[]
+
+
+Author
+------
+Written by Johannes Schindelin <Johannes.Schindelin@gmx.de>
+
+Documentation
+--------------
+Documentation by Johannes Schindelin, Petr Baudis and the git-list <git@vger.kernel.org>.
+
+GIT
+---
+Part of the gitlink:git[7] suite
+