Re: [PATCH] git add -e documentation: rephrase note

From: Jeff King <peff@peff.net>
Date: Oct 19, 2009, 04:34 UTC
Message-ID: <20091019043418.GD7170@coredump.intra.peff.net>
In-Reply-To: <20091019000900.GV6115@genesis.frugalware.org>

On Mon, Oct 19, 2009 at 02:09:00AM +0200, Miklos Vajna wrote:

Show 5 quoted lines

> Add a quick overview about what is OK and what is not to cover all
> cases.
> 
> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
> Signed-off-by: Jeff King <peff@peff.net>

Please be careful with sign-offs. While your patch text is an adaptation of what I said, and while it is true that I personally would never say anything on the list that was not free for use in git, I did not in fact do such a sign-off, which is what that line is supposed to be documenting.

In this case, I think you probably just wanted to say "text from Jeff King" or even "From: Jeff King <peff@peff.net>".

That being said,

  Signed-off-by: Jeff King <peff@peff.net>

:)

I still have a few comments, though.

Show 5 quoted lines

> +The intent of this option is to pick and choose lines of the diff to
> +apply, or even to munge the lines. So it is safe to:
> ++
> +* remove lines with a "+" (don't stage the addition)
> +* munge any lines with a "+" (stage modified contents)

Do we want to use "munge" here? Maybe something a little more specific like "modify the content of" is more appropriate for documentation.

> +* add lines with a "+" (stage an addition)
> +* convert lines with a " " to "-" (stage removal)
> +* convert lines with a "-" to " " (don't stage removal)

Is " " going to render in an obvious-to-read way? I checked the html version and the manpage version in my terminal, and they looked OK, but I would not be surprised if somebody has a font setup that makes it a little hard to read.

> ++
> +It is a bad idea to:
> ++

Annoyingly, this renders for me as:

           ·   convert lines with a "-" to " " (don’t stage removal)

               It is a bad idea to:

           ·   delete "-" lines

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

-Peff