Re: [PATCH] docs: give more hints about how "add -e" works

[Junio C Hamano <gitster@pobox.com>]

Jeff King <peff@peff.net> writes:

> -*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.

It is a good change to lose this "Obviously", which is often a sign of the
lazyness of the author who didn't even bother to explain certain things,
handwaving them away as "Obvious" ;-)

> +The intent of this option is to pick and choose lines of the patch to
> +apply, or even to modify the contents of lines to be staged. There are
> +three line types in a patch: 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)

I am not sure if the use of the word "stage" here is correct, even when
read from the "git stage" lovers' viewpoint.

If the "+" line is a pure addition without any corresponding line in the
preimage (which is removed by "-"), then this is "Don't add that line".
If it has a corresponding "-" line somewhere, that is rather "Remove
the corresponding line in the preimage".

"Don't add the updated line" might be a good compromise.

> +* 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)

Alternatively, to be consistent with "stage modification", "stage
removal", the removal of "+" can be phrased as "do not stage the addition
of the line".

I'd recommend to phrase them as "don't add", "add modified contents
instead", "add new line", "remove line" and "do not remove line", which
would be simpler to read, though.

> +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
> +--
> ++
> +NOTE: In the first list above, the results given for each action are
> +with respect to that patch line only. Conceptual changes like
> +modification of a line in the original file are actually represented by
> +removal of the old line followed by addition of the new line. Deleting
> +only the addition line of this pair but leaving the removal line would
> +therefore convert the modification into a deletion. In other words, use
> +this feature with caution, as it is easy to stage unintended changes.

Is there a way to move this note way upwards?  Once the reader understands
what this paragraph teaches, it becomes much easier to understand the
implication of "remove addition".