On Mon, Oct 19, 2009 at 12:34:18AM -0400, Jeff King wrote:
> I still have a few comments, though.
> [...]
> (the spacing of which will hopefully not be destroyed in transit). In
> other words, the "+" list continuation makes the "it is a bad idea" text
> part of the "good idea" list, instead of continuing the definition of
> the "-e" option. I think we can fix it with an open block marker. I'll
> see what I can do.
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?
-- >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@xxxxxxxx>
---
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
+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)
+* modify the content of any addition lines (stage modified contents)
+* add new addition lines (stage the new line)
+* convert context lines to removal lines (stage removal of line)
+* convert removal lines to context lines (don't stage removal)
+--
++
+Similarly, your patch will likely not apply if you:
++
+* add context or removal lines
+* delete removal or context lines
+* modify the contents of context or removal lines
-u::
--update::
--
1.6.5.1.123.gcaaf
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html