Signed-off-by: Kai Koponen <kaikopone@xxxxxxxxxx>
---
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.
A more detailed explanation follows.
--
2.47.0.338.g60cca15819-goog
On Tue, Nov 19, 2024 at 10:22â?¯PM Elijah Newren <newren@xxxxxxxxx> wrote:
>
> On Tue, Nov 19, 2024 at 1:53â?¯PM Kai Koponen <kaikoponen@xxxxxxxxxx> wrote:
> >
> > What did you do before the bug happened? (Steps to reproduce your issue)
> > Create a toy repo with commits in the following structure:
> > A - B - C
> > \
> > D
> >
> > Run `git rev-list --ancestry-path=D A..C`.
> >
> > What did you expect to happen? (Expected behavior)
> > Commits A and B should be listed.
> >
> > What happened instead? (Actual behavior)
> > No commits listed.
> >
> > What's different between what you expected and what actually happened?
> > --ancestry-path with a commit arg seems to return 0 results unless the
> > specified commit is itself part of the range. The rev-list documentation
> > does not mention that this is a requirement.
>
> Yeah, the commit message that introduced --ancestry-path=COMMIT did
> document this in its commit message (see
> 257418c59040c13bfa839e01922e21833cda6a52257418c59040 (revision: allow
> --ancestry-path to take an argument, 2022-08-19)), and I think my
> original documentation patch was a little clearer on this point, but
> when Jonathan suggested an alternative for the documentation
> (https://lore.kernel.org/git/20220818222416.3567602-1-jonathantanmy@xxxxxxxxxx/),
> I didn't think about someone attempting a commit outside the
> ancestry-path as the argument. My bad.
>
> Based on the references above, would you like to suggest a
> documentation patch to ensure this requirement is documented?
