Re: [PATCH] git add -e documentation: rephrase note

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 19, 2009, 05:38 UTC
Message-ID: <7vbpk4aqop.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20091019050456.GA15706@coredump.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 12 quoted lines

> Hmph. Here is my attempt. The text is (I hope) more clear, but I am
> still having trouble with the formatting. It looks fine in the HTML
> version, and if I am reading the XML right, the XML is correct. But
> docbook seems to screw up converting the XML to roff, giving this:
>
>            ·   convert removal lines to context lines (don’t stage removal)
>                Similarly, your patch will likely not apply if you:
>
>            ·   add context or removal lines
>
> Am I missing something, or is it really a docbook bug? Does it render
> better for anybody else?

Not for me, and I have seen manpages lacking a blank line like the above where I expect one in other places, so it is not very surprising.

Show 23 quoted lines

> -- >8 --
> Subject: [PATCH] docs: give more hints about how "add -e" works
>
> The original text was not very descriptive about what you
> can and can't do; let's try to enumerate all cases.
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
>  Documentation/git-add.txt |   22 +++++++++++++++++++---
>  1 files changed, 19 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> index 45ebf87..b0a8420 100644
> --- a/Documentation/git-add.txt
> +++ b/Documentation/git-add.txt
> @@ -86,9 +86,25 @@ OPTIONS
>  	edit it.  After the editor was closed, adjust the hunk headers
>  	and apply the patch to the index.
>  +
> -*NOTE*: Obviously, if you change anything else than the first character
> -on lines beginning with a space or a minus, the patch will no longer
> -apply.
> +The intent of this option is to pick and choose lines of the diff to

I'd slightly prefer "patch" over "diff" in this context.

Show 7 quoted lines

> +apply, or even to modify the contents of lines to be staged. There are
> +three line types in a diff: addition lines (beginning with a plus),
> +removal lines (beginning with a minus), and context lines (beginning
> +with a space). In general, it should be safe to:
> ++
> +--
> +* remove addition lines (don't stage the line)

This is more like "don't add the line", isn't it? Also if this "+" line has corresponding "-" line (i.e. it is a "rewrite to this" line), removal of such a line would mean "instead of rewriting, remove it".

> +* modify the content of any addition lines (stage modified contents)

Would be "add differently".

> +* add new addition lines (stage the new line)

"Add more than what you have in the work tree"

While kibitzing like the above, I noticed that there is another thing that may deserve warning even more. Suppose you added lines and the patch between HEAD and the work tree looks like this:

    diff --git a/t-f b/t-f
    index e69de29..d68dd40 100644
    --- a/t-f
    +++ b/t-f
    @@ -0,0 +1,4 @@
    +a
    +b
    +c
    +d

And you do "add -e" and edit the patch to:

    diff --git a/t-f b/t-f
    index e69de29..17c3f0b 100644
    --- a/t-f
    +++ b/t-f
    @@ -0,0 +1,3 @@
    +a
    +e
    +d

Obviously, the above patch is what "diff --cached" would show after such an "add -e", but this does _not_ touch anything in the work tree (which is correct; add is about moving changed contents to the index and it should fundamentally not affect work tree). As a result, "diff" between the index and the work tree now would read like this:

    diff --git a/t-f b/t-f
    index 17c3f0b..d68dd40 100644
    --- a/t-f
    +++ b/t-f
    @@ -1,3 +1,4 @@
     a
    -e
    +b
    +c
     d

IOW, your request to "add -e" was "I do not want to put the addition of 'c' in the index at this point (that is why you removed '+c')" and "I do not want to put the addition of 'b' in the index; I want 'e' instead (that is why you changed '+b' to '+e')". After "add -e" granted both requests, what is left in the work tree can confuse the user. The "not at this point" part of the first request is clearly visible that the leftover diff has an addition of '+c'. But the user may expect that the second request, "I don't want 'b', I want 'e'", would carry over to the work tree and not see the apparent reversion of the wish (i.e. you changed it to add 'e' instead of 'b' in "add -e" session, but it is reverted and "commit -a" would record the version with 'b' instead).