Merge branch 'jc/rerere'
[git/git.git] / Documentation / config.txt
index 0c7cf61..838794d 100644 (file)
@@ -63,7 +63,7 @@ The values following the equals sign in variable assign are all either
 a string, an integer, or a boolean.  Boolean values may be given as yes/no,
 0/1 or true/false.  Case is not significant in boolean values, when
 converting value to the canonical form using '--bool' type specifier;
-`git-config` will ensure that the output is "true" or "false".
+'git-config' will ensure that the output is "true" or "false".
 
 String values may be entirely or partially enclosed in double quotes.
 You need to enclose variable value in double quotes if you want to
@@ -118,8 +118,8 @@ core.fileMode::
        See linkgit:git-update-index[1]. True by default.
 
 core.quotepath::
-       The commands that output paths (e.g. `ls-files`,
-       `diff`), when not given the `-z` option, will quote
+       The commands that output paths (e.g. 'ls-files',
+       'diff'), when not given the `-z` option, will quote
        "unusual" characters in the pathname by enclosing the
        pathname in a double-quote pair and with backslashes the
        same way strings in C source code are quoted.  If this
@@ -356,8 +356,8 @@ core.pager::
 
 core.whitespace::
        A comma separated list of common whitespace problems to
-       notice.  `git diff` will use `color.diff.whitespace` to
-       highlight them, and `git apply --whitespace=error` will
+       notice.  'git-diff' will use `color.diff.whitespace` to
+       highlight them, and 'git-apply --whitespace=error' will
        consider them as errors:
 +
 * `trailing-space` treats trailing whitespaces at the end of the line
@@ -372,6 +372,14 @@ core.whitespace::
   does not trigger if the character before such a carriage-return
   is not a whitespace (not enabled by default).
 
+core.fsyncobjectfiles::
+       This boolean will enable 'fsync()' when writing object files.
++
+This is a total waste of time and effort on a filesystem that orders
+data writes properly, but can be useful for filesystems that do not use
+journalling (traditional UNIX filesystems) or that only journal metadata
+and not file contents (OS X's HFS+, or Linux ext3 with "data=writeback").
+
 alias.*::
        Command aliases for the linkgit:git[1] command wrapper - e.g.
        after defining "alias.last = cat-file commit HEAD", the invocation
@@ -388,11 +396,11 @@ it will be treated as a shell command.  For example, defining
 "gitk --all --not ORIG_HEAD".
 
 apply.whitespace::
-       Tells `git-apply` how to handle whitespaces, in the same way
+       Tells 'git-apply' how to handle whitespaces, in the same way
        as the '--whitespace' option. See linkgit:git-apply[1].
 
 branch.autosetupmerge::
-       Tells `git-branch` and `git-checkout` to setup new branches
+       Tells 'git-branch' and 'git-checkout' to setup new branches
        so that linkgit:git-pull[1] will appropriately merge from the
        starting point branch. Note that even if this option is not set,
        this behavior can be chosen per-branch using the `--track`
@@ -403,7 +411,7 @@ branch.autosetupmerge::
        branch. This option defaults to true.
 
 branch.autosetuprebase::
-       When a new branch is created with `git-branch` or `git-checkout`
+       When a new branch is created with 'git-branch' or 'git-checkout'
        that tracks another branch, this variable tells git to set
        up pull to rebase instead of merge (see "branch.<name>.rebase").
        When `never`, rebase is never automatically set to true.
@@ -418,20 +426,20 @@ branch.autosetuprebase::
        This option defaults to never.
 
 branch.<name>.remote::
-       When in branch <name>, it tells `git fetch` which remote to fetch.
-       If this option is not given, `git fetch` defaults to remote "origin".
+       When in branch <name>, it tells 'git-fetch' which remote to fetch.
+       If this option is not given, 'git-fetch' defaults to remote "origin".
 
 branch.<name>.merge::
-       When in branch <name>, it tells `git fetch` the default
+       When in branch <name>, it tells 'git-fetch' the default
        refspec to be marked for merging in FETCH_HEAD. The value is
        handled like the remote part of a refspec, and must match a
        ref which is fetched from the remote given by
        "branch.<name>.remote".
-       The merge information is used by `git pull` (which at first calls
-       `git fetch`) to lookup the default branch for merging. Without
-       this option, `git pull` defaults to merge the first refspec fetched.
+       The merge information is used by 'git-pull' (which at first calls
+       'git-fetch') to lookup the default branch for merging. Without
+       this option, 'git-pull' defaults to merge the first refspec fetched.
        Specify multiple values to get an octopus merge.
-       If you wish to setup `git pull` so that it merges into <name> from
+       If you wish to setup 'git-pull' so that it merges into <name> from
        another branch in the local repository, you can point
        branch.<name>.merge to the desired branch, and use the special setting
        `.` (a period) for branch.<name>.remote.
@@ -500,12 +508,12 @@ color.diff.<slot>::
 
 color.interactive::
        When set to `always`, always use colors for interactive prompts
-       and displays (such as those used by "git add --interactive").
+       and displays (such as those used by "git-add --interactive").
        When false (or `never`), never.  When set to `true` or `auto`, use
        colors only when the output is to the terminal. Defaults to false.
 
 color.interactive.<slot>::
-       Use customized color for `git add --interactive`
+       Use customized color for 'git-add --interactive'
        output. `<slot>` may be `prompt`, `header`, or `help`, for
        three distinct types of normal output from interactive
        programs.  The values of these variables may be specified as
@@ -542,14 +550,14 @@ color.ui::
        take precedence over this setting. Defaults to false.
 
 diff.autorefreshindex::
-       When using `git diff` to compare with work tree
+       When using 'git-diff' to compare with work tree
        files, do not consider stat-only change as changed.
        Instead, silently run `git update-index --refresh` to
        update the cached stat information for paths whose
        contents in the work tree match the contents in the
        index.  This option defaults to true.  Note that this
-       affects only `git diff` Porcelain, and not lower level
-       `diff` commands, such as `git diff-files`.
+       affects only 'git-diff' Porcelain, and not lower level
+       'diff' commands, such as 'git-diff-files'.
 
 diff.external::
        If this config variable is set, diff generation is not
@@ -560,7 +568,7 @@ diff.external::
 
 diff.renameLimit::
        The number of files to consider when performing the copy/rename
-       detection; equivalent to the git diff option '-l'.
+       detection; equivalent to the 'git-diff' option '-l'.
 
 diff.renames::
        Tells git to detect renames.  If set to any boolean value, it
@@ -600,7 +608,7 @@ format.pretty::
 
 gc.aggressiveWindow::
        The window size parameter used in the delta compression
-       algorithm used by 'git gc --aggressive'.  This defaults
+       algorithm used by 'git-gc --aggressive'.  This defaults
        to 10.
 
 gc.auto::
@@ -617,37 +625,37 @@ gc.autopacklimit::
        default value is 50.  Setting this to 0 disables it.
 
 gc.packrefs::
-       `git gc` does not run `git pack-refs` in a bare repository by
+       'git-gc' does not run `git pack-refs` in a bare repository by
        default so that older dumb-transport clients can still fetch
-       from the repository.  Setting this to `true` lets `git
-       gc` to run `git pack-refs`.  Setting this to `false` tells
-       `git gc` never to run `git pack-refs`. The default setting is
+       from the repository.  Setting this to `true` lets 'git-gc'
+       to run `git pack-refs`.  Setting this to `false` tells
+       'git-gc' never to run `git pack-refs`. The default setting is
        `notbare`. Enable it only when you know you do not have to
        support such clients.  The default setting will change to `true`
        at some stage, and setting this to `false` will continue to
-       prevent `git pack-refs` from being run from `git gc`.
+       prevent `git pack-refs` from being run from 'git-gc'.
 
 gc.pruneexpire::
-       When `git gc` is run, it will call `prune --expire 2.weeks.ago`.
+       When 'git-gc' is run, it will call 'prune --expire 2.weeks.ago'.
        Override the grace period with this config variable.
 
 gc.reflogexpire::
-       `git reflog expire` removes reflog entries older than
+       'git-reflog expire' removes reflog entries older than
        this time; defaults to 90 days.
 
 gc.reflogexpireunreachable::
-       `git reflog expire` removes reflog entries older than
+       'git-reflog expire' removes reflog entries older than
        this time and are not reachable from the current tip;
        defaults to 30 days.
 
 gc.rerereresolved::
        Records of conflicted merge you resolved earlier are
-       kept for this many days when `git rerere gc` is run.
+       kept for this many days when 'git-rerere gc' is run.
        The default is 60 days.  See linkgit:git-rerere[1].
 
 gc.rerereunresolved::
        Records of conflicted merge you have not resolved are
-       kept for this many days when `git rerere gc` is run.
+       kept for this many days when 'git-rerere gc' is run.
        The default is 15 days.  See linkgit:git-rerere[1].
 
 rerere.autoupdate::
@@ -818,7 +826,7 @@ i18n.commitEncoding::
 
 i18n.logOutputEncoding::
        Character encoding the commit messages are converted to when
-       running `git-log` and friends.
+       running 'git-log' and friends.
 
 instaweb.browser::
        Specify the program that will be used to browse your working
@@ -841,7 +849,7 @@ instaweb.port::
 
 log.date::
        Set default date-time mode for the log command. Setting log.date
-       value is similar to using git log's --date option. The value is one of
+       value is similar to using 'git-log'\'s --date option. The value is one of the
        following alternatives: {relative,local,default,iso,rfc,short}.
        See linkgit:git-log[1].
 
@@ -942,9 +950,17 @@ pack.indexVersion::
        legacy pack index used by Git versions prior to 1.5.2, and 2 for
        the new pack index with capabilities for packs larger than 4 GB
        as well as proper protection against the repacking of corrupted
-       packs.  Version 2 is selected and this config option ignored
-       whenever the corresponding pack is larger than 2 GB.  Otherwise
-       the default is 1.
+       packs.  Version 2 is the default.  Note that version 2 is enforced
+       and this config option ignored whenever the corresponding pack is
+       larger than 2 GB.
++
+If you have an old git that does not understand the version 2 `{asterisk}.idx` file,
+cloning or fetching over a non native protocol (e.g. "http" and "rsync")
+that will copy both `{asterisk}.pack` file and corresponding `{asterisk}.idx` file from the
+other side may give you a repository that cannot be accessed with your
+older version of git. If the `{asterisk}.pack` file is smaller than 2 GB, however,
+you can use linkgit:git-index-pack[1] on the *.pack file to regenerate
+the `{asterisk}.idx` file.
 
 pack.packSizeLimit::
        The default maximum size of a pack.  This setting only affects
@@ -1001,12 +1017,12 @@ remotes.<group>::
        <group>".  See linkgit:git-remote[1].
 
 repack.usedeltabaseoffset::
-       Allow linkgit:git-repack[1] to create packs that uses
-       delta-base offset.  Defaults to false.
-
-show.difftree::
-       The default linkgit:git-diff-tree[1] arguments to be used
-       for linkgit:git-show[1].
+       By default, linkgit:git-repack[1] creates packs that use
+       delta-base offset. If you need to share your repository with
+       git older than version 1.4.4, either directly or via a dumb
+       protocol such as http, then you need to set this option to
+       "false" and repack. Access from old git versions over the
+       native protocol are unaffected by this option.
 
 showbranch.default::
        The default set of branches for linkgit:git-show-branch[1].
@@ -1018,6 +1034,25 @@ status.relativePaths::
        relative to the repository root (this was the default for git
        prior to v1.5.4).
 
+status.showUntrackedFiles::
+       By default, linkgit:git-status[1] and linkgit:git-commit[1] show
+       files which are not currently tracked by Git. Directories which
+       contain only untracked files, are shown with the directory name
+       only. Showing untracked files means that Git needs to lstat() all
+       all the files in the whole repository, which might be slow on some
+       systems. So, this variable controls how the commands displays
+       the untracked files. Possible values are:
++
+--
+       - 'no'     - Show no untracked files
+       - 'normal' - Shows untracked files and directories
+       - 'all'    - Shows also individual files in untracked directories.
+--
++
+If this variable is not specified, it defaults to 'normal'.
+This variable can be overridden with the -u|--untracked-files option
+of linkgit:git-status[1] and linkgit:git-commit[1].
+
 tar.umask::
        This variable can be used to restrict the permission bits of
        tar archive entries.  The default is 0002, which turns off the
@@ -1053,10 +1088,6 @@ user.signingkey::
        unchanged to gpg's --local-user parameter, so you may specify a key
        using any method that gpg supports.
 
-whatchanged.difftree::
-       The default linkgit:git-diff-tree[1] arguments to be used
-       for linkgit:git-whatchanged[1].
-
 imap::
        The configuration variables in the 'imap' section are described
        in linkgit:git-imap-send[1].