Re: rev-list --ancestry-path with arg - bug or undocumented requirement

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

Kai Koponen <kaikoponen@google.com> writes:

> From 447a2367f8d3318e69adccc1b011b0d04792e438 Mon Sep 17 00:00:00 2001

Do not include this line.

It is not a part of message, but merely added as a mark that a new
message starts here in case there are two or more patch e-mail
messages in a file.  Since you are sending one patch per one e-mail
message, you do not want it.

> From: Kai Koponen <kaikoponen@google.com>

Let your MUA have it on the From: header of your message; you do not
want this line when your MUA is configured correctly (and yours is;
we see From: header saying the same thing).

> Date: Mon, 2 Dec 2024 19:32:25 +0000

You do not want this, either.  Your MUA records on Date: header the
time general public saw this change for the first time.

> Subject: [PATCH] doc: mention rev-list --ancestry-path restrictions

Put this in the e-mail header.  We add [PATCH] for a very good reason:
make it easier to find patches in the mailing list traffic.

>

Here is where you "sell" your changes by explaining why we are
making this change (like "existing text allows misinterpretation
that makes it sound like doing this and that are possible, which is
not true").  Please do not leave it empty.

> Signed-off-by: Kai Koponen <kaikopone@google.com>
> ---
>  Documentation/rev-list-options.txt | 13 +++++++------
>  1 file changed, 7 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/rev-list-options.txt
> b/Documentation/rev-list-options.txt
> index 00ccf68744..1c678294af 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -412,12 +412,13 @@ Default mode::
>
>  --ancestry-path[=<commit>]::
>   When given a range of commits to display (e.g. 'commit1..commit2'
> - or 'commit2 {caret}commit1'), only display commits in that range
> - that are ancestors of <commit>, descendants of <commit>, or
> - <commit> itself.  If no commit is specified, use 'commit1' (the
> - excluded part of the range) as <commit>.  Can be passed multiple
> - times; if so, a commit is included if it is any of the commits
> - given or if it is an ancestor or descendant of one of them.
> + or 'commit2 {caret}commit1'), and a commit <commit> in that range,
> + only display commits in that range that are ancestors of <commit>,
> + descendants of <commit>, or <commit> itself. If no commit is
> + specified, use 'commit1' (the excluded part of the range) as
> + <commit>.  Can be passed multiple times; if so, a commit is
> + included if it is any of the commits given or if it is an ancestor
> + or descendant of one of them.

As these files in Documentation/ are input to formatting programs,
please do not reflow the text unnecessarily so that what you changed
stand out, instead of forcing reviewers to go word-by-word to sift
through the changes to see what got really changed.

Thanks.