repo-settings: create feature.manyFiles setting
[git/git.git] / Documentation / config / core.txt
2 Tells Git if the executable bit of files in the working tree
3 is to be honored.
5Some filesystems lose the executable bit when a file that is
6marked as executable is checked out, or checks out a
7non-executable file with executable bit on.
8linkgit:git-clone[1] or linkgit:git-init[1] probe the filesystem
9to see if it handles the executable bit correctly
10and this variable is automatically set as necessary.
12A repository, however, may be on a filesystem that handles
13the filemode correctly, and this variable is set to 'true'
14when created, but later may be made accessible from another
15environment that loses the filemode (e.g. exporting ext4 via
16CIFS mount, visiting a Cygwin created repository with
17Git for Windows or Eclipse).
18In such a case it may be necessary to set this variable to 'false'.
19See linkgit:git-update-index[1].
21The default is true (when core.filemode is not specified in the config file).
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'.
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".
37The default is false, except linkgit:git-clone[1] or linkgit:git-init[1]
38will probe and set core.ignoreCase true if appropriate when the repository
39is created.
41Git relies on the proper configuration of this variable for your operating
42and file system. Modifying this value may result in unexpected behavior.
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.
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.
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.
65 If set, the value of this variable is used as a command which
66 will identify all files that may have changed since the
67 requested date/time. This information is used to speed up git by
68 avoiding unnecessary processing of files that have not changed.
69 See the "fsmonitor-watchman" section of linkgit:githooks[5].
72 If false, the ctime differences between the index and the
73 working tree are ignored; useful when the inode change time
74 is regularly modified by something outside Git (file system
75 crawlers and some backup systems).
76 See linkgit:git-update-index[1]. True by default.
79 If true, the split-index feature of the index will be used.
80 See linkgit:git-update-index[1]. False by default.
83 Determines what to do about the untracked cache feature of the
84 index. It will be kept, if this variable is unset or set to
85 `keep`. It will automatically be added if set to `true`. And
86 it will automatically be removed, if set to `false`. Before
87 setting it to `true`, you should check that mtime is working
88 properly on your system.
89 See linkgit:git-update-index[1]. `keep` by default, unless
90 `feature.manyFiles` is enabled which sets this setting to
91 `true` by default.
94 When missing or is set to `default`, many fields in the stat
95 structure are checked to detect if a file has been modified
96 since Git looked at it. When this configuration variable is
97 set to `minimal`, sub-second part of mtime and ctime, the
98 uid and gid of the owner of the file, the inode number (and
99 the device number, if Git was compiled to use it), are
100 excluded from the check among these fields, leaving only the
101 whole-second part of mtime (and ctime, if `core.trustCtime`
102 is set) and the filesize to be checked.
104There are implementations of Git that do not leave usable values in
105some fields (e.g. JGit); by excluding these fields from the
106comparison, the `minimal` mode may help interoperability when the
107same repository is used by these other systems at the same time.
110 Commands that output paths (e.g. 'ls-files', 'diff'), will
111 quote "unusual" characters in the pathname by enclosing the
112 pathname in double-quotes and escaping those characters with
113 backslashes in the same way C escapes control characters (e.g.
114 `\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with
115 values larger than 0x80 (e.g. octal `\302\265` for "micro" in
116 UTF-8). If this variable is set to false, bytes higher than
117 0x80 are not considered "unusual" any more. Double-quotes,
118 backslash and control characters are always escaped regardless
119 of the setting of this variable. A simple space character is
120 not considered "unusual". Many commands can output pathnames
121 completely verbatim using the `-z` option. The default value
122 is true.
125 Sets the line ending type to use in the working directory for
126 files that are marked as text (either by having the `text`
127 attribute set, or by having `text=auto` and Git auto-detecting
128 the contents as text).
129 Alternatives are 'lf', 'crlf' and 'native', which uses the platform's
130 native line ending. The default value is `native`. See
131 linkgit:gitattributes[5] for more information on end-of-line
132 conversion. Note that this value is ignored if `core.autocrlf`
133 is set to `true` or `input`.
136 If true, makes Git check if converting `CRLF` is reversible when
137 end-of-line conversion is active. Git will verify if a command
138 modifies a file in the work tree either directly or indirectly.
139 For example, committing a file followed by checking out the
140 same file should yield the original file in the work tree. If
141 this is not the case for the current setting of
142 `core.autocrlf`, Git will reject the file. The variable can
143 be set to "warn", in which case Git will only warn about an
144 irreversible conversion but continue the operation.
146CRLF conversion bears a slight chance of corrupting data.
147When it is enabled, Git will convert CRLF to LF during commit and LF to
148CRLF during checkout. A file that contains a mixture of LF and
149CRLF before the commit cannot be recreated by Git. For text
150files this is the right thing to do: it corrects line endings
151such that we have only LF line endings in the repository.
152But for binary files that are accidentally classified as text the
153conversion can corrupt data.
155If you recognize such corruption early you can easily fix it by
156setting the conversion type explicitly in .gitattributes. Right
157after committing you still have the original file in your work
158tree and this file is not yet corrupted. You can explicitly tell
159Git that this file is binary and Git will handle the file
162Unfortunately, the desired effect of cleaning up text files with
163mixed line endings and the undesired effect of corrupting binary
164files cannot be distinguished. In both cases CRLFs are removed
165in an irreversible way. For text files this is the right thing
166to do because CRLFs are line endings, while for binary files
167converting CRLFs corrupts data.
169Note, this safety check does not mean that a checkout will generate a
170file identical to the original file for a different setting of
171`core.eol` and `core.autocrlf`, but only for the current one. For
172example, a text file with `LF` would be accepted with `core.eol=lf`
173and could later be checked out with `core.eol=crlf`, in which case the
174resulting file would contain `CRLF`, although the original file
175contained `LF`. However, in both work trees the line endings would be
176consistent, that is either all `LF` or all `CRLF`, but never mixed. A
177file with mixed line endings would be reported by the `core.safecrlf`
181 Setting this variable to "true" is the same as setting
182 the `text` attribute to "auto" on all files and core.eol to "crlf".
183 Set to true if you want to have `CRLF` line endings in your
184 working directory and the repository has LF line endings.
185 This variable can be set to 'input',
186 in which case no output conversion is performed.
189 A comma and/or whitespace separated list of encodings that Git
190 performs UTF-8 round trip checks on if they are used in an
191 `working-tree-encoding` attribute (see linkgit:gitattributes[5]).
192 The default value is `SHIFT-JIS`.
195 If false, symbolic links are checked out as small plain files that
196 contain the link text. linkgit:git-update-index[1] and
197 linkgit:git-add[1] will not change the recorded type to regular
198 file. Useful on filesystems like FAT that do not support
199 symbolic links.
201The default is true, except linkgit:git-clone[1] or linkgit:git-init[1]
202will probe and set core.symlinks false if appropriate when the repository
203is created.
206 A "proxy command" to execute (as 'command host port') instead
207 of establishing direct connection to the remote server when
208 using the Git protocol for fetching. If the variable value is
209 in the "COMMAND for DOMAIN" format, the command is applied only
210 on hostnames ending with the specified domain string. This variable
211 may be set multiple times and is matched in the given order;
212 the first match wins.
214Can be overridden by the `GIT_PROXY_COMMAND` environment variable
215(which always applies universally, without the special "for"
218The special string `none` can be used as the proxy command to
219specify that no proxy be used for a given domain pattern.
220This is useful for excluding servers inside a firewall from
221proxy use, while defaulting to a common proxy for external domains.
224 If this variable is set, `git fetch` and `git push` will
225 use the specified command instead of `ssh` when they need to
226 connect to a remote system. The command is in the same form as
227 the `GIT_SSH_COMMAND` environment variable and is overridden
228 when the environment variable is set.
231 If true, Git will avoid using lstat() calls to detect if files have
232 changed by setting the "assume-unchanged" bit for those tracked files
233 which it has updated identically in both the index and working tree.
235When files are modified outside of Git, the user will need to stage
236the modified files explicitly (e.g. see 'Examples' section in
238Git will not normally detect changes to those files.
240This is useful on systems where lstat() calls are very slow, such as
241CIFS/Microsoft Windows.
243False by default.
246 Instead of the default "symref" format for HEAD
247 and other symbolic reference files, use symbolic links.
248 This is sometimes needed to work with old scripts that
249 expect HEAD to be a symbolic link.
252 When advertising tips of available history from an alternate, use the shell to
253 execute the specified command instead of linkgit:git-for-each-ref[1]. The
254 first argument is the absolute path of the alternate. Output must contain one
fd7761a1 255 hex object id per line (i.e., the same as produced by `git for-each-ref
256 --format='%(objectname)'`).
258Note that you cannot generally put `git for-each-ref` directly into the config
259value, as it does not take a repository path as an argument (but you can wrap
260the command above in a shell script).
263 When listing references from an alternate, list only references that begin
264 with the given prefix. Prefixes match as if they were given as arguments to
265 linkgit:git-for-each-ref[1]. To list multiple prefixes, separate them with
266 whitespace. If `core.alternateRefsCommand` is set, setting
267 `core.alternateRefsPrefixes` has no effect.
270 If true this repository is assumed to be 'bare' and has no
271 working directory associated with it. If this is the case a
272 number of commands that require a working directory will be
273 disabled, such as linkgit:git-add[1] or linkgit:git-merge[1].
275This setting is automatically guessed by linkgit:git-clone[1] or
276linkgit:git-init[1] when the repository was created. By default a
277repository that ends in "/.git" is assumed to be not bare (bare =
278false), while all other repositories are assumed to be bare (bare
279= true).
282 Set the path to the root of the working tree.
283 If `GIT_COMMON_DIR` environment variable is set, core.worktree
284 is ignored and not used for determining the root of working tree.
285 This can be overridden by the `GIT_WORK_TREE` environment
286 variable and the `--work-tree` command-line option.
287 The value can be an absolute path or relative to the path to
288 the .git directory, which is either specified by --git-dir
289 or GIT_DIR, or automatically discovered.
290 If --git-dir or GIT_DIR is specified but none of
291 --work-tree, GIT_WORK_TREE and core.worktree is specified,
292 the current working directory is regarded as the top level
293 of your working tree.
295Note that this variable is honored even when set in a configuration
296file in a ".git" subdirectory of a directory and its value differs
297from the latter directory (e.g. "/path/to/.git/config" has
298core.worktree set to "/different/path"), which is most likely a
299misconfiguration. Running Git commands in the "/path/to" directory will
300still use "/different/path" as the root of the work tree and can cause
301confusion unless you know what you are doing (e.g. you are creating a
302read-only snapshot of the same index to a location different from the
303repository's usual working tree).
306 Enable the reflog. Updates to a ref <ref> is logged to the file
307 "`$GIT_DIR/logs/<ref>`", by appending the new and old
308 SHA-1, the date/time and the reason of the update, but
309 only when the file exists. If this configuration
310 variable is set to `true`, missing "`$GIT_DIR/logs/<ref>`"
311 file is automatically created for branch heads (i.e. under
312 `refs/heads/`), remote refs (i.e. under `refs/remotes/`),
313 note refs (i.e. under `refs/notes/`), and the symbolic ref `HEAD`.
314 If it is set to `always`, then a missing reflog is automatically
315 created for any ref under `refs/`.
317This information can be used to determine what commit
318was the tip of a branch "2 days ago".
320This value is true by default in a repository that has
321a working directory associated with it, and false by
322default in a bare repository.
325 Internal variable identifying the repository format and layout
326 version.
329 When 'group' (or 'true'), the repository is made shareable between
330 several users in a group (making sure all the files and objects are
331 group-writable). When 'all' (or 'world' or 'everybody'), the
332 repository will be readable by all users, additionally to being
333 group-shareable. When 'umask' (or 'false'), Git will use permissions
334 reported by umask(2). When '0xxx', where '0xxx' is an octal number,
335 files in the repository will have this mode value. '0xxx' will override
336 user's umask value (whereas the other options will only override
337 requested parts of the user's umask value). Examples: '0660' will make
338 the repo read/write-able for the owner and group, but inaccessible to
339 others (equivalent to 'group' unless umask is e.g. '0022'). '0640' is a
340 repository that is group-readable but not group-writable.
341 See linkgit:git-init[1]. False by default.
344 If true, Git will warn you if the ref name you passed it is ambiguous
345 and might match multiple refs in the repository. True by default.
348 An integer -1..9, indicating a default compression level.
349 -1 is the zlib default. 0 means no compression,
350 and 1..9 are various speed/size tradeoffs, 9 being slowest.
351 If set, this provides a default to other compression variables,
352 such as `core.looseCompression` and `pack.compression`.
355 An integer -1..9, indicating the compression level for objects that
356 are not in a pack file. -1 is the zlib default. 0 means no
357 compression, and 1..9 are various speed/size tradeoffs, 9 being
358 slowest. If not set, defaults to core.compression. If that is
359 not set, defaults to 1 (best speed).
362 Number of bytes of a pack file to map into memory in a
363 single mapping operation. Larger window sizes may allow
364 your system to process a smaller number of large pack files
365 more quickly. Smaller window sizes will negatively affect
366 performance due to increased calls to the operating system's
367 memory manager, but may improve performance when accessing
368 a large number of large pack files.
370Default is 1 MiB if NO_MMAP was set at compile time, otherwise 32
371MiB on 32 bit platforms and 1 GiB on 64 bit platforms. This should
372be reasonable for all users/operating systems. You probably do
373not need to adjust this value.
375Common unit suffixes of 'k', 'm', or 'g' are supported.
378 Maximum number of bytes to map simultaneously into memory
379 from pack files. If Git needs to access more than this many
380 bytes at once to complete an operation it will unmap existing
381 regions to reclaim virtual address space within the process.
383Default is 256 MiB on 32 bit platforms and 32 TiB (effectively
384unlimited) on 64 bit platforms.
385This should be reasonable for all users/operating systems, except on
386the largest projects. You probably do not need to adjust this value.
388Common unit suffixes of 'k', 'm', or 'g' are supported.
391 Maximum number of bytes to reserve for caching base objects
392 that may be referenced by multiple deltified objects. By storing the
393 entire decompressed base objects in a cache Git is able
394 to avoid unpacking and decompressing frequently used base
395 objects multiple times.
397Default is 96 MiB on all platforms. This should be reasonable
398for all users/operating systems, except on the largest projects.
399You probably do not need to adjust this value.
401Common unit suffixes of 'k', 'm', or 'g' are supported.
404 Files larger than this size are stored deflated, without
405 attempting delta compression. Storing large files without
406 delta compression avoids excessive memory usage, at the
407 slight expense of increased disk usage. Additionally files
408 larger than this size are always treated as binary.
410Default is 512 MiB on all platforms. This should be reasonable
411for most projects as source code and other text files can still
412be delta compressed, but larger binary media files won't be.
414Common unit suffixes of 'k', 'm', or 'g' are supported.
417 Specifies the pathname to the file that contains patterns to
418 describe paths that are not meant to be tracked, in addition
68ed71b5 419 to `.gitignore` (per-directory) and `.git/info/exclude`.
420 Defaults to `$XDG_CONFIG_HOME/git/ignore`.
421 If `$XDG_CONFIG_HOME` is either not set or empty, `$HOME/.config/git/ignore`
422 is used instead. See linkgit:gitignore[5].
425 Some commands (e.g. svn and http interfaces) that interactively
426 ask for a password can be told to use an external program given
427 via the value of this variable. Can be overridden by the `GIT_ASKPASS`
428 environment variable. If not set, fall back to the value of the
429 `SSH_ASKPASS` environment variable or, failing that, a simple password
430 prompt. The external program shall be given a suitable prompt as
431 command-line argument and write the password on its STDOUT.
434 In addition to `.gitattributes` (per-directory) and
435 `.git/info/attributes`, Git looks into this file for attributes
436 (see linkgit:gitattributes[5]). Path expansions are made the same
437 way as for `core.excludesFile`. Its default value is
438 `$XDG_CONFIG_HOME/git/attributes`. If `$XDG_CONFIG_HOME` is either not
439 set or empty, `$HOME/.config/git/attributes` is used instead.
442 By default Git will look for your hooks in the
443 `$GIT_DIR/hooks` directory. Set this to different path,
444 e.g. `/etc/git/hooks`, and Git will try to find your hooks in
445 that directory, e.g. `/etc/git/hooks/pre-receive` instead of
446 in `$GIT_DIR/hooks/pre-receive`.
448The path can be either absolute or relative. A relative path is
449taken as relative to the directory where the hooks are run (see
450the "DESCRIPTION" section of linkgit:githooks[5]).
452This configuration variable is useful in cases where you'd like to
453centrally configure your Git hooks instead of configuring them on a
454per-repository basis, or as a more flexible and centralized
455alternative to having an `init.templateDir` where you've changed
456default hooks.
459 Commands such as `commit` and `tag` that let you edit
460 messages by launching an editor use the value of this
461 variable when it is set, and the environment variable
462 `GIT_EDITOR` is not set. See linkgit:git-var[1].
465 Commands such as `commit` and `tag` that let you edit
466 messages consider a line that begins with this character
467 commented, and removes them after the editor returns
468 (default '#').
470If set to "auto", `git-commit` would select a character that is not
471the beginning character of any line in existing commit messages.
474 The length of time, in milliseconds, to retry when trying to
475 lock an individual reference. Value 0 means not to retry at
476 all; -1 means to try indefinitely. Default is 100 (i.e.,
477 retry for 100ms).
480 The length of time, in milliseconds, to retry when trying to
481 lock the `packed-refs` file. Value 0 means not to retry at
482 all; -1 means to try indefinitely. Default is 1000 (i.e.,
483 retry for 1 second).
486 Text viewer for use by Git commands (e.g., 'less'). The value
487 is meant to be interpreted by the shell. The order of preference
488 is the `$GIT_PAGER` environment variable, then `core.pager`
489 configuration, then `$PAGER`, and then the default chosen at
490 compile time (usually 'less').
492When the `LESS` environment variable is unset, Git sets it to `FRX`
493(if `LESS` environment variable is set, Git does not change it at
494all). If you want to selectively override Git's default setting
495for `LESS`, you can set `core.pager` to e.g. `less -S`. This will
496be passed to the shell by Git, which will translate the final
497command to `LESS=FRX less -S`. The environment does not set the
498`S` option but the command line does, instructing less to truncate
499long lines. Similarly, setting `core.pager` to `less -+F` will
500deactivate the `F` option specified by the environment from the
501command-line, deactivating the "quit if one screen" behavior of
502`less`. One can specifically activate some flags for particular
503commands: for example, setting `pager.blame` to `less -S` enables
504line truncation only for `git blame`.
506Likewise, when the `LV` environment variable is unset, Git sets it
507to `-c`. You can override this setting by exporting `LV` with
508another value or setting `core.pager` to `lv +c`.
511 A comma separated list of common whitespace problems to
512 notice. 'git diff' will use `color.diff.whitespace` to
513 highlight them, and 'git apply --whitespace=error' will
514 consider them as errors. You can prefix `-` to disable
515 any of them (e.g. `-trailing-space`):
517* `blank-at-eol` treats trailing whitespaces at the end of the line
518 as an error (enabled by default).
519* `space-before-tab` treats a space character that appears immediately
520 before a tab character in the initial indent part of the line as an
521 error (enabled by default).
522* `indent-with-non-tab` treats a line that is indented with space
523 characters instead of the equivalent tabs as an error (not enabled by
524 default).
525* `tab-in-indent` treats a tab character in the initial indent part of
526 the line as an error (not enabled by default).
527* `blank-at-eof` treats blank lines added at the end of file as an error
528 (enabled by default).
529* `trailing-space` is a short-hand to cover both `blank-at-eol` and
530 `blank-at-eof`.
531* `cr-at-eol` treats a carriage-return at the end of line as
532 part of the line terminator, i.e. with it, `trailing-space`
533 does not trigger if the character before such a carriage-return
534 is not a whitespace (not enabled by default).
535* `tabwidth=<n>` tells how many character positions a tab occupies; this
536 is relevant for `indent-with-non-tab` and when Git fixes `tab-in-indent`
537 errors. The default tab width is 8. Allowed values are 1 to 63.
540 This boolean will enable 'fsync()' when writing object files.
542This is a total waste of time and effort on a filesystem that orders
543data writes properly, but can be useful for filesystems that do not use
544journalling (traditional UNIX filesystems) or that only journal metadata
545and not file contents (OS X's HFS+, or Linux ext3 with "data=writeback").
548 Enable parallel index preload for operations like 'git diff'
550This can speed up operations like 'git diff' and 'git status' especially
551on filesystems like NFS that have weak caching semantics and thus
552relatively high IO latencies. When enabled, Git will do the
553index comparison to the filesystem data in parallel, allowing
554overlapping IO's. Defaults to true.
557 Windows-only: comma-separated list of environment variables'
558 names that need to be unset before spawning any other process.
559 Defaults to `PERL5LIB` to account for the fact that Git for
560 Windows insists on using its own Perl interpreter.
563 You can set this to 'link', in which case a hardlink followed by
564 a delete of the source are used to make sure that object creation
565 will not overwrite existing objects.
567On some file system/operating system combinations, this is unreliable.
568Set this config setting to 'rename' there; However, This will remove the
569check that makes sure that existing object files will not get overwritten.
572 When showing commit messages, also show notes which are stored in
573 the given ref. The ref must be fully qualified. If the given
574 ref does not exist, it is not an error but means that no
575 notes should be printed.
577This setting defaults to "refs/notes/commits", and it can be overridden by
578the `GIT_NOTES_REF` environment variable. See linkgit:git-notes[1].
581 If true, then git will read the commit-graph file (if it exists)
31b1de6a 582 to parse the graph structure of commits. Defaults to true. See
583 linkgit:git-commit-graph[1] for more information.
586 If set to `false`, behave as if the `--no-replace-objects`
587 option was given on the command line. See linkgit:git[1] and
588 linkgit:git-replace[1] for more information.
591 Use the multi-pack-index file to track multiple packfiles using a
592 single index. See link:technical/multi-pack-index.html[the
593 multi-pack-index design document].
596 Enable "sparse checkout" feature. See section "Sparse checkout" in
597 linkgit:git-read-tree[1] for more information.
600 Set the length object names are abbreviated to. If
601 unspecified or set to "auto", an appropriate value is
602 computed based on the approximate number of packed objects
603 in your repository, which hopefully is enough for
604 abbreviated object names to stay unique for some time.
605 The minimum length is 4.