Re: [PATCH] doc: Use the term "remark" in "cherry-pick -x" to disambiguate from "git notes"

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 15, 2011, 17:12 UTC
Message-ID: <7v7have8wo.fsf@alter.siamese.dyndns.org>
In-Reply-To: <4DA7F73B.9050007@gmail.com>

Sebastian Schuberth <sschuberth@gmail.com> writes:

> The documentation for "cherry-pick -x" can be misread in the way that a
> "git notes" object is attached to the new commit, which is not the case.
> Instead, just some text is appended to the original commit message. Make this
> more clear by simply using the term "remark" instead of "note".

A sensible concern, I guess, even though "_append_ to the original _commit message_" should signal that this sentence cannot be referring to a note object separate from the commit.

Show 11 quoted lines

> diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
> index 01db830..5afc2b0 100644
> --- a/Documentation/git-cherry-pick.txt
> +++ b/Documentation/git-cherry-pick.txt
> @@ -52,8 +52,8 @@ OPTIONS
>  
>  -x::
>  	When recording the commit, append to the original commit
> +	message a remark that indicates which commit this change
> +	was cherry-picked from.  Append the remark only for cherry
>  	picks without conflicts.  ...

I wonder if it is better to be even more explicit and say:

	... append a line that says "(cherry picked from commit ...)" to
        the original commit message in order to indicate which commit this
        change was cherry-picked from.  This is done only for ...

so that we don't have to worry about having to change this in 10 years when we notice that description can easily be misread that it is done using the remark feature introduced a few years back?