Re: [PATCH] git add -e documentation: rephrase note
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:47:34
Jeff King [off-list ref] writes:
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.
quoted hunk
-- >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 <redacted> --- 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.
+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).