Re: [PATCH v3 21/21] Documentation/git-update-index: explain splitIndex.*

On Tue, Dec 27, 2016 at 8:13 PM, Junio C Hamano [off-list ref] wrote:

Christian Couder [off-list ref] writes:

quoted

 --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.

In the world after this series that introduced the percentage-based
auto consolidation, it smells strange, or even illogical, that index
is un-split after doing this:

    $ git update-index --split-index
    $ git update-index --split-index

Before this series, it may have been a quick and dirty way to force
consolidating the split index without totally disabling the feature,
i.e. it would have looked more like

    $ git update-index --split-index
    ... work work work to accumulate more modifications
    ... consolidate into one --- there was no other way than
    ... disabling it temporarily
    $ git update-index --no-split-index
    ... but the user likes the feature so re-enable it.
    $ git update-index --split-index

which I guess is where this strange behaviour comes from.

It may be something we need to fix to unconfuse the end-users after
this series lands.  Even though "first disable and then re-enable"
takes two commands (as opposed to one), it is far more logical.  And
the percentage-based auto consolidation feature is meant to reduce
the need for manual consolidation, so it probably makes sense to
remove this illogical feature.

Yeah, I tend to agree that this feature could be removed later. Though
before removing it, I'd like to hear Duy's opinion on this as he
created the feature in the first place.

quoted

@@ -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.

+Split index
+-----------
+
+This mode is designed for very large indexes that take a significant
+amount of time to read or write.

This is not a new problem, but it probably is incorrect to say "to
read or write".  It saves time by not rewriting the whole thing but
instead write out only the updated bits.  You'd still read the whole
thing while populating the in-core index from the disk, and if
anything, you'd probably spend _more_ cycles because you'd essentially
be reading the base and then reading the delta to apply on top.

Ok, then what about:

+This mode is designed for repositories with very large indexes, and aims
+at reducing the time it takes to repeatedly write these indexes.

quoted

+To avoid deleting a shared index file that is still used, its mtime is
+updated to the current time everytime a new split index based on the
+shared index file is either created or read from.

The same comment on the mention of "mtime" in another patch applies
here as well.

Ok, I will use "modification time" instead of "mtime".

Thanks.