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

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

[Kai Koponen]

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.

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

[Kristoffer Haugsbakk]

Hello Kai

On Tue, Dec 3, 2024, at 18:14, Kai Koponen wrote:
> 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(-)

I couldn’t apply this patch to `master` (cc01bad4a9f (The twelfth batch,
2024-11-27)). It looks like it is because..

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

This line got corrupted (linebreak).

I see that you used git-send-email(1).  Did you edit the patch file
manually in order to add the quotation from Junio below? I’m guessing
the editor then broke that line since it is 102 characters when
combined/joined.  I guess you could use cat(1) instead.  I like to use
Git Notes.  You can add a note to the commit and then use that default
namespace (commits) when making the patch.

    git notes edit
    git format-patch --notes=commits ...

Although in this case it might be better to add a linebreak since the
line gets so long. You can add one short line so that you don’t get the
reflow-paragraph problem from the previous version:

(these are with space indentation instead of tabs)

     --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'), only display commits in that range,
    +       and a commit <commit> 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

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

[Kai Koponen]

Apologies, I made a mistake while copying the patch in manually from
format-patch; my git install doesn't have send-email available, I'll
fix that.

On Tue, Dec 3, 2024 at 12:39 PM Kristoffer Haugsbakk
<kristofferhaugsbakk@fastmail.com> wrote:
>
> Hello Kai
>
> On Tue, Dec 3, 2024, at 18:14, Kai Koponen wrote:
> > 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(-)
>
> I couldn’t apply this patch to `master` (cc01bad4a9f (The twelfth batch,
> 2024-11-27)). It looks like it is because..
>
> >
> > 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
>
> This line got corrupted (linebreak).
>
> I see that you used git-send-email(1).  Did you edit the patch file
> manually in order to add the quotation from Junio below? I’m guessing
> the editor then broke that line since it is 102 characters when
> combined/joined.  I guess you could use cat(1) instead.  I like to use
> Git Notes.  You can add a note to the commit and then use that default
> namespace (commits) when making the patch.
>
>     git notes edit
>     git format-patch --notes=commits ...
>
> Although in this case it might be better to add a linebreak since the
> line gets so long. You can add one short line so that you don’t get the
> reflow-paragraph problem from the previous version:
>
> (these are with space indentation instead of tabs)
>
>      --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'), only display commits in that range,
>     +       and a commit <commit> 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

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

[Kai Koponen via GitGitGadget]

From: Kai Koponen <kaikoponen@google.com>

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

Signed-off-by: Kai Koponen <kaikoponen@google.com>
---
    doc: mention rev-list --ancestry-path restrictions

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1838%2Fgkaikoponen%2Fmaster-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1838/gkaikoponen/master-v1
Pull-Request: https://github.com/git/git/pull/1838

 Documentation/rev-list-options.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 00ccf687441..459e5a02f52 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -412,7 +412,8 @@ 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

base-commit: cc01bad4a9f566cf4453c7edd6b433851b0835e2
-- 
gitgitgadget

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

[Kai Koponen]

Re-trying via GitGitGadget at
https://lore.kernel.org/git/pull.1838.git.git.1733257083739.gitgitgadget@gmail.com/

On Tue, Dec 3, 2024 at 12:59 PM Kai Koponen <kaikoponen@google.com> wrote:
>
> Apologies, I made a mistake while copying the patch in manually from
> format-patch; my git install doesn't have send-email available, I'll
> fix that.
>
> On Tue, Dec 3, 2024 at 12:39 PM Kristoffer Haugsbakk
> <kristofferhaugsbakk@fastmail.com> wrote:
> >
> > Hello Kai
> >
> > On Tue, Dec 3, 2024, at 18:14, Kai Koponen wrote:
> > > 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(-)
> >
> > I couldn’t apply this patch to `master` (cc01bad4a9f (The twelfth batch,
> > 2024-11-27)). It looks like it is because..
> >
> > >
> > > 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
> >
> > This line got corrupted (linebreak).
> >
> > I see that you used git-send-email(1).  Did you edit the patch file
> > manually in order to add the quotation from Junio below? I’m guessing
> > the editor then broke that line since it is 102 characters when
> > combined/joined.  I guess you could use cat(1) instead.  I like to use
> > Git Notes.  You can add a note to the commit and then use that default
> > namespace (commits) when making the patch.
> >
> >     git notes edit
> >     git format-patch --notes=commits ...
> >
> > Although in this case it might be better to add a linebreak since the
> > line gets so long. You can add one short line so that you don’t get the
> > reflow-paragraph problem from the previous version:
> >
> > (these are with space indentation instead of tabs)
> >
> >      --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'), only display commits in that range,
> >     +       and a commit <commit> 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

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

[Elijah Newren]

On Tue, Dec 3, 2024 at 12:18 PM Kai Koponen via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Kai Koponen <kaikoponen@google.com>
>
> The rev-list documention doesn't mention that the given
> commit must be in the specified commit range, leading
> to unexpected results.
>
> Signed-off-by: Kai Koponen <kaikoponen@google.com>
> ---
>     doc: mention rev-list --ancestry-path restrictions
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1838%2Fgkaikoponen%2Fmaster-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1838/gkaikoponen/master-v1
> Pull-Request: https://github.com/git/git/pull/1838
>
>  Documentation/rev-list-options.txt | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
> index 00ccf687441..459e5a02f52 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -412,7 +412,8 @@ 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
>
> base-commit: cc01bad4a9f566cf4453c7edd6b433851b0835e2
> --
> gitgitgadget

Might be worth linking to the thread where this was discussed (in
single-commit gitgitgadget PRs, that'd be done in the PR description),
over here: https://lore.kernel.org/git/CADYQcGpXm=RTEYyxqdSowQ4Vg9jmXuCzOOpd-TgDX8U814BReg@mail.gmail.com/

Anyway, patch looks good to me.

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

[Junio C Hamano]

Kai Koponen <kaikoponen@google.com> writes:

> 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

Thanks for accomodating my pickyness ;-)  This version reads very
well.

Will queue.

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

[Junio C Hamano]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

> Hello Kai
>
> I couldn’t apply this patch to `master` (cc01bad4a9f (The twelfth batch,
> 2024-11-27)). It looks like it is because..

yes it is heavily whitespace damaged.  Here is what I applied after
manually reconstructing.

--- >8 ---
From: Kai Koponen <kaikoponen@google.com>
Date: Tue, 3 Dec 2024 12:14:34 -0500
Subject: [PATCH] doc: mention rev-list --ancestry-path restrictions

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/rev-list-options.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 0d90d5b154..9d5243e0aa 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -401,7 +401,8 @@ 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.1-529-gecd20ec0f1

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

[Kai Koponen]

Thanks for fixing the mangling, pickiness is definitely called for a
huge project like this with lots of work on the maintainers. Wish
gmail didn't eat tabs in plain text mode... the github app was easier
to use than I expected though.

On Tue, Dec 3, 2024 at 6:33 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
>
> > Hello Kai
> >
> > I couldn’t apply this patch to `master` (cc01bad4a9f (The twelfth batch,
> > 2024-11-27)). It looks like it is because..
>
> yes it is heavily whitespace damaged.  Here is what I applied after
> manually reconstructing.
>
> --- >8 ---
> From: Kai Koponen <kaikoponen@google.com>
> Date: Tue, 3 Dec 2024 12:14:34 -0500
> Subject: [PATCH] doc: mention rev-list --ancestry-path restrictions
>
> 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>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/rev-list-options.txt | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
> index 0d90d5b154..9d5243e0aa 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -401,7 +401,8 @@ 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.1-529-gecd20ec0f1
>

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

[Junio C Hamano]

"Kai Koponen via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Kai Koponen <kaikoponen@google.com>
>
> The rev-list documention doesn't mention that the given
> commit must be in the specified commit range, leading
> to unexpected results.
>
> Signed-off-by: Kai Koponen <kaikoponen@google.com>
> ---
>     doc: mention rev-list --ancestry-path restrictions

Thanks.