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

[Kai Koponen <kaikoponen@google.com>]

The rev-list documentation doesn't mention that the given
commit must be in the specified commit range, leading
to unexpected results.

Signed-off-by: Kai Koponen <kaikopone@google.com>
---
 Documentation/rev-list-options.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/rev-list-options.txt
b/Documentation/rev-list-options.txt
index 00ccf68744..f0a46f9da5 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -412,7 +412,7 @@ 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
+ 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
-- 
2.47.0.338.g60cca15819-goog

On Mon, Dec 2, 2024 at 8:05 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> 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.