Documentation for update-index

[Rasmus Villemoes]

The man page for update-index says

   -q
   Quiet. If --refresh finds that the index needs an update,
the default behavior is to error out. This
   option makes git update-index continue anyway.

   --ignore-submodules
   Do not try to update submodules. This option is only
respected when passed before --refresh.


However, it seems that the "This option is only respected when passed
before --refresh." also applies to -q (and --unmerged); at least I get
different results from

  git update-index -q --refresh
  git update-index --refresh -q

>From the documentation, that doesn't seem to be intentional, but the
code in update-index.c seems to handle -q, --ignore-submodules,
--ignore-missing and --unmerged the same way.

Rasmus

[PATCH v5 09/22] Documentation/git-update-index: talk about core.splitIndex config var

[Christian Couder]

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
 Documentation/git-update-index.txt | 6 ++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index 7386c93162..e091b2a409 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -171,6 +171,12 @@ may not support it yet.
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.
++
+These options take effect whatever the value of the `core.splitIndex`
+configuration variable (see linkgit:git-config[1]). But a warning is
+emitted when the change goes against the configured value, as the
+configured value will take effect next time the index is read and this
+will remove the intended effect of the option.
 
 --untracked-cache::
 --no-untracked-cache::
-- 
2.12.0.206.g74921e51d6.dirty

[PATCH v5 22/22] Documentation/git-update-index: explain splitIndex.*

[Christian Couder]

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
 Documentation/config.txt   |  2 +-
 Documentation/git-update-index.txt | 37 +
 2 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 2afd5d982b..24ed9c476d 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2873,7 +2873,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
-   created based on it.
+   either created based on it or read from it.
See linkgit:git-update-index[1].
 
 status.relativePaths::
diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index e091b2a409..1579abf3c3 100644
--- 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::
-   Enable or disable split index mode. If enabled, the index is
-   split into two files, $GIT_DIR/index and $GIT_DIR/sharedindex..
-   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
@@ -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 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.. 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
 ---
 
-- 
2.12.0.206.g74921e51d6.dirty

[PATCH v4 22/22] Documentation/git-update-index: explain splitIndex.*

[Christian Couder]

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
 Documentation/config.txt   |  2 +-
 Documentation/git-update-index.txt | 37 +
 2 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 0e9982c5e3..2ccb053d92 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2853,7 +2853,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
-   created based on it.
+   either created based on it or read from it.
See linkgit:git-update-index[1].
 
 status.relativePaths::
diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index e091b2a409..1579abf3c3 100644
--- 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::
-   Enable or disable split index mode. If enabled, the index is
-   split into two files, $GIT_DIR/index and $GIT_DIR/sharedindex..
-   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
@@ -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 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.. 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
 ---
 
-- 
2.12.0.22.g0672473d40

[PATCH v4 09/22] Documentation/git-update-index: talk about core.splitIndex config var

[Christian Couder]

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
 Documentation/git-update-index.txt | 6 ++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index 7386c93162..e091b2a409 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -171,6 +171,12 @@ may not support it yet.
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.
++
+These options take effect whatever the value of the `core.splitIndex`
+configuration variable (see linkgit:git-config[1]). But a warning is
+emitted when the change goes against the configured value, as the
+configured value will take effect next time the index is read and this
+will remove the intended effect of the option.
 
 --untracked-cache::
 --no-untracked-cache::
-- 
2.12.0.22.g0672473d40

Re: [PATCH v3 08/21] Documentation/git-update-index: talk about core.splitIndex config var

[Junio C Hamano]

Christian Couder  writes:

>>> Perhaps we should declare that config will be the one and only way
>>> in the future and start deprecating the command line option way.
>>> That will remove the need for two to interact with each other.
>
> That would be my preferred solution as I think it is the simplest in
> the end for users.
> Also, as Duy wrote above, one can always use something like "git -c
> core.splitIndex= ...", which by the way can work for any command, not
> just "update-index".
>
> Anyway we would have to introduce core.splitIndex first, and it
> wouldn't make sense to have a different behavior between
> --[no-]split-index and --[no-]untracked-cache in the meantime before
> they are deprecated and eventually removed.
>
> So let's just go with the implementation in this series, which is
> similar to --[no-]untracked-cache, and let's plan to deprecate
> --[no-]split-index and --[no-]untracked-cache in a later patch series.

Sounds like we have a plan.  Thanks.

Re: [PATCH v3 08/21] Documentation/git-update-index: talk about core.splitIndex config var

[Christian Couder]

On Mon, Jan 9, 2017 at 12:18 PM, Duy Nguyen  wrote:
> On Sun, Jan 8, 2017 at 4:38 AM, Junio C Hamano  wrote:
>> Christian Couder  writes:
>>
>>> It feels strange that when I do things one way, you suggest another
>>> way, and the next time in a similar situation when I do things the way
>>> you suggested previously, then you suggest the way I did it initially
>>> the first time...
>>
>> Perhaps because neither is quite satisfactory and I am being forced
>> to choose between the two unsatifactory designs?  In any case, I
>> mostly am and was pointing out the issues and not saying the other
>> one is the most preferred solution in these threads.
>>
>> I think there should just be one authoritative source of the truth,
>
> Either that, or we make sure all sources of truth are consistent. In
> this case, 'update --split-index' could update core.splitIndex if it
> finds that the config tells a different story. As a plumbing though, I
> rather leave update-index do simple things, even if it means the user
> has to clean up after it (or before it) with "git config -unset
> core.splitIndex". Another option is refuse to execute --split-index in
> the presence of (conflicting) core.splitIndex. We kind of force the
> user to keep all sources of truth consistent this way while leaving a
> back door ("git -c core.splitIndex= update-index") for those who need
> tools to recover from a bad case.
>
>> and I have always thought it should be the bit set in the index file
>> when the command line option is used, because that was the way the
>> feature was introduced first and I am superstitious about end-user
>> inertia.  And from that point of view, no matter how you make this
>> new "config" thing interact with it, it would always give a strange
>> and unsatifactory end-user experience, at least to me.
>>
>> Perhaps we should declare that config will be the one and only way
>> in the future and start deprecating the command line option way.
>> That will remove the need for two to interact with each other.

That would be my preferred solution as I think it is the simplest in
the end for users.
Also, as Duy wrote above, one can always use something like "git -c
core.splitIndex= ...", which by the way can work for any command, not
just "update-index".

Anyway we would have to introduce core.splitIndex first, and it
wouldn't make sense to have a different behavior between
--[no-]split-index and --[no-]untracked-cache in the meantime before
they are deprecated and eventually removed.

So let's just go with the implementation in this series, which is
similar to --[no-]untracked-cache, and let's plan to deprecate
--[no-]split-index and --[no-]untracked-cache in a later patch series.

Re: [PATCH v3 08/21] Documentation/git-update-index: talk about core.splitIndex config var

[Duy Nguyen]

On Sun, Jan 8, 2017 at 4:38 AM, Junio C Hamano  wrote:
> Christian Couder  writes:
>
>> It feels strange that when I do things one way, you suggest another
>> way, and the next time in a similar situation when I do things the way
>> you suggested previously, then you suggest the way I did it initially
>> the first time...
>
> Perhaps because neither is quite satisfactory and I am being forced
> to choose between the two unsatifactory designs?  In any case, I
> mostly am and was pointing out the issues and not saying the other
> one is the most preferred solution in these threads.
>
> I think there should just be one authoritative source of the truth,

Either that, or we make sure all sources of truth are consistent. In
this case, 'update --split-index' could update core.splitIndex if it
finds that the config tells a different story. As a plumbing though, I
rather leave update-index do simple things, even if it means the user
has to clean up after it (or before it) with "git config -unset
core.splitIndex". Another option is refuse to execute --split-index in
the presence of (conflicting) core.splitIndex. We kind of force the
user to keep all sources of truth consistent this way while leaving a
back door ("git -c core.splitIndex= update-index") for those who need
tools to recover from a bad case.

> and I have always thought it should be the bit set in the index file
> when the command line option is used, because that was the way the
> feature was introduced first and I am superstitious about end-user
> inertia.  And from that point of view, no matter how you make this
> new "config" thing interact with it, it would always give a strange
> and unsatifactory end-user experience, at least to me.
>
> Perhaps we should declare that config will be the one and only way
> in the future and start deprecating the command line option way.
> That will remove the need for two to interact with each other.
>
> I dunno.



-- 
Duy

Re: [PATCH v3 08/21] Documentation/git-update-index: talk about core.splitIndex config var

[Junio C Hamano]

Christian Couder  writes:

> It feels strange that when I do things one way, you suggest another
> way, and the next time in a similar situation when I do things the way
> you suggested previously, then you suggest the way I did it initially
> the first time...

Perhaps because neither is quite satisfactory and I am being forced
to choose between the two unsatifactory designs?  In any case, I
mostly am and was pointing out the issues and not saying the other
one is the most preferred solution in these threads.

I think there should just be one authoritative source of the truth,
and I have always thought it should be the bit set in the index file
when the command line option is used, because that was the way the
feature was introduced first and I am superstitious about end-user
inertia.  And from that point of view, no matter how you make this
new "config" thing interact with it, it would always give a strange
and unsatifactory end-user experience, at least to me.

Perhaps we should declare that config will be the one and only way
in the future and start deprecating the command line option way.
That will remove the need for two to interact with each other.

I dunno.

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

[Christian Couder]

On Tue, Dec 27, 2016 at 8:13 PM, Junio C Hamano  wrote:
> Christian Couder  writes:
>
>>  --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..
>> - 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.

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

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

Re: [PATCH v3 08/21] Documentation/git-update-index: talk about core.splitIndex config var

[Christian Couder]

On Tue, Dec 27, 2016 at 8:07 PM, Junio C Hamano <gits...@pobox.com> wrote:
> Christian Couder <christian.cou...@gmail.com> writes:
>
>> Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
>> ---
>>  Documentation/git-update-index.txt | 6 ++
>>  1 file changed, 6 insertions(+)
>>
>> diff --git a/Documentation/git-update-index.txt 
>> b/Documentation/git-update-index.txt
>> index 7386c93162..e091b2a409 100644
>> --- a/Documentation/git-update-index.txt
>> +++ b/Documentation/git-update-index.txt
>> @@ -171,6 +171,12 @@ may not support it yet.
>>   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.
>> ++
>> +These options take effect whatever the value of the `core.splitIndex`
>> +configuration variable (see linkgit:git-config[1]).
>
> Doesn't the "whatever..." clause in this sentence lack its verb
> (presumably, "is", right after "variable")?

I think that it is ok to have no verb here. My preferred online
dictionary (http://www.wordreference.com/enfr/whatever) gives "We'll
try to free the hostage whatever the cost." as an example with no
verb, though I am not a native speaker.

Also note that I mostly copied what I had already written for
--(no-)untracked-cache:

--untracked-cache::
--no-untracked-cache::
Enable or disable untracked cache feature. Please use
`--test-untracked-cache` before enabling it.
+
These options take effect whatever the value of the `core.untrackedCache`
configuration variable (see linkgit:git-config[1]). But a warning is
emitted when the change goes against the configured value, as the
configured value will take effect next time the index is read and this
will remove the intended effect of the option.

>> +emitted when the change goes against the configured value, as the
>> +configured value will take effect next time the index is read and this
>> +will remove the intended effect of the option.
>
> It feels somewhat strange to see a warning in this case.

We already discussed the warning issue for --(no-)untracked-cache, and
I am just following the conclusions of that previous discussion about
--(no-)untracked-cache. See the end of this message where you
suggested the warning:

https://public-inbox.org/git/xmqqlh8cg9y2@gitster.mtv.corp.google.com/

> If the user configures the system to usually do X, and issues a
> command that explicitly does Y (or "not-X"), we do not warn for the
> command invocation if it is a single-shot operation.  That's the
> usual "command line overrides configuration" an end-user expects.
>
> I think you made this deviate from the usual end-user expectation
> because it is unpredictable when the configuration kicks in the next
> time to undo the effect of this command line request.  And I agree
> that it is a very un-nice thing to do to the users if we did not
> warn here, if we are to keep that unpredictableness.

I also think it would be strange and user unfriendly for
--untracked-cache and --split-index to behave differently, and I am
reluctant at this point to rework the way it works for
--untracked-cache.

> But stepping back a bit, we know the user's intention is that with
> "--split-index" the user wants to use the split index, even though
> the user may have configuration not to use the split index.  Don't
> we want to honor that intention?  In order to honor that intention
> without getting confused by the configured variable to tell us not
> to split, another way is to destroy that unpredictableness.  For
> that, shouldn't we automatically remove the configuration that says
> "do not split" (by perhaps set it to "do split")?  Doing so still
> may need a warning that says "we disabled your previously configured
> setting while at it", but it would be much better than a warning
> message that essentially says "we do it once, but we will disobey
> you at an unpredictable time", I would think.

I wanted to do that for --untracked-cache around one year ago but in
the following message:

https://public-inbox.org/git/xmqqsi3ckadi@gitster.mtv.corp.google.com/

you wrote the following:

"Why is it a good idea to allow an explicit operation from the
command line to muck with the configuration?  If the user wants to
change the configuration permanently, "git config" has been there
for the purpose for all the configuration variables to do so for
almost forever.  Why is it a good idea to make this variable so
special that the user does not have to use "git config" but disable
or enable it in some other way?"

It feels strange that when I do things one way, you suggest another
way, and the next time in a similar situation when I do things the way
you suggested previously, then you suggest the way I did it initially
the first time...

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

[Junio C Hamano]

Christian Couder  writes:

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

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

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

Re: [PATCH v3 08/21] Documentation/git-update-index: talk about core.splitIndex config var

[Junio C Hamano]

Christian Couder <christian.cou...@gmail.com> writes:

> Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
> ---
>  Documentation/git-update-index.txt | 6 ++
>  1 file changed, 6 insertions(+)
>
> diff --git a/Documentation/git-update-index.txt 
> b/Documentation/git-update-index.txt
> index 7386c93162..e091b2a409 100644
> --- a/Documentation/git-update-index.txt
> +++ b/Documentation/git-update-index.txt
> @@ -171,6 +171,12 @@ may not support it yet.
>   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.
> ++
> +These options take effect whatever the value of the `core.splitIndex`
> +configuration variable (see linkgit:git-config[1]).

Doesn't the "whatever..." clause in this sentence lack its verb
(presumably, "is", right after "variable")?

> +emitted when the change goes against the configured value, as the
> +configured value will take effect next time the index is read and this
> +will remove the intended effect of the option.

It feels somewhat strange to see a warning in this case. 

If the user configures the system to usually do X, and issues a
command that explicitly does Y (or "not-X"), we do not warn for the
command invocation if it is a single-shot operation.  That's the
usual "command line overrides configuration" an end-user expects.

I think you made this deviate from the usual end-user expectation
because it is unpredictable when the configuration kicks in the next
time to undo the effect of this command line request.  And I agree
that it is a very un-nice thing to do to the users if we did not
warn here, if we are to keep that unpredictableness.

But stepping back a bit, we know the user's intention is that with
"--split-index" the user wants to use the split index, even though
the user may have configuration not to use the split index.  Don't
we want to honor that intention?  In order to honor that intention
without getting confused by the configured variable to tell us not
to split, another way is to destroy that unpredictableness.  For
that, shouldn't we automatically remove the configuration that says
"do not split" (by perhaps set it to "do split")?  Doing so still
may need a warning that says "we disabled your previously configured
setting while at it", but it would be much better than a warning
message that essentially says "we do it once, but we will disobey
you at an unpredictable time", I would think.

[PATCH v3 08/21] Documentation/git-update-index: talk about core.splitIndex config var

[Christian Couder]

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
 Documentation/git-update-index.txt | 6 ++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index 7386c93162..e091b2a409 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -171,6 +171,12 @@ may not support it yet.
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.
++
+These options take effect whatever the value of the `core.splitIndex`
+configuration variable (see linkgit:git-config[1]). But a warning is
+emitted when the change goes against the configured value, as the
+configured value will take effect next time the index is read and this
+will remove the intended effect of the option.
 
 --untracked-cache::
 --no-untracked-cache::
-- 
2.11.0.209.gda91e66374.dirty

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

[Christian Couder]

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
 Documentation/config.txt   |  6 +++---
 Documentation/git-update-index.txt | 37 +
 2 files changed, 32 insertions(+), 11 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 24e771d22e..87a570cf88 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2792,9 +2792,9 @@ splitIndex.sharedIndexExpire::
index file is created. The value "now" expires all entries
immediately, and "never" suppresses expiration altogether.
The default value is "one.week.ago".
-   Note that each time a new split-index file is created, the
-   mtime of the related shared index file is updated to the
-   current time.
+   Note that each time a split index based on a shared index file
+   is either created or read from, the mtime of the shared index
+   file is updated to the current time.
See linkgit:git-update-index[1].
 
 status.relativePaths::
diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index e091b2a409..46c953b2f2 100644
--- 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::
-   Enable or disable split index mode. If enabled, the index is
-   split into two files, $GIT_DIR/index and $GIT_DIR/sharedindex..
-   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
@@ -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.
+
+In this mode, the index is split into two files, $GIT_DIR/index and
+$GIT_DIR/sharedindex.. 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 mtime 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 mtime 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
 ---
 
-- 
2.11.0.209.gda91e66374.dirty

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

[Christian Couder]

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
 Documentation/config.txt   |  6 +++---
 Documentation/git-update-index.txt | 37 +
 2 files changed, 32 insertions(+), 11 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 8fbef25cb1..52a3cac4ff 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2782,9 +2782,9 @@ splitIndex.sharedIndexExpire::
index file is created. The value "now" expires all entries
immediately, and "never" suppresses expiration altogether.
The default value is "one.week.ago".
-   Note that each time a new split-index file is created, the
-   mtime of the related shared index file is updated to the
-   current time.
+   Note that each time a split index based on a shared index file
+   is either created or read from, the mtime of the shared index
+   file is updated to the current time.
See linkgit:git-update-index[1].
 
 status.relativePaths::
diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index e091b2a409..46c953b2f2 100644
--- 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::
-   Enable or disable split index mode. If enabled, the index is
-   split into two files, $GIT_DIR/index and $GIT_DIR/sharedindex..
-   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
@@ -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.
+
+In this mode, the index is split into two files, $GIT_DIR/index and
+$GIT_DIR/sharedindex.. 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 mtime 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 mtime 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
 ---
 
-- 
2.11.0.49.g2414764.dirty

[PATCH v2 08/21] Documentation/git-update-index: talk about core.splitIndex config var

[Christian Couder]

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
 Documentation/git-update-index.txt | 6 ++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index 7386c93162..e091b2a409 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -171,6 +171,12 @@ may not support it yet.
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.
++
+These options take effect whatever the value of the `core.splitIndex`
+configuration variable (see linkgit:git-config[1]). But a warning is
+emitted when the change goes against the configured value, as the
+configured value will take effect next time the index is read and this
+will remove the intended effect of the option.
 
 --untracked-cache::
 --no-untracked-cache::
-- 
2.11.0.49.g2414764.dirty

[PATCH v1 08/19] Documentation/git-update-index: talk about core.splitIndex config var

[Christian Couder]

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
 Documentation/git-update-index.txt | 6 ++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index 7386c93..e091b2a 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -171,6 +171,12 @@ may not support it yet.
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.
++
+These options take effect whatever the value of the `core.splitIndex`
+configuration variable (see linkgit:git-config[1]). But a warning is
+emitted when the change goes against the configured value, as the
+configured value will take effect next time the index is read and this
+will remove the intended effect of the option.
 
 --untracked-cache::
 --no-untracked-cache::
-- 
2.10.1.462.g7e1e03a

[PATCH v1 19/19] Documentation/git-update-index: explain splitIndex.*

[Christian Couder]

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
 Documentation/git-update-index.txt | 33 +
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index e091b2a..635d157 100644
--- 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::
-   Enable or disable split index mode. If enabled, the index is
-   split into two files, $GIT_DIR/index and $GIT_DIR/sharedindex..
-   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
@@ -394,6 +390,27 @@ 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.
+
+In this mode, the index is split into two files, $GIT_DIR/index and
+$GIT_DIR/sharedindex.. 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 they are older than what is specified by the
+splitIndex.sharedIndexExpire config variable (see
+linkgit:git-config[1]).
+
 Untracked cache
 ---
 
-- 
2.10.1.462.g7e1e03a

[RFC/PATCH 6/8] Documentation/git-update-index: talk about core.splitIndex config var

[Christian Couder]

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
 Documentation/git-update-index.txt | 6 ++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index c6cbed1..2293140 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -171,6 +171,12 @@ may not support it yet.
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.
++
+These options take effect whatever the value of the `core.splitIndex`
+configuration variable (see linkgit:git-config[1]). But a warning is
+emitted when the change goes against the configured value, as the
+configured value will take effect next time the index is read and this
+will remove the intended effect of the option.
 
 --untracked-cache::
 --no-untracked-cache::
-- 
2.9.0.250.g7087ccc.dirty

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v4] Documentation/git-update-index: add missing opts to synopsis

[Junio C Hamano]

Christian Couder <christian.cou...@gmail.com> writes:

> On Wed, Nov 25, 2015 at 10:30 AM, Christian Couder
> <christian.cou...@gmail.com> wrote:
>> Split index related options should appear in the 'SYNOPSIS'
>> section.
>>
>> These options are already documented in the 'OPTIONS' section.
>>
>> Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
>> ---
>> This v4 contains only the split-index options and applies on top
>> of the new master that already contains the untracked-cache options.
>
> It looks like this patch has not been applied.
> Maybe I should have given it a different title to avoid confusion with
> a previous patch that added [--[no-|force-]untracked-cache] in the
> SYNOPSIS.

It indeed seems that this was lost in the noise.




>
>>  Documentation/git-update-index.txt | 1 +
>>  1 file changed, 1 insertion(+)
>>
>> diff --git a/Documentation/git-update-index.txt 
>> b/Documentation/git-update-index.txt
>> index 3df9c26..f4e5a85 100644
>> --- a/Documentation/git-update-index.txt
>> +++ b/Documentation/git-update-index.txt
>> @@ -17,6 +17,7 @@ SYNOPSIS
>>  [--[no-]assume-unchanged]
>>  [--[no-]skip-worktree]
>>  [--ignore-submodules]
>> +[--[no-]split-index]
>>  [--[no-|force-]untracked-cache]
>>  [--really-refresh] [--unresolve] [--again | -g]
>>  [--info-only] [--index-info]
>> --
>> 2.6.3.380.g494b52d
>>
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v4] Documentation/git-update-index: add missing opts to synopsis

[Christian Couder]

On Wed, Nov 25, 2015 at 10:30 AM, Christian Couder
<christian.cou...@gmail.com> wrote:
> Split index related options should appear in the 'SYNOPSIS'
> section.
>
> These options are already documented in the 'OPTIONS' section.
>
> Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
> ---
> This v4 contains only the split-index options and applies on top
> of the new master that already contains the untracked-cache options.

It looks like this patch has not been applied.
Maybe I should have given it a different title to avoid confusion with
a previous patch that added [--[no-|force-]untracked-cache] in the
SYNOPSIS.

>  Documentation/git-update-index.txt | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git a/Documentation/git-update-index.txt 
> b/Documentation/git-update-index.txt
> index 3df9c26..f4e5a85 100644
> --- a/Documentation/git-update-index.txt
> +++ b/Documentation/git-update-index.txt
> @@ -17,6 +17,7 @@ SYNOPSIS
>  [--[no-]assume-unchanged]
>  [--[no-]skip-worktree]
>  [--ignore-submodules]
> +[--[no-]split-index]
>  [--[no-|force-]untracked-cache]
>  [--really-refresh] [--unresolve] [--again | -g]
>  [--info-only] [--index-info]
> --
> 2.6.3.380.g494b52d
>
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] Documentation/git-update-index: add missing opts to synopsys

[Christian Couder]

On Wed, Nov 25, 2015 at 10:03 AM, Jeff King  wrote:
> On Wed, Nov 25, 2015 at 07:53:12AM +0100, Christian Couder wrote:
>
>> Untracked cache and split index related options should appear
>> in the 'SYNOPSIS' section.
>>
>> These options are already documented in the 'OPTIONS' section.
>>
>> Signed-off-by: Christian Couder 
>> ---
>> Soon after sending the first version I realized that the split index
>> options were not in the synopsys either...
>
> Sorry, too late. I merged v1 as part of yesterday's cycle, as it seemed
> obviously correct (that's what I get... :) ).
>
> Can you please send the change as a patch on top?

Ok will do.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v4] Documentation/git-update-index: add missing opts to synopsis

[Christian Couder]

Split index related options should appear in the 'SYNOPSIS'
section.

These options are already documented in the 'OPTIONS' section.

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
This v4 contains only the split-index options and applies on top
of the new master that already contains the untracked-cache options. 

 Documentation/git-update-index.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index 3df9c26..f4e5a85 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -17,6 +17,7 @@ SYNOPSIS
 [--[no-]assume-unchanged]
 [--[no-]skip-worktree]
 [--ignore-submodules]
+[--[no-]split-index]
 [--[no-|force-]untracked-cache]
 [--really-refresh] [--unresolve] [--again | -g]
 [--info-only] [--index-info]
-- 
2.6.3.380.g494b52d

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] Documentation/git-update-index: add missing opts to synopsys

[Jeff King]

On Wed, Nov 25, 2015 at 07:53:12AM +0100, Christian Couder wrote:

> Untracked cache and split index related options should appear
> in the 'SYNOPSIS' section.
> 
> These options are already documented in the 'OPTIONS' section.
> 
> Signed-off-by: Christian Couder 
> ---
> Soon after sending the first version I realized that the split index
> options were not in the synopsys either...

Sorry, too late. I merged v1 as part of yesterday's cycle, as it seemed
obviously correct (that's what I get... :) ).

Can you please send the change as a patch on top?

-Peff
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2] Documentation/git-update-index: add missing opts to synopsys

[Christian Couder]

Untracked cache and split index related options should appear
in the 'SYNOPSIS' section.

These options are already documented in the 'OPTIONS' section.

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
Soon after sending the first version I realized that the split index
options were not in the synopsys either...

 Documentation/git-update-index.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index 1a296bc..f4e5a85 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -17,6 +17,8 @@ SYNOPSIS
 [--[no-]assume-unchanged]
 [--[no-]skip-worktree]
 [--ignore-submodules]
+[--[no-]split-index]
+[--[no-|force-]untracked-cache]
 [--really-refresh] [--unresolve] [--again | -g]
 [--info-only] [--index-info]
 [-z] [--stdin] [--index-version ]
-- 
2.6.3.380.g494b52d

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/git-update-index: add missing opts to synopsys

[Christian Couder]

On Tue, Nov 24, 2015 at 9:46 PM, Jeff King <p...@peff.net> wrote:
> On Tue, Nov 24, 2015 at 12:55:07PM +0100, Christian Couder wrote:
>
>> Untracked cache related options should appear in the synopsis.
>>
>> Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
>> ---
>>  Documentation/git-update-index.txt | 1 +
>>  1 file changed, 1 insertion(+)
>>
>> diff --git a/Documentation/git-update-index.txt 
>> b/Documentation/git-update-index.txt
>> index 1a296bc..3df9c26 100644
>> --- a/Documentation/git-update-index.txt
>> +++ b/Documentation/git-update-index.txt
>> @@ -17,6 +17,7 @@ SYNOPSIS
>>[--[no-]assume-unchanged]
>>[--[no-]skip-worktree]
>>[--ignore-submodules]
>> +  [--[no-|force-]untracked-cache]
>
> Thanks, and it looks like they are already documented in the OPTIONS
> section.

Yeah, I just added this information into the commit message and sent a
v2 that also add split index related options to the synopsis.

Thanks,
Christian.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/git-update-index: add missing opts to synopsys

[Jeff King]

On Tue, Nov 24, 2015 at 12:55:07PM +0100, Christian Couder wrote:

> Untracked cache related options should appear in the synopsis.
> 
> Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
> ---
>  Documentation/git-update-index.txt | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/git-update-index.txt 
> b/Documentation/git-update-index.txt
> index 1a296bc..3df9c26 100644
> --- a/Documentation/git-update-index.txt
> +++ b/Documentation/git-update-index.txt
> @@ -17,6 +17,7 @@ SYNOPSIS
>[--[no-]assume-unchanged]
>[--[no-]skip-worktree]
>[--ignore-submodules]
> +  [--[no-|force-]untracked-cache]

Thanks, and it looks like they are already documented in the OPTIONS
section.

-Peff
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v3] Documentation/git-update-index: add missing opts to synopsis

[Christian Couder]

Untracked cache and split index related options should appear
in the 'SYNOPSIS' section.

These options are already documented in the 'OPTIONS' section.

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
The only change compared to v2 is s/synopsys/synopsis/ thanks to Eric.

 Documentation/git-update-index.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index 1a296bc..f4e5a85 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -17,6 +17,8 @@ SYNOPSIS
 [--[no-]assume-unchanged]
 [--[no-]skip-worktree]
 [--ignore-submodules]
+[--[no-]split-index]
+[--[no-|force-]untracked-cache]
 [--really-refresh] [--unresolve] [--again | -g]
 [--info-only] [--index-info]
 [-z] [--stdin] [--index-version ]
-- 
2.6.3.380.g494b52d

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] Documentation/git-update-index: add missing opts to synopsys

[Eric Sunshine]

On Wed, Nov 25, 2015 at 1:53 AM, Christian Couder
<christian.cou...@gmail.com> wrote:
> Documentation/git-update-index: add missing opts to synopsys

s/synopsys/synopsis/

> Untracked cache and split index related options should appear
> in the 'SYNOPSIS' section.
>
> These options are already documented in the 'OPTIONS' section.
>
> Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
> ---
> diff --git a/Documentation/git-update-index.txt 
> b/Documentation/git-update-index.txt
> @@ -17,6 +17,8 @@ SYNOPSIS
>  [--[no-]assume-unchanged]
>  [--[no-]skip-worktree]
>  [--ignore-submodules]
> +[--[no-]split-index]
> +[--[no-|force-]untracked-cache]
>  [--really-refresh] [--unresolve] [--again | -g]
>  [--info-only] [--index-info]
>  [-z] [--stdin] [--index-version ]
> --
> 2.6.3.380.g494b52d
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] Documentation/git-update-index: add missing opts to synopsys

[Christian Couder]

Untracked cache related options should appear in the synopsis.

Signed-off-by: Christian Couder <chrisc...@tuxfamily.org>
---
 Documentation/git-update-index.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index 1a296bc..3df9c26 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -17,6 +17,7 @@ SYNOPSIS
 [--[no-]assume-unchanged]
 [--[no-]skip-worktree]
 [--ignore-submodules]
+[--[no-|force-]untracked-cache]
 [--really-refresh] [--unresolve] [--again | -g]
 [--info-only] [--index-info]
 [-z] [--stdin] [--index-version ]
-- 
2.6.2.412.gf783589.dirty

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] Documentation/git-update-index: caution about tree objects

[Greg Troxel]

While one can add tree objects to the index, this is not currently
useful.  Therefore, use git ls-tree -r as the example to be fed to
--index-info.  Add a section explaining about expected index contents.
(Thanks to Junio for explaining this to me in August of 2011.)

Signed-off-by: Greg Troxel g...@ir.bbn.com
---
 Documentation/git-update-index.txt | 7 ++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-update-index.txt 
b/Documentation/git-update-index.txt
index 9d0b151..6ce65fa 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -29,6 +29,11 @@ Modifies the index or directory cache. Each file mentioned 
is updated
 into the index and any 'unmerged' or 'needs updating' state is
 cleared.
 
+Note that update-index does not check that the modifications preserve
+the expected invariants.  In particular, an index normally holds
+regular blobs, executable blobs, symlink blobs, and gitlinks.
+Therefore, adding a tree object is not likely useful.
+
 See also linkgit:git-add[1] for a more user-friendly way to do some of
 the most common operations on the index.
 
@@ -210,7 +215,7 @@ back on 3-way merge.
 
 . mode SP type SP sha1  TAB path
 +
-The second format is to stuff 'git ls-tree' output
+The second format is to stuff 'git ls-tree -r' output
 into the index file.
 
 . mode SP sha1 SP stage TAB path
-- 
1.8.0.1

--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation/git-update-index: caution about tree objects

[Junio C Hamano]

Greg Troxel g...@ir.bbn.com writes:

 While one can add tree objects to the index, this is not currently
 useful.  Therefore, use git ls-tree -r as the example to be fed to
 --index-info.  Add a section explaining about expected index contents.
 (Thanks to Junio for explaining this to me in August of 2011.)

 Signed-off-by: Greg Troxel g...@ir.bbn.com
 ---
  Documentation/git-update-index.txt | 7 ++-
  1 file changed, 6 insertions(+), 1 deletion(-)

 diff --git a/Documentation/git-update-index.txt 
 b/Documentation/git-update-index.txt
 index 9d0b151..6ce65fa 100644
 --- a/Documentation/git-update-index.txt
 +++ b/Documentation/git-update-index.txt
 @@ -29,6 +29,11 @@ Modifies the index or directory cache. Each file mentioned 
 is updated
  into the index and any 'unmerged' or 'needs updating' state is
  cleared.
  
 +Note that update-index does not check that the modifications preserve
 +the expected invariants.  In particular, an index normally holds
 +regular blobs, executable blobs, symlink blobs, and gitlinks.
 +Therefore, adding a tree object is not likely useful.
 +

I find this unnecessarily alarmist as a description meant for
general audiences.  For the normal mode of operations of the command
(e.g. git update-index --add --remove hello.c), whatever you mean
by expected invariants are fully preserved.

I think you meant this for --cacheinfo and --index-info options,
which are primarily meant for people who know what they are doing
(that includes the use of this command in scripted Porceains) or Git
developers who want to work on enhancing the index (and to them,
being able to record anything is more convenient).

 @@ -210,7 +215,7 @@ back on 3-way merge.
  
  . mode SP type SP sha1  TAB path
  +
 -The second format is to stuff 'git ls-tree' output
 +The second format is to stuff 'git ls-tree -r' output
  into the index file.

This hunk is good.

Thanks.
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html