docs: give more hints about how "add -e" works
The previous text was not exactly accurate; it is OK to change space and minus lines, but only in certain ways. This patch attempts to cover explicitly what can be done at the individual line level, and cautions the user that conceptually larger changes (like modifying a line) require some understanding of the patch format. Signed-off-by: Jeff King <peff@peff.net> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff King committed
Oct 21, 2010 at 10:30 UTC
5df4d67d4156ec7cd37089aeb3d5f66ee857a01a
1 file changed
+29
-3
Documentation/git-add.txt
+29
-3
@@ -92,9 +92,35 @@ See ``Interactive mode'' for details.
92
edit it. After the editor was closed, adjust the hunk headers
93
and apply the patch to the index.
94
+
95
-*NOTE*: Obviously, if you change anything else than the first character
96
-on lines beginning with a space or a minus, the patch will no longer
97
-apply.
95
+The intent of this option is to pick and choose lines of the patch to
96
+apply, or even to modify the contents of lines to be staged. There are
97
+three line types in a patch: addition lines (beginning with a plus),
98
+removal lines (beginning with a minus), and context lines (beginning
99
+with a space). In general, it should be safe to:
100
++
101
+--
102
+* remove addition lines (don't stage the line)
103
+* modify the content of any addition lines (stage modified contents)
104
+* add new addition lines (stage the new line)
105
+* convert context lines to removal lines (stage removal of line)
106
+* convert removal lines to context lines (don't stage removal)
107
+--
108
++
109
+Similarly, your patch will likely not apply if you:
110
++
111
+--
112
+* add context or removal lines
113
+* delete removal or context lines
114
+* modify the contents of context or removal lines
115
+--
116
++
117
+NOTE: In the first list above, the results given for each action are
118
+with respect to that patch line only. Conceptual changes like
119
+modification of a line in the original file are actually represented by
120
+removal of the old line followed by addition of the new line. Deleting
121
+only the addition line of this pair but leaving the removal line would
122
+therefore convert the modification into a deletion. In other words, use
123
+this feature with caution, as it is easy to stage unintended changes.
124
125
-u::
126
--update::