Documentation/git-update-index: explain splitIndex.*

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 5f5a92f7cfc3ba3592baabf0c58ff4445793a088..58326c8ff2d915a0d33570c6e48840b86411f5e8 100644 (file)
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2795,7 +2795,7 @@ splitIndex.sharedIndexExpire::
        The default value is "2.weeks.ago".
        Note that a shared index file is considered modified (for the
        purpose of expiration) each time a new split-index file is
        The default value is "2.weeks.ago".
        Note that a shared index file is considered modified (for the
        purpose of expiration) each time a new split-index file is

-       created based on it.
+       either created based on it or read from it.

        See linkgit:git-update-index[1].
 
 status.relativePaths::
        See linkgit:git-update-index[1].
 
 status.relativePaths::

diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index e091b2a409632300a8010d3e9d039568c85aa275..1579abf3c3b45f4e63f8f17746dde31a06a3a564 100644 (file)
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -163,14 +163,10 @@ may not support it yet.
 
 --split-index::
 --no-split-index::
 
 --split-index::
 --no-split-index::

-       Enable or disable split index mode. If enabled, the index is
-       split into two files, $GIT_DIR/index and $GIT_DIR/sharedindex.<SHA-1>.
-       Changes are accumulated in $GIT_DIR/index while the shared
-       index file contains all index entries stays unchanged. If
-       split-index mode is already enabled and `--split-index` is
-       given again, all changes in $GIT_DIR/index are pushed back to
-       the shared index file. This mode is designed for very large
-       indexes that take a significant amount of time to read or write.
+       Enable or disable split index mode. If split-index mode is
+       already enabled and `--split-index` is given again, all
+       changes in $GIT_DIR/index are pushed back to the shared index
+       file.

 +
 These options take effect whatever the value of the `core.splitIndex`
 configuration variable (see linkgit:git-config[1]). But a warning is
 +
 These options take effect whatever the value of the `core.splitIndex`
 configuration variable (see linkgit:git-config[1]). But a warning is


@@ -394,6 +390,31 @@ Although this bit looks similar to assume-unchanged bit, its goal is
 different from assume-unchanged bit's. Skip-worktree also takes
 precedence over assume-unchanged bit when both are set.
 
 different from assume-unchanged bit's. Skip-worktree also takes
 precedence over assume-unchanged bit when both are set.
 

+Split index
+-----------
+
+This mode is designed for repositories with very large indexes, and
+aims at reducing the time it takes to repeatedly write these indexes.
+
+In this mode, the index is split into two files, $GIT_DIR/index and
+$GIT_DIR/sharedindex.<SHA-1>. Changes are accumulated in
+$GIT_DIR/index, the split index, while the shared index file contains
+all index entries and stays unchanged.
+
+All changes in the split index are pushed back to the shared index
+file when the number of entries in the split index reaches a level
+specified by the splitIndex.maxPercentChange config variable (see
+linkgit:git-config[1]).
+
+Each time a new shared index file is created, the old shared index
+files are deleted if their modification time is older than what is
+specified by the splitIndex.sharedIndexExpire config variable (see
+linkgit:git-config[1]).
+
+To avoid deleting a shared index file that is still used, its
+modification time is updated to the current time everytime a new split
+index based on the shared index file is either created or read from.
+

 Untracked cache
 ---------------
 
 Untracked cache
 ---------------