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

[Jeff King <peff@peff.net>]

On Mon, Nov 08, 2010 at 04:57:34PM -0800, Junio C Hamano wrote:

> The new text indeed looks much clearer, except for one part I am not
> absolutely sure...
> 
> > +new content::
> > +
> > +You may also add new content that does not exist in the patch. Simply
> > +add new lines, each starting with "{plus}".
> > +
> > +You can also perform more complex operations, such as modifying the
> > +content to be staged by a "{plus}" line. However, note that this impacts
> > +_only_ the index; the working tree file will remain unchanged, and will
> > +appear to "undo" the content you have staged. Such operations should be
> > +performed only if you know what you are doing.
> 
> This "However, note that" part should apply not only to newly introduced
> {plus} lines but also to {plus} lines whose change were edited (lines from
> "added content" and from post-image half of "modified content"), no?

Right. The final paragraph you quoted is not part of the list, and it
looks better when rendered by asciidoc, as it's indented differently. So
I think some of the confusion is from the source formatting. But...

> I tried to be careless when reading the two paragraphs above, and managed
> to get an incorrect impression that the caveat applies only to "more
> complex operations", even though it actually applies not just the previous
> "new content" but also "added/modified" content.
> 
> Thinking about it a bit more, it is worse than that.  Turning " " into "-"
> has the same "getting reverted" issue, no?

Yeah, some of the operations described in the upper list are actually
"more complex" in the sense of looking like reverts. Basically any time
you are _introducing_ a change during the diff edit rather than simply
selecting or not-selecting changes that exist in the working tree, you
are going to get confusing results. So let me take one more stab at it,
and I think the correct breakdown is:

  1. stuff you might want to do: staging or not staging added, removed,
     and modified lines

  2. stuff you might want to do if you're insane: marking context lines
     for removal, adding new content, changing content on existing add
     lines

  3. stuff that you never want to do, because it makes the patch
     impossible to apply: deleting, adding, or changing context or
     removal lines

I'll try to do a patch later tonight.

-Peff