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