[PATCH] don't mention index refreshing side effect in git-status docs

[PATCH] don't mention index refreshing side effect in git-status docs

[Jeff King]

The tip about speeding up subsequent operations is now
obsolete; since aecbf914, git-diff now squelches empty diffs
and performs an automatic refresh.

Signed-off-by: Jeff King <peff@peff.net>
---
This is on top of my other patches to the git-status docs.

I don't see any reason to mention this side effect at all. Those who
know enough to set diff.autorefreshindex presumably know what they are
doing, and the removed paragraph is a bit confusing to those who don't.

If there is some desire to document the side effect, I think we should
at least remove the mention of speeding up git-diff (which is just wrong
now).

 Documentation/git-status.txt |    7 -------
 1 files changed, 0 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index a1bb9bd..5c5a480 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -28,13 +28,6 @@ If there is no path that is different between the index file and
 the current HEAD commit (i.e., there is nothing to commit by running
 `git-commit`), the command exits with non-zero status.
 
-If any paths have been touched in the working tree (that is,
-their modification times have changed) but their contents and
-permissions are identical to those in the index file, the command
-updates the index file. Running `git-status` can thus speed up
-subsequent operations such as `git-diff` if the working tree
-contains many paths that have been touched but not modified.
-
 
 OUTPUT
 ------
-- 
1.5.3.7.2187.gb646

Re: [PATCH] don't mention index refreshing side effect in git-status docs

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> If there is some desire to document the side effect, I think we should
> at least remove the mention of speeding up git-diff (which is just wrong
> now).

Why is it "just wrong"?  Having to squelch the false hits and to run
auto-refresh are both unnecessary overhead if your index is fresh.

Re: [PATCH] don't mention index refreshing side effect in git-status docs

[Jeff King]

On Sun, Dec 09, 2007 at 12:33:19AM -0800, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> > If there is some desire to document the side effect, I think we should
> > at least remove the mention of speeding up git-diff (which is just wrong
> > now).
> 
> Why is it "just wrong"?  Having to squelch the false hits and to run
> auto-refresh are both unnecessary overhead if your index is fresh.

I mean that this is not a useful technique for speeding up git-diff
anymore (assuming you have not tinkered with autorefreshindex, in which
case I assume you know what you are doing and don't need this tip).

Did you think I meant "there is no speedup with autorefreshindex off",
or are you arguing that even with the new diff behavior there is still a
speedup in "git status; git diff" over just "git status"?

-Peff

Re: [PATCH] don't mention index refreshing side effect in git-status docs

[Jonathan del Strother]

On Dec 9, 2007 8:21 AM, Jeff King <peff@peff.net> wrote:
> The tip about speeding up subsequent operations is now
> obsolete; since aecbf914, git-diff now squelches empty diffs
> and performs an automatic refresh.
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
> This is on top of my other patches to the git-status docs.
>
> I don't see any reason to mention this side effect at all. Those who
> know enough to set diff.autorefreshindex presumably know what they are
> doing, and the removed paragraph is a bit confusing to those who don't.
>


...   I wasn't aware the index needed refreshing.  This might be
totally unrelated to the present conversation, but the GIT-VERSION-GEN
script occasionally gives me spurious 'dirty' results (eg when a file
timestamp changes despite the content having changed).  Should it
perhaps be running "git update-index --refresh" before it runs "git
diff-index --name-only HEAD" ?

Re: [PATCH] don't mention index refreshing side effect in git-status docs

[Junio C Hamano]

"Jonathan del Strother" <maillist@steelskies.com> writes:

> ... the GIT-VERSION-GEN
> script occasionally gives me spurious 'dirty' results (eg when a file
> timestamp changes despite the content having changed).

Good eyes.  Either refreshing before diff-index or using the "git diff"
Porcelain would be more appropriate.