| 1 | core.fileMode:: |
| 2 | Tells Git if the executable bit of files in the working tree |
| 3 | is to be honored. |
| 4 | + |
| 5 | Some filesystems lose the executable bit when a file that is |
| 6 | marked as executable is checked out, or checks out a |
| 7 | non-executable file with executable bit on. |
| 8 | linkgit:git-clone[1] or linkgit:git-init[1] probe the filesystem |
| 9 | to see if it handles the executable bit correctly |
| 10 | and this variable is automatically set as necessary. |
| 11 | + |
| 12 | A repository, however, may be on a filesystem that handles |
| 13 | the filemode correctly, and this variable is set to 'true' |
| 14 | when created, but later may be made accessible from another |
| 15 | environment that loses the filemode (e.g. exporting ext4 via |
| 16 | CIFS mount, visiting a Cygwin created repository with |
| 17 | Git for Windows or Eclipse). |
| 18 | In such a case it may be necessary to set this variable to 'false'. |
| 19 | See linkgit:git-update-index[1]. |
| 20 | + |
| 21 | The default is true (when core.filemode is not specified in the config file). |
| 22 | |
| 23 | core.hideDotFiles:: |
| 24 | (Windows-only) If true, mark newly-created directories and files whose |
| 25 | name starts with a dot as hidden. If 'dotGitOnly', only the `.git/` |
| 26 | directory is hidden, but no other files starting with a dot. The |
| 27 | default mode is 'dotGitOnly'. |
| 28 | |
| 29 | core.ignoreCase:: |
| 30 | Internal variable which enables various workarounds to enable |
| 31 | Git to work better on filesystems that are not case sensitive, |
| 32 | like APFS, HFS+, FAT, NTFS, etc. For example, if a directory listing |
| 33 | finds "makefile" when Git expects "Makefile", Git will assume |
| 34 | it is really the same file, and continue to remember it as |
| 35 | "Makefile". |
| 36 | + |
| 37 | The default is false, except linkgit:git-clone[1] or linkgit:git-init[1] |
| 38 | will probe and set core.ignoreCase true if appropriate when the repository |
| 39 | is created. |
| 40 | + |
| 41 | Git relies on the proper configuration of this variable for your operating |
| 42 | and file system. Modifying this value may result in unexpected behavior. |
| 43 | |
| 44 | core.precomposeUnicode:: |
| 45 | This option is only used by Mac OS implementation of Git. |
| 46 | When core.precomposeUnicode=true, Git reverts the unicode decomposition |
| 47 | of filenames done by Mac OS. This is useful when sharing a repository |
| 48 | between Mac OS and Linux or Windows. |
| 49 | (Git for Windows 1.7.10 or higher is needed, or Git under cygwin 1.7). |
| 50 | When false, file names are handled fully transparent by Git, |
| 51 | which is backward compatible with older versions of Git. |
| 52 | |
| 53 | core.protectHFS:: |
| 54 | If set to true, do not allow checkout of paths that would |
| 55 | be considered equivalent to `.git` on an HFS+ filesystem. |
| 56 | Defaults to `true` on Mac OS, and `false` elsewhere. |
| 57 | |
| 58 | core.protectNTFS:: |
| 59 | If set to true, do not allow checkout of paths that would |
| 60 | cause problems with the NTFS filesystem, e.g. conflict with |
| 61 | 8.3 "short" names. |
| 62 | Defaults to `true` on Windows, and `false` elsewhere. |
| 63 | |
| 64 | core.fsmonitor:: |
| 65 | If set to true, enable the built-in file system monitor |
| 66 | daemon for this working directory (linkgit:git-fsmonitor{litdd}daemon[1]). |
| 67 | + |
| 68 | Like hook-based file system monitors, the built-in file system monitor |
| 69 | can speed up Git commands that need to refresh the Git index |
| 70 | (e.g. `git status`) in a working directory with many files. The |
| 71 | built-in monitor eliminates the need to install and maintain an |
| 72 | external third-party tool. |
| 73 | + |
| 74 | The built-in file system monitor is currently available only on a |
| 75 | limited set of supported platforms. Currently, this includes Windows |
| 76 | and MacOS. |
| 77 | + |
| 78 | Otherwise, this variable contains the pathname of the "fsmonitor" |
| 79 | hook command. |
| 80 | + |
| 81 | This hook command is used to identify all files that may have changed |
| 82 | since the requested date/time. This information is used to speed up |
| 83 | git by avoiding unnecessary scanning of files that have not changed. |
| 84 | + |
| 85 | See the "fsmonitor-watchman" section of linkgit:githooks[5]. |
| 86 | + |
| 87 | Note that if you concurrently use multiple versions of Git, such |
| 88 | as one version on the command line and another version in an IDE |
| 89 | tool, that the definition of `core.fsmonitor` was extended to |
| 90 | allow boolean values in addition to hook pathnames. Git versions |
| 91 | 2.35.1 and prior will not understand the boolean values and will |
| 92 | consider the "true" or "false" values as hook pathnames to be |
| 93 | invoked. Git versions 2.26 thru 2.35.1 default to hook protocol |
| 94 | V2 and will fall back to no fsmonitor (full scan). Git versions |
| 95 | prior to 2.26 default to hook protocol V1 and will silently |
| 96 | assume there were no changes to report (no scan), so status |
| 97 | commands may report incomplete results. For this reason, it is |
| 98 | best to upgrade all of your Git versions before using the built-in |
| 99 | file system monitor. |
| 100 | |
| 101 | core.fsmonitorHookVersion:: |
| 102 | Sets the protocol version to be used when invoking the |
| 103 | "fsmonitor" hook. |
| 104 | + |
| 105 | There are currently versions 1 and 2. When this is not set, |
| 106 | version 2 will be tried first and if it fails then version 1 |
| 107 | will be tried. Version 1 uses a timestamp as input to determine |
| 108 | which files have changes since that time but some monitors |
| 109 | like Watchman have race conditions when used with a timestamp. |
| 110 | Version 2 uses an opaque string so that the monitor can return |
| 111 | something that can be used to determine what files have changed |
| 112 | without race conditions. |
| 113 | |
| 114 | core.trustctime:: |
| 115 | If false, the ctime differences between the index and the |
| 116 | working tree are ignored; useful when the inode change time |
| 117 | is regularly modified by something outside Git (file system |
| 118 | crawlers and some backup systems). |
| 119 | See linkgit:git-update-index[1]. True by default. |
| 120 | |
| 121 | core.splitIndex:: |
| 122 | If true, the split-index feature of the index will be used. |
| 123 | See linkgit:git-update-index[1]. False by default. |
| 124 | |
| 125 | core.untrackedCache:: |
| 126 | Determines what to do about the untracked cache feature of the |
| 127 | index. It will be kept, if this variable is unset or set to |
| 128 | `keep`. It will automatically be added if set to `true`. And |
| 129 | it will automatically be removed, if set to `false`. Before |
| 130 | setting it to `true`, you should check that mtime is working |
| 131 | properly on your system. |
| 132 | See linkgit:git-update-index[1]. `keep` by default, unless |
| 133 | `feature.manyFiles` is enabled which sets this setting to |
| 134 | `true` by default. |
| 135 | |
| 136 | core.checkStat:: |
| 137 | When missing or is set to `default`, many fields in the stat |
| 138 | structure are checked to detect if a file has been modified |
| 139 | since Git looked at it. When this configuration variable is |
| 140 | set to `minimal`, sub-second part of mtime and ctime, the |
| 141 | uid and gid of the owner of the file, the inode number (and |
| 142 | the device number, if Git was compiled to use it), are |
| 143 | excluded from the check among these fields, leaving only the |
| 144 | whole-second part of mtime (and ctime, if `core.trustCtime` |
| 145 | is set) and the filesize to be checked. |
| 146 | + |
| 147 | There are implementations of Git that do not leave usable values in |
| 148 | some fields (e.g. JGit); by excluding these fields from the |
| 149 | comparison, the `minimal` mode may help interoperability when the |
| 150 | same repository is used by these other systems at the same time. |
| 151 | |
| 152 | core.quotePath:: |
| 153 | Commands that output paths (e.g. 'ls-files', 'diff'), will |
| 154 | quote "unusual" characters in the pathname by enclosing the |
| 155 | pathname in double-quotes and escaping those characters with |
| 156 | backslashes in the same way C escapes control characters (e.g. |
| 157 | `\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with |
| 158 | values larger than 0x80 (e.g. octal `\302\265` for "micro" in |
| 159 | UTF-8). If this variable is set to false, bytes higher than |
| 160 | 0x80 are not considered "unusual" any more. Double-quotes, |
| 161 | backslash and control characters are always escaped regardless |
| 162 | of the setting of this variable. A simple space character is |
| 163 | not considered "unusual". Many commands can output pathnames |
| 164 | completely verbatim using the `-z` option. The default value |
| 165 | is true. |
| 166 | |
| 167 | core.eol:: |
| 168 | Sets the line ending type to use in the working directory for |
| 169 | files that are marked as text (either by having the `text` |
| 170 | attribute set, or by having `text=auto` and Git auto-detecting |
| 171 | the contents as text). |
| 172 | Alternatives are 'lf', 'crlf' and 'native', which uses the platform's |
| 173 | native line ending. The default value is `native`. See |
| 174 | linkgit:gitattributes[5] for more information on end-of-line |
| 175 | conversion. Note that this value is ignored if `core.autocrlf` |
| 176 | is set to `true` or `input`. |
| 177 | |
| 178 | core.safecrlf:: |
| 179 | If true, makes Git check if converting `CRLF` is reversible when |
| 180 | end-of-line conversion is active. Git will verify if a command |
| 181 | modifies a file in the work tree either directly or indirectly. |
| 182 | For example, committing a file followed by checking out the |
| 183 | same file should yield the original file in the work tree. If |
| 184 | this is not the case for the current setting of |
| 185 | `core.autocrlf`, Git will reject the file. The variable can |
| 186 | be set to "warn", in which case Git will only warn about an |
| 187 | irreversible conversion but continue the operation. |
| 188 | + |
| 189 | CRLF conversion bears a slight chance of corrupting data. |
| 190 | When it is enabled, Git will convert CRLF to LF during commit and LF to |
| 191 | CRLF during checkout. A file that contains a mixture of LF and |
| 192 | CRLF before the commit cannot be recreated by Git. For text |
| 193 | files this is the right thing to do: it corrects line endings |
| 194 | such that we have only LF line endings in the repository. |
| 195 | But for binary files that are accidentally classified as text the |
| 196 | conversion can corrupt data. |
| 197 | + |
| 198 | If you recognize such corruption early you can easily fix it by |
| 199 | setting the conversion type explicitly in .gitattributes. Right |
| 200 | after committing you still have the original file in your work |
| 201 | tree and this file is not yet corrupted. You can explicitly tell |
| 202 | Git that this file is binary and Git will handle the file |
| 203 | appropriately. |
| 204 | + |
| 205 | Unfortunately, the desired effect of cleaning up text files with |
| 206 | mixed line endings and the undesired effect of corrupting binary |
| 207 | files cannot be distinguished. In both cases CRLFs are removed |
| 208 | in an irreversible way. For text files this is the right thing |
| 209 | to do because CRLFs are line endings, while for binary files |
| 210 | converting CRLFs corrupts data. |
| 211 | + |
| 212 | Note, this safety check does not mean that a checkout will generate a |
| 213 | file identical to the original file for a different setting of |
| 214 | `core.eol` and `core.autocrlf`, but only for the current one. For |
| 215 | example, a text file with `LF` would be accepted with `core.eol=lf` |
| 216 | and could later be checked out with `core.eol=crlf`, in which case the |
| 217 | resulting file would contain `CRLF`, although the original file |
| 218 | contained `LF`. However, in both work trees the line endings would be |
| 219 | consistent, that is either all `LF` or all `CRLF`, but never mixed. A |
| 220 | file with mixed line endings would be reported by the `core.safecrlf` |
| 221 | mechanism. |
| 222 | |
| 223 | core.autocrlf:: |
| 224 | Setting this variable to "true" is the same as setting |
| 225 | the `text` attribute to "auto" on all files and core.eol to "crlf". |
| 226 | Set to true if you want to have `CRLF` line endings in your |
| 227 | working directory and the repository has LF line endings. |
| 228 | This variable can be set to 'input', |
| 229 | in which case no output conversion is performed. |
| 230 | |
| 231 | core.checkRoundtripEncoding:: |
| 232 | A comma and/or whitespace separated list of encodings that Git |
| 233 | performs UTF-8 round trip checks on if they are used in an |
| 234 | `working-tree-encoding` attribute (see linkgit:gitattributes[5]). |
| 235 | The default value is `SHIFT-JIS`. |
| 236 | |
| 237 | core.symlinks:: |
| 238 | If false, symbolic links are checked out as small plain files that |
| 239 | contain the link text. linkgit:git-update-index[1] and |
| 240 | linkgit:git-add[1] will not change the recorded type to regular |
| 241 | file. Useful on filesystems like FAT that do not support |
| 242 | symbolic links. |
| 243 | + |
| 244 | The default is true, except linkgit:git-clone[1] or linkgit:git-init[1] |
| 245 | will probe and set core.symlinks false if appropriate when the repository |
| 246 | is created. |
| 247 | |
| 248 | core.gitProxy:: |
| 249 | A "proxy command" to execute (as 'command host port') instead |
| 250 | of establishing direct connection to the remote server when |
| 251 | using the Git protocol for fetching. If the variable value is |
| 252 | in the "COMMAND for DOMAIN" format, the command is applied only |
| 253 | on hostnames ending with the specified domain string. This variable |
| 254 | may be set multiple times and is matched in the given order; |
| 255 | the first match wins. |
| 256 | + |
| 257 | Can be overridden by the `GIT_PROXY_COMMAND` environment variable |
| 258 | (which always applies universally, without the special "for" |
| 259 | handling). |
| 260 | + |
| 261 | The special string `none` can be used as the proxy command to |
| 262 | specify that no proxy be used for a given domain pattern. |
| 263 | This is useful for excluding servers inside a firewall from |
| 264 | proxy use, while defaulting to a common proxy for external domains. |
| 265 | |
| 266 | core.sshCommand:: |
| 267 | If this variable is set, `git fetch` and `git push` will |
| 268 | use the specified command instead of `ssh` when they need to |
| 269 | connect to a remote system. The command is in the same form as |
| 270 | the `GIT_SSH_COMMAND` environment variable and is overridden |
| 271 | when the environment variable is set. |
| 272 | |
| 273 | core.ignoreStat:: |
| 274 | If true, Git will avoid using lstat() calls to detect if files have |
| 275 | changed by setting the "assume-unchanged" bit for those tracked files |
| 276 | which it has updated identically in both the index and working tree. |
| 277 | + |
| 278 | When files are modified outside of Git, the user will need to stage |
| 279 | the modified files explicitly (e.g. see 'Examples' section in |
| 280 | linkgit:git-update-index[1]). |
| 281 | Git will not normally detect changes to those files. |
| 282 | + |
| 283 | This is useful on systems where lstat() calls are very slow, such as |
| 284 | CIFS/Microsoft Windows. |
| 285 | + |
| 286 | False by default. |
| 287 | |
| 288 | core.preferSymlinkRefs:: |
| 289 | Instead of the default "symref" format for HEAD |
| 290 | and other symbolic reference files, use symbolic links. |
| 291 | This is sometimes needed to work with old scripts that |
| 292 | expect HEAD to be a symbolic link. |
| 293 | + |
| 294 | This configuration is deprecated and will be removed in Git 3.0. Symbolic refs |
| 295 | will always be written as textual symrefs. |
| 296 | |
| 297 | core.alternateRefsCommand:: |
| 298 | When advertising tips of available history from an alternate, use the shell to |
| 299 | execute the specified command instead of linkgit:git-for-each-ref[1]. The |
| 300 | first argument is the absolute path of the alternate. Output must contain one |
| 301 | hex object id per line (i.e., the same as produced by `git for-each-ref |
| 302 | --format='%(objectname)'`). |
| 303 | + |
| 304 | Note that you cannot generally put `git for-each-ref` directly into the config |
| 305 | value, as it does not take a repository path as an argument (but you can wrap |
| 306 | the command above in a shell script). |
| 307 | |
| 308 | core.alternateRefsPrefixes:: |
| 309 | When listing references from an alternate, list only references that begin |
| 310 | with the given prefix. Prefixes match as if they were given as arguments to |
| 311 | linkgit:git-for-each-ref[1]. To list multiple prefixes, separate them with |
| 312 | whitespace. If `core.alternateRefsCommand` is set, setting |
| 313 | `core.alternateRefsPrefixes` has no effect. |
| 314 | |
| 315 | core.bare:: |
| 316 | If true this repository is assumed to be 'bare' and has no |
| 317 | working directory associated with it. If this is the case a |
| 318 | number of commands that require a working directory will be |
| 319 | disabled, such as linkgit:git-add[1] or linkgit:git-merge[1]. |
| 320 | + |
| 321 | This setting is automatically guessed by linkgit:git-clone[1] or |
| 322 | linkgit:git-init[1] when the repository was created. By default a |
| 323 | repository that ends in "/.git" is assumed to be not bare (bare = |
| 324 | false), while all other repositories are assumed to be bare (bare |
| 325 | = true). |
| 326 | |
| 327 | core.worktree:: |
| 328 | Set the path to the root of the working tree. |
| 329 | If `GIT_COMMON_DIR` environment variable is set, core.worktree |
| 330 | is ignored and not used for determining the root of working tree. |
| 331 | This can be overridden by the `GIT_WORK_TREE` environment |
| 332 | variable and the `--work-tree` command-line option. |
| 333 | The value can be an absolute path or relative to the path to |
| 334 | the .git directory, which is either specified by --git-dir |
| 335 | or GIT_DIR, or automatically discovered. |
| 336 | If --git-dir or GIT_DIR is specified but none of |
| 337 | --work-tree, GIT_WORK_TREE and core.worktree is specified, |
| 338 | the current working directory is regarded as the top level |
| 339 | of your working tree. |
| 340 | + |
| 341 | Note that this variable is honored even when set in a configuration |
| 342 | file in a ".git" subdirectory of a directory and its value differs |
| 343 | from the latter directory (e.g. "/path/to/.git/config" has |
| 344 | core.worktree set to "/different/path"), which is most likely a |
| 345 | misconfiguration. Running Git commands in the "/path/to" directory will |
| 346 | still use "/different/path" as the root of the work tree and can cause |
| 347 | confusion unless you know what you are doing (e.g. you are creating a |
| 348 | read-only snapshot of the same index to a location different from the |
| 349 | repository's usual working tree). |
| 350 | |
| 351 | core.lockfilePid:: |
| 352 | If true, Git will create a PID file alongside lock files. When a |
| 353 | lock acquisition fails and a PID file exists, Git can provide |
| 354 | additional diagnostic information about the process holding the |
| 355 | lock, including whether it is still running. Defaults to `false`. |
| 356 | + |
| 357 | The PID file is named by inserting `~pid` before the `.lock` suffix. |
| 358 | For example, if the lock file is `index.lock`, the PID file will be |
| 359 | `index~pid.lock`. The file contains a single line in the format |
| 360 | `pid <value>` followed by a newline. |
| 361 | |
| 362 | core.logAllRefUpdates:: |
| 363 | Enable the reflog. Updates to a ref <ref> is logged to the file |
| 364 | "`$GIT_DIR/logs/<ref>`", by appending the new and old |
| 365 | SHA-1, the date/time and the reason of the update, but |
| 366 | only when the file exists. If this configuration |
| 367 | variable is set to `true`, missing "`$GIT_DIR/logs/<ref>`" |
| 368 | file is automatically created for branch heads (i.e. under |
| 369 | `refs/heads/`), remote refs (i.e. under `refs/remotes/`), |
| 370 | note refs (i.e. under `refs/notes/`), and the symbolic ref `HEAD`. |
| 371 | If it is set to `always`, then a missing reflog is automatically |
| 372 | created for any ref under `refs/`. |
| 373 | + |
| 374 | This information can be used to determine what commit |
| 375 | was the tip of a branch "2 days ago". |
| 376 | + |
| 377 | This value is true by default in a repository that has |
| 378 | a working directory associated with it, and false by |
| 379 | default in a bare repository. |
| 380 | |
| 381 | core.repositoryFormatVersion:: |
| 382 | Internal variable identifying the repository format and layout |
| 383 | version. See linkgit:gitrepository-layout[5]. |
| 384 | |
| 385 | core.sharedRepository:: |
| 386 | When 'group' (or 'true'), the repository is made shareable between |
| 387 | several users in a group (making sure all the files and objects are |
| 388 | group-writable). When 'all' (or 'world' or 'everybody'), the |
| 389 | repository will be readable by all users, additionally to being |
| 390 | group-shareable. When 'umask' (or 'false'), Git will use permissions |
| 391 | reported by umask(2). When '0xxx', where '0xxx' is an octal number, |
| 392 | files in the repository will have this mode value. '0xxx' will override |
| 393 | user's umask value (whereas the other options will only override |
| 394 | requested parts of the user's umask value). Examples: '0660' will make |
| 395 | the repo read/write-able for the owner and group, but inaccessible to |
| 396 | others (equivalent to 'group' unless umask is e.g. '0022'). '0640' is a |
| 397 | repository that is group-readable but not group-writable. |
| 398 | See linkgit:git-init[1]. False by default. |
| 399 | |
| 400 | core.warnAmbiguousRefs:: |
| 401 | If true, Git will warn you if the ref name you passed it is ambiguous |
| 402 | and might match multiple refs in the repository. True by default. |
| 403 | |
| 404 | core.compression:: |
| 405 | An integer -1..9, indicating a default compression level. |
| 406 | -1 is the zlib default. 0 means no compression, |
| 407 | and 1..9 are various speed/size tradeoffs, 9 being slowest. |
| 408 | If set, this provides a default to other compression variables, |
| 409 | such as `core.looseCompression` and `pack.compression`. |
| 410 | |
| 411 | core.looseCompression:: |
| 412 | An integer -1..9, indicating the compression level for objects that |
| 413 | are not in a pack file. -1 is the zlib default. 0 means no |
| 414 | compression, and 1..9 are various speed/size tradeoffs, 9 being |
| 415 | slowest. If not set, defaults to core.compression. If that is |
| 416 | not set, defaults to 1 (best speed). |
| 417 | |
| 418 | core.packedGitWindowSize:: |
| 419 | Number of bytes of a pack file to map into memory in a |
| 420 | single mapping operation. Larger window sizes may allow |
| 421 | your system to process a smaller number of large pack files |
| 422 | more quickly. Smaller window sizes will negatively affect |
| 423 | performance due to increased calls to the operating system's |
| 424 | memory manager, but may improve performance when accessing |
| 425 | a large number of large pack files. |
| 426 | + |
| 427 | Default is 1 MiB if NO_MMAP was set at compile time, otherwise 32 |
| 428 | MiB on 32 bit platforms and 1 GiB on 64 bit platforms. This should |
| 429 | be reasonable for all users/operating systems. You probably do |
| 430 | not need to adjust this value. |
| 431 | + |
| 432 | Common unit suffixes of 'k', 'm', or 'g' are supported. |
| 433 | |
| 434 | core.packedGitLimit:: |
| 435 | Maximum number of bytes to map simultaneously into memory |
| 436 | from pack files. If Git needs to access more than this many |
| 437 | bytes at once to complete an operation it will unmap existing |
| 438 | regions to reclaim virtual address space within the process. |
| 439 | + |
| 440 | Default is 256 MiB on 32 bit platforms and 32 TiB (effectively |
| 441 | unlimited) on 64 bit platforms. |
| 442 | This should be reasonable for all users/operating systems, except on |
| 443 | the largest projects. You probably do not need to adjust this value. |
| 444 | + |
| 445 | Common unit suffixes of 'k', 'm', or 'g' are supported. |
| 446 | |
| 447 | core.deltaBaseCacheLimit:: |
| 448 | Maximum number of bytes per thread to reserve for caching base objects |
| 449 | that may be referenced by multiple deltified objects. By storing the |
| 450 | entire decompressed base objects in a cache Git is able |
| 451 | to avoid unpacking and decompressing frequently used base |
| 452 | objects multiple times. |
| 453 | + |
| 454 | Default is 96 MiB on all platforms. This should be reasonable |
| 455 | for all users/operating systems, except on the largest projects. |
| 456 | You probably do not need to adjust this value. |
| 457 | + |
| 458 | Common unit suffixes of 'k', 'm', or 'g' are supported. |
| 459 | |
| 460 | core.bigFileThreshold:: |
| 461 | The size of files considered "big", which as discussed below |
| 462 | changes the behavior of numerous git commands, as well as how |
| 463 | such files are stored within the repository. The default is |
| 464 | 512 MiB. Common unit suffixes of 'k', 'm', or 'g' are |
| 465 | supported. |
| 466 | + |
| 467 | Files above the configured limit will be: |
| 468 | + |
| 469 | * Stored deflated in packfiles, without attempting delta compression. |
| 470 | + |
| 471 | The default limit is primarily set with this use-case in mind. With it, |
| 472 | most projects will have their source code and other text files delta |
| 473 | compressed, but not larger binary media files. |
| 474 | + |
| 475 | Storing large files without delta compression avoids excessive memory |
| 476 | usage, at the slight expense of increased disk usage. |
| 477 | + |
| 478 | * Will be treated as if they were labeled "binary" (see |
| 479 | linkgit:gitattributes[5]). e.g. linkgit:git-log[1] and |
| 480 | linkgit:git-diff[1] will not compute diffs for files above this limit. |
| 481 | + |
| 482 | * Will generally be streamed when written, which avoids excessive |
| 483 | memory usage, at the cost of some fixed overhead. Commands that make |
| 484 | use of this include linkgit:git-archive[1], |
| 485 | linkgit:git-fast-import[1], linkgit:git-index-pack[1], |
| 486 | linkgit:git-unpack-objects[1] and linkgit:git-fsck[1]. |
| 487 | |
| 488 | core.excludesFile:: |
| 489 | Specifies the pathname to the file that contains patterns to |
| 490 | describe paths that are not meant to be tracked, in addition |
| 491 | to `.gitignore` (per-directory) and `.git/info/exclude`. |
| 492 | Defaults to `$XDG_CONFIG_HOME/git/ignore`. |
| 493 | If `$XDG_CONFIG_HOME` is either not set or empty, `$HOME/.config/git/ignore` |
| 494 | is used instead. See linkgit:gitignore[5]. |
| 495 | |
| 496 | core.askPass:: |
| 497 | Some commands (e.g. svn and http interfaces) that interactively |
| 498 | ask for a password can be told to use an external program given |
| 499 | via the value of this variable. Can be overridden by the `GIT_ASKPASS` |
| 500 | environment variable. If not set, fall back to the value of the |
| 501 | `SSH_ASKPASS` environment variable or, failing that, a simple password |
| 502 | prompt. The external program shall be given a suitable prompt as |
| 503 | command-line argument and write the password on its STDOUT. |
| 504 | |
| 505 | core.attributesFile:: |
| 506 | Specifies the pathname to the file that contains attributes (see |
| 507 | linkgit:gitattributes[5]), in addition to `.gitattributes` (per-directory) |
| 508 | and `.git/info/attributes`. Its default value is |
| 509 | `$XDG_CONFIG_HOME/git/attributes`. If `$XDG_CONFIG_HOME` is either not |
| 510 | set or empty, `$HOME/.config/git/attributes` is used instead. |
| 511 | |
| 512 | core.hooksPath:: |
| 513 | By default Git will look for your hooks in the |
| 514 | `$GIT_DIR/hooks` directory. Set this to different path, |
| 515 | e.g. `/etc/git/hooks`, and Git will try to find your hooks in |
| 516 | that directory, e.g. `/etc/git/hooks/pre-receive` instead of |
| 517 | in `$GIT_DIR/hooks/pre-receive`. |
| 518 | + |
| 519 | The path can be either absolute or relative. A relative path is |
| 520 | taken as relative to the directory where the hooks are run (see |
| 521 | the "DESCRIPTION" section of linkgit:githooks[5]). |
| 522 | + |
| 523 | This configuration variable is useful in cases where you'd like to |
| 524 | centrally configure your Git hooks instead of configuring them on a |
| 525 | per-repository basis, or as a more flexible and centralized |
| 526 | alternative to having an `init.templateDir` where you've changed |
| 527 | default hooks. |
| 528 | + |
| 529 | You can also disable all hooks entirely by setting `core.hooksPath` |
| 530 | to `/dev/null`. This is usually only advisable for expert users and |
| 531 | on a per-command basis using configuration parameters of the form |
| 532 | `git -c core.hooksPath=/dev/null ...`. |
| 533 | |
| 534 | core.editor:: |
| 535 | Commands such as `commit` and `tag` that let you edit |
| 536 | messages by launching an editor use the value of this |
| 537 | variable when it is set, and the environment variable |
| 538 | `GIT_EDITOR` is not set. See linkgit:git-var[1]. |
| 539 | |
| 540 | core.commentChar:: |
| 541 | core.commentString:: |
| 542 | Commands such as `commit` and `tag` that let you edit |
| 543 | messages consider a line that begins with this character |
| 544 | commented, and removes them after the editor returns |
| 545 | (default '#'). |
| 546 | + |
| 547 | ifndef::with-breaking-changes[] |
| 548 | If set to "auto", `git-commit` will select a character that is not |
| 549 | the beginning character of any line in existing commit messages. |
| 550 | Support for this value is deprecated and will be removed in Git 3.0 |
| 551 | due to the following limitations: |
| 552 | + |
| 553 | -- |
| 554 | * It is incompatible with adding comments in a commit message |
| 555 | template. This includes the conflicts comments added to |
| 556 | the commit message by `cherry-pick`, `merge`, `rebase` and |
| 557 | `revert`. |
| 558 | * It is incompatible with adding comments to the commit message |
| 559 | in the `prepare-commit-msg` hook. |
| 560 | * It is incompatible with the `fixup` and `squash` commands when |
| 561 | rebasing, |
| 562 | * It is not respected by `git notes` |
| 563 | -- |
| 564 | + |
| 565 | endif::with-breaking-changes[] |
| 566 | Note that these two variables are aliases of each other, and in modern |
| 567 | versions of Git you are free to use a string (e.g., `//` or `⁑⁕⁑`) with |
| 568 | `commentChar`. Versions of Git prior to v2.45.0 will ignore |
| 569 | `commentString` but will reject a value of `commentChar` that consists |
| 570 | of more than a single ASCII byte. If you plan to use your config with |
| 571 | older and newer versions of Git, you may want to specify both: |
| 572 | + |
| 573 | [core] |
| 574 | # single character for older versions |
| 575 | commentChar = "#" |
| 576 | # string for newer versions (which will override commentChar |
| 577 | # because it comes later in the file) |
| 578 | commentString = "//" |
| 579 | |
| 580 | core.filesRefLockTimeout:: |
| 581 | The length of time, in milliseconds, to retry when trying to |
| 582 | lock an individual reference. Value 0 means not to retry at |
| 583 | all; -1 means to try indefinitely. Default is 100 (i.e., |
| 584 | retry for 100ms). |
| 585 | |
| 586 | core.packedRefsTimeout:: |
| 587 | The length of time, in milliseconds, to retry when trying to |
| 588 | lock the `packed-refs` file. Value 0 means not to retry at |
| 589 | all; -1 means to try indefinitely. Default is 1000 (i.e., |
| 590 | retry for 1 second). |
| 591 | |
| 592 | core.configLockTimeout:: |
| 593 | The length of time, in milliseconds, to retry when trying to |
| 594 | lock a configuration file for writing. Value 0 means not to |
| 595 | retry at all; -1 means to try indefinitely. Default is 1000 |
| 596 | (i.e., retry for 1 second). This is read from the configuration |
| 597 | that is already on disk before the lock is taken, so it can be |
| 598 | set persistently like any other option. |
| 599 | |
| 600 | core.pager:: |
| 601 | Text viewer for use by Git commands (e.g., 'less'). The value |
| 602 | is meant to be interpreted by the shell. The order of preference |
| 603 | is the `$GIT_PAGER` environment variable, then `core.pager` |
| 604 | configuration, then `$PAGER`, and then the default chosen at |
| 605 | compile time (usually 'less'). |
| 606 | + |
| 607 | When the `LESS` environment variable is unset, Git sets it to `FRX` |
| 608 | (if `LESS` environment variable is set, Git does not change it at |
| 609 | all). If you want to selectively override Git's default setting |
| 610 | for `LESS`, you can set `core.pager` to e.g. `less -S`. This will |
| 611 | be passed to the shell by Git, which will translate the final |
| 612 | command to `LESS=FRX less -S`. The environment does not set the |
| 613 | `S` option but the command line does, instructing less to truncate |
| 614 | long lines. Similarly, setting `core.pager` to `less -+F` will |
| 615 | deactivate the `F` option specified by the environment from the |
| 616 | command-line, deactivating the "quit if one screen" behavior of |
| 617 | `less`. One can specifically activate some flags for particular |
| 618 | commands: for example, setting `pager.blame` to `less -S` enables |
| 619 | line truncation only for `git blame`. |
| 620 | + |
| 621 | Likewise, when the `LV` environment variable is unset, Git sets it |
| 622 | to `-c`. You can override this setting by exporting `LV` with |
| 623 | another value or setting `core.pager` to `lv +c`. |
| 624 | |
| 625 | core.whitespace:: |
| 626 | A comma separated list of common whitespace problems to |
| 627 | notice. 'git diff' will use `color.diff.whitespace` to |
| 628 | highlight them, and 'git apply --whitespace=error' will |
| 629 | consider them as errors. You can prefix `-` to disable |
| 630 | any of them (e.g. `-trailing-space`): |
| 631 | + |
| 632 | * `blank-at-eol` treats trailing whitespaces at the end of the line |
| 633 | as an error (enabled by default). |
| 634 | * `space-before-tab` treats a space character that appears immediately |
| 635 | before a tab character in the initial indent part of the line as an |
| 636 | error (enabled by default). |
| 637 | * `indent-with-non-tab` treats a line that is indented with space |
| 638 | characters instead of the equivalent tabs as an error (not enabled by |
| 639 | default). |
| 640 | * `tab-in-indent` treats a tab character in the initial indent part of |
| 641 | the line as an error (not enabled by default). |
| 642 | * `blank-at-eof` treats blank lines added at the end of file as an error |
| 643 | (enabled by default). |
| 644 | * `trailing-space` is a short-hand to cover both `blank-at-eol` and |
| 645 | `blank-at-eof`. |
| 646 | * `cr-at-eol` treats a carriage-return at the end of line as |
| 647 | part of the line terminator, i.e. with it, `trailing-space` |
| 648 | does not trigger if the character before such a carriage-return |
| 649 | is not a whitespace (not enabled by default). |
| 650 | * `incomplete-line` treats the last line of a file that is missing the |
| 651 | newline at the end as an error (not enabled by default). |
| 652 | * `tabwidth=<n>` tells how many character positions a tab occupies; this |
| 653 | is relevant for `indent-with-non-tab` and when Git fixes `tab-in-indent` |
| 654 | errors. The default tab width is 8. Allowed values are 1 to 63. |
| 655 | |
| 656 | core.fsync:: |
| 657 | A comma-separated list of components of the repository that |
| 658 | should be hardened via the core.fsyncMethod when created or |
| 659 | modified. You can disable hardening of any component by |
| 660 | prefixing it with a '-'. Items that are not hardened may be |
| 661 | lost in the event of an unclean system shutdown. Unless you |
| 662 | have special requirements, it is recommended that you leave |
| 663 | this option empty or pick one of `committed`, `added`, |
| 664 | or `all`. |
| 665 | + |
| 666 | When this configuration is encountered, the set of components starts with |
| 667 | the platform default value, disabled components are removed, and additional |
| 668 | components are added. `none` resets the state so that the platform default |
| 669 | is ignored. |
| 670 | + |
| 671 | The empty string resets the fsync configuration to the platform |
| 672 | default. The default on most platforms is equivalent to |
| 673 | `core.fsync=committed,-loose-object`, which has good performance, |
| 674 | but risks losing recent work in the event of an unclean system shutdown. |
| 675 | + |
| 676 | * `none` clears the set of fsynced components. |
| 677 | * `loose-object` hardens objects added to the repo in loose-object form. |
| 678 | * `pack` hardens objects added to the repo in packfile form. |
| 679 | * `pack-metadata` hardens packfile bitmaps and indexes. |
| 680 | * `commit-graph` hardens the commit-graph file. |
| 681 | * `index` hardens the index when it is modified. |
| 682 | * `objects` is an aggregate option that is equivalent to |
| 683 | `loose-object,pack`. |
| 684 | * `reference` hardens references modified in the repo. |
| 685 | * `derived-metadata` is an aggregate option that is equivalent to |
| 686 | `pack-metadata,commit-graph`. |
| 687 | * `committed` is an aggregate option that is currently equivalent to |
| 688 | `objects`. This mode sacrifices some performance to ensure that work |
| 689 | that is committed to the repository with `git commit` or similar commands |
| 690 | is hardened. |
| 691 | * `added` is an aggregate option that is currently equivalent to |
| 692 | `committed,index`. This mode sacrifices additional performance to |
| 693 | ensure that the results of commands like `git add` and similar operations |
| 694 | are hardened. |
| 695 | * `all` is an aggregate option that syncs all individual components above. |
| 696 | |
| 697 | core.fsyncMethod:: |
| 698 | A value indicating the strategy Git will use to harden repository data |
| 699 | using fsync and related primitives. |
| 700 | + |
| 701 | * `fsync` uses the fsync() system call or platform equivalents. |
| 702 | * `writeout-only` issues pagecache writeback requests, but depending on the |
| 703 | filesystem and storage hardware, data added to the repository may not be |
| 704 | durable in the event of a system crash. This is the default mode on macOS. |
| 705 | * `batch` enables a mode that uses writeout-only flushes to stage multiple |
| 706 | updates in the disk writeback cache and then does a single full fsync of |
| 707 | a dummy file to trigger the disk cache flush at the end of the operation. |
| 708 | + |
| 709 | Currently `batch` mode only applies to loose-object files. Other repository |
| 710 | data is made durable as if `fsync` was specified. This mode is expected to |
| 711 | be as safe as `fsync` on macOS for repos stored on HFS+ or APFS filesystems |
| 712 | and on Windows for repos stored on NTFS or ReFS filesystems. |
| 713 | |
| 714 | core.fsyncObjectFiles:: |
| 715 | This boolean will enable 'fsync()' when writing object files. |
| 716 | This setting is deprecated. Use core.fsync instead. |
| 717 | + |
| 718 | This setting affects data added to the Git repository in loose-object |
| 719 | form. When set to true, Git will issue an fsync or similar system call |
| 720 | to flush caches so that loose-objects remain consistent in the face |
| 721 | of a unclean system shutdown. |
| 722 | |
| 723 | core.preloadIndex:: |
| 724 | Enable parallel index preload for operations like 'git diff' |
| 725 | + |
| 726 | This can speed up operations like 'git diff' and 'git status' especially |
| 727 | on filesystems like NFS that have weak caching semantics and thus |
| 728 | relatively high IO latencies. When enabled, Git will do the |
| 729 | index comparison to the filesystem data in parallel, allowing |
| 730 | overlapping IO's. Defaults to true. |
| 731 | |
| 732 | core.unsetenvvars:: |
| 733 | Windows-only: comma-separated list of environment variables' |
| 734 | names that need to be unset before spawning any other process. |
| 735 | Defaults to `PERL5LIB` to account for the fact that Git for |
| 736 | Windows insists on using its own Perl interpreter. |
| 737 | |
| 738 | core.createObject:: |
| 739 | You can set this to 'link', in which case a hardlink followed by |
| 740 | a delete of the source are used to make sure that object creation |
| 741 | will not overwrite existing objects. |
| 742 | + |
| 743 | On some file system/operating system combinations, this is unreliable. |
| 744 | Set this config setting to 'rename' there; however, this will remove the |
| 745 | check that makes sure that existing object files will not get overwritten. |
| 746 | |
| 747 | core.notesRef:: |
| 748 | When showing commit messages, also show notes which are stored in |
| 749 | the given ref. The ref must be fully qualified. If the given |
| 750 | ref does not exist, it is not an error but means that no |
| 751 | notes should be printed. |
| 752 | + |
| 753 | This setting defaults to "refs/notes/commits", and it can be overridden by |
| 754 | the `GIT_NOTES_REF` environment variable. See linkgit:git-notes[1]. |
| 755 | |
| 756 | core.commitGraph:: |
| 757 | If true, then git will read the commit-graph file (if it exists) |
| 758 | to parse the graph structure of commits. Defaults to true. See |
| 759 | linkgit:git-commit-graph[1] for more information. |
| 760 | |
| 761 | core.useReplaceRefs:: |
| 762 | If set to `false`, behave as if the `--no-replace-objects` |
| 763 | option was given on the command line. See linkgit:git[1] and |
| 764 | linkgit:git-replace[1] for more information. |
| 765 | |
| 766 | core.multiPackIndex:: |
| 767 | Use the multi-pack-index file to track multiple packfiles using a |
| 768 | single index. See linkgit:git-multi-pack-index[1] for more |
| 769 | information. Defaults to true. |
| 770 | |
| 771 | core.sparseCheckout:: |
| 772 | Enable "sparse checkout" feature. See linkgit:git-sparse-checkout[1] |
| 773 | for more information. |
| 774 | |
| 775 | core.sparseCheckoutCone:: |
| 776 | Enables the "cone mode" of the sparse checkout feature. When the |
| 777 | sparse-checkout file contains a limited set of patterns, this |
| 778 | mode provides significant performance advantages. The "non-cone |
| 779 | mode" can be requested to allow specifying more flexible |
| 780 | patterns by setting this variable to 'false'. See |
| 781 | linkgit:git-sparse-checkout[1] for more information. |
| 782 | |
| 783 | core.abbrev:: |
| 784 | Set the length object names are abbreviated to. If |
| 785 | unspecified or set to "auto", an appropriate value is |
| 786 | computed based on the approximate number of packed objects |
| 787 | in your repository, which hopefully is enough for |
| 788 | abbreviated object names to stay unique for some time. |
| 789 | If set to "no", no abbreviation is made and the object names |
| 790 | are shown in their full length. |
| 791 | The minimum length is 4. |
| 792 | |
| 793 | core.maxTreeDepth:: |
| 794 | The maximum depth Git is willing to recurse while traversing a |
| 795 | tree (e.g., "a/b/cde/f" has a depth of 4). This is a fail-safe |
| 796 | to allow Git to abort cleanly, and should not generally need to |
| 797 | be adjusted. When Git is compiled with MSVC, the default is 512. |
| 798 | Otherwise, the default is 2048. |