Documentation/git-config.txt

   1 git-config(1)
   2 =============
   3
   4 NAME
   5 ----
   6 git-config - Get and set repository or global options
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git-config' [--system | --global] [type] name [value [value_regex]]
  13 'git-config' [--system | --global] [type] --add name value
  14 'git-config' [--system | --global] [type] --replace-all name [value [value_regex]]
  15 'git-config' [--system | --global] [type] --get name [value_regex]
  16 'git-config' [--system | --global] [type] --get-all name [value_regex]
  17 'git-config' [--system | --global] [type] --unset name [value_regex]
  18 'git-config' [--system | --global] [type] --unset-all name [value_regex]
  19 'git-config' [--system | --global] [type] --rename-section old_name new_name
  20 'git-config' [--system | --global] [type] --remove-section name
  21 'git-config' [--system | --global] -l | --list
  22
  23 DESCRIPTION
  24 -----------
  25 You can query/set/replace/unset options with this command. The name is
  26 actually the section and the key separated by a dot, and the value will be
  27 escaped.
  28
  29 Multiple lines can be added to an option by using the '--add' option.
  30 If you want to update or unset an option which can occur on multiple
  31 lines, a POSIX regexp `value_regex` needs to be given.  Only the
  32 existing values that match the regexp are updated or unset.  If
  33 you want to handle the lines that do *not* match the regex, just
  34 prepend a single exclamation mark in front (see EXAMPLES).
  35
  36 The type specifier can be either '--int' or '--bool', which will make
  37 'git-config' ensure that the variable(s) are of the given type and
  38 convert the value to the canonical form (simple decimal number for int,
  39 a "true" or "false" string for bool). If no type specifier is passed,
  40 no checks or transformations are performed on the value.
  41
  42 This command will fail if:
  43
  44 . The .git/config file is invalid,
  45 . Can not write to .git/config,
  46 . no section was provided,
  47 . the section or key is invalid,
  48 . you try to unset an option which does not exist,
  49 . you try to unset/set an option for which multiple lines match, or
  50 . you use --global option without $HOME being properly set.
  51
  52
  53 OPTIONS
  54 -------
  55
  56 --replace-all::
  57         Default behavior is to replace at most one line. This replaces
  58         all lines matching the key (and optionally the value_regex).
  59
  60 --add::
  61         Adds a new line to the option without altering any existing
  62         values.  This is the same as providing '^$' as the value_regex.
  63
  64 --get::
  65         Get the value for a given key (optionally filtered by a regex
  66         matching the value). Returns error code 1 if the key was not
  67         found and error code 2 if multiple key values were found.
  68
  69 --get-all::
  70         Like get, but does not fail if the number of values for the key
  71         is not exactly one.
  72
  73 --get-regexp::
  74         Like --get-all, but interprets the name as a regular expression.
  75
  76 --global::
  77         Use global ~/.gitconfig file rather than the repository .git/config.
  78
  79 --system::
  80         Use system-wide $(prefix)/etc/gitconfig rather than the repository
  81         .git/config.
  82
  83 --remove-section::
  84         Remove the given section from the configuration file.
  85
  86 --rename-section::
  87         Rename the given section to a new name.
  88
  89 --unset::
  90         Remove the line matching the key from config file.
  91
  92 --unset-all::
  93         Remove all lines matching the key from config file.
  94
  95 -l, --list::
  96         List all variables set in config file.
  97
  98 --bool::
  99         git-config will ensure that the output is "true" or "false"
 100
 101 --int::
 102         git-config will ensure that the output is a simple
 103         decimal number.  An optional value suffix of 'k', 'm', or 'g'
 104         in the config file will cause the value to be multiplied
 105         by 1024, 1048576, or 1073741824 prior to output.
 106
 107
 108 ENVIRONMENT
 109 -----------
 110
 111 GIT_CONFIG::
 112         Take the configuration from the given file instead of .git/config.
 113         Using the "--global" option forces this to ~/.gitconfig.
 114
 115 GIT_CONFIG_LOCAL::
 116         Currently the same as $GIT_CONFIG; when Git will support global
 117         configuration files, this will cause it to take the configuration
 118         from the global configuration file in addition to the given file.
 119
 120
 121 EXAMPLE
 122 -------
 123
 124 Given a .git/config like this:
 125
 126         #
 127         # This is the config file, and
 128         # a '#' or ';' character indicates
 129         # a comment
 130         #
 131
 132         ; core variables
 133         [core]
 134                 ; Don't trust file modes
 135                 filemode = false
 136
 137         ; Our diff algorithm
 138         [diff]
 139                 external = "/usr/local/bin/gnu-diff -u"
 140                 renames = true
 141
 142         ; Proxy settings
 143         [core]
 144                 gitproxy="ssh" for "ssh://kernel.org/"
 145                 gitproxy="proxy-command" for kernel.org
 146                 gitproxy="myprotocol-command" for "my://"
 147                 gitproxy=default-proxy ; for all the rest
 148
 149 you can set the filemode to true with
 150
 151 ------------
 152 % git config core.filemode true
 153 ------------
 154
 155 The hypothetical proxy command entries actually have a postfix to discern
 156 what URL they apply to. Here is how to change the entry for kernel.org
 157 to "ssh".
 158
 159 ------------
 160 % git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$'
 161 ------------
 162
 163 This makes sure that only the key/value pair for kernel.org is replaced.
 164
 165 To delete the entry for renames, do
 166
 167 ------------
 168 % git config --unset diff.renames
 169 ------------
 170
 171 If you want to delete an entry for a multivar (like core.gitproxy above),
 172 you have to provide a regex matching the value of exactly one line.
 173
 174 To query the value for a given key, do
 175
 176 ------------
 177 % git config --get core.filemode
 178 ------------
 179
 180 or
 181
 182 ------------
 183 % git config core.filemode
 184 ------------
 185
 186 or, to query a multivar:
 187
 188 ------------
 189 % git config --get core.gitproxy "for kernel.org$"
 190 ------------
 191
 192 If you want to know all the values for a multivar, do:
 193
 194 ------------
 195 % git config --get-all core.gitproxy
 196 ------------
 197
 198 If you like to live dangerous, you can replace *all* core.gitproxy by a
 199 new one with
 200
 201 ------------
 202 % git config --replace-all core.gitproxy ssh
 203 ------------
 204
 205 However, if you really only want to replace the line for the default proxy,
 206 i.e. the one without a "for ..." postfix, do something like this:
 207
 208 ------------
 209 % git config core.gitproxy ssh '! for '
 210 ------------
 211
 212 To actually match only values with an exclamation mark, you have to
 213
 214 ------------
 215 % git config section.key value '[!]'
 216 ------------
 217
 218 To add a new proxy, without altering any of the existing ones, use
 219
 220 ------------
 221 % git config core.gitproxy '"proxy" for example.com'
 222 ------------
 223
 224
 225 include::config.txt[]
 226
 227
 228 Author
 229 ------
 230 Written by Johannes Schindelin <Johannes.Schindelin@gmx.de>
 231
 232 Documentation
 233 --------------
 234 Documentation by Johannes Schindelin, Petr Baudis and the git-list <git@vger.kernel.org>.
 235
 236 GIT
 237 ---
 238 Part of the gitlink:git[7] suite
 239