Re: `--ancestry-path` documentation has wrong graph

From: Elijah Newren <newren@gmail.com>
Date: Mar 15, 2025, 16:42 UTC
Message-ID: <CABPp-BHn6sPBh0CPctJ4-rM3rxGwXkbG4-o236dRV8FTwdP_nQ@mail.gmail.com>
In-Reply-To: <CANrWfmRpDFuqv+fkCf_p_ggHTrRjD3Vgviqrai_rA7Lu-YFEMA@mail.gmail.com>

On Sat, Mar 15, 2025 at 1:21 AM Han Jiang <jhcarl0814@gmail.com> wrote:

Show 32 quoted lines

>
> On Sat, Mar 15, 2025 at 6:16 AM Elijah Newren <newren@gmail.com> wrote:
> >
> > On Thu, Mar 13, 2025 at 2:04 PM Han Jiang <jhcarl0814@gmail.com> wrote:
> > >
> > > Git - git-log Documentation --ancestry-path[=<commit>]
> > > https://git-scm.com/docs/git-log#Documentation/git-log.txt---ancestry-pathltcommitgt-1
> > >
> > > The graph for `--ancestry-path=H D..M` should contain commit C.
> >
> > Indeed; D..H contains C, and C is an ancestor of H.  I apparently
> > overlooked C in that example when writing that documentation.  Would
> > you like to submit a patch, or would you like me to do so and record
> > you as the reporter?  I'm fine with either, but if you want to give it
> > a try, the relevant file is Documentation/rev-list-options.adoc in the
> > repository.
>
> Thank you for the clarification! I'd like to try sending a patch.
> After doing some research on how to make contributions today, I
> decided to try GitGitGadget way first. But I got some questions that
> the doc doesn't clearly explain:
>
> [Git - CodingGuidelines
> Documentation](https://git-scm.com/docs/CodingGuidelines) says:
> For C programs: We use tabs to indent, and interpret tabs as taking up
> to 8 spaces.
> 1. It seems adoc files treats tabs as 8 spaces too, is that true?
> (The prepared commit in forked repository is at
> https://github.com/jhcarl0814/git/commit/ce568e4a87dff14df4e7104af89be3f12616f5de
> . The source diff shows tabs as 4 spaces. The rich diff shows tabs as
> 8 spaces. When I was editting the number defaults to 8 and is
> adjustable in editor options.)

Yes, assume 8 spaces per tab.

Note that if you're worried, you can cd into the doc directory and run either
    make git-log.html
or
    make git-log.1

followed by then either
    <open your log git-log.html file in your web browser>
or
    man ./git-log.1

and look at how your changes modify the end result.

Show 10 quoted lines

> [Git - MyFirstContribution
> Documentation](https://git-scm.com/docs/MyFirstContribution) says:
> For single-patch contributions, your commit message should already be
> meaningful and explain at a high level the purpose (what is happening
> and why) of your patch, so you usually do not need any additional
> context. In that case, remove the PR description that GitHub
> automatically generates from your commit message (your PR description
> should be empty).
> 2. For single-patch contributions, is the pull request title or the
> first line of commit message that will become Subject of the email?

Why would you make the pull request title and the first line of the commit message different for a single-commit pull request? That'd be weird.

I have a guess at the answer, but only a guess.

Show 5 quoted lines

> [Git - SubmittingPatches
> Documentation](https://git-scm.com/docs/SubmittingPatches) says:
> It is a common convention to prefix your subject line with [PATCH].
> 3. Which one of GitGitGadget or the pull request creator is the one
> who add "[PATCH]" at the beginning of the title?

GitGitGadget will add it for you.

Show 7 quoted lines

> [Git - MyFirstContribution
> Documentation](https://git-scm.com/docs/MyFirstContribution) says:
> Now that your CI is passing and someone has granted you permission to
> use GitGitGadget with the `/allow` command, sending out for review is
> as simple as commenting on your PR with `/submit`.
> 4. Who is able to use `/submit` to trigger email sending action? Is it
> the pull request creator (when `/allow`ed) or anyone (`/allow`ed)?

Once you've been /allow'ed once, you can /submit that or any future PRs of yours.

> 5. If `/submit` sends email, then how to cc all relevant people
> (including myself) at the moment of `/submit`? Is there a place to
> fill in this parameter?

In the PR description include a line of the form
   cc: User Name <user@email>

> 6. Where does `/submit` send the email to, as a brand new post or as a
> reply under this post? How to configure?

Brand new post, not configurable. Just post a response to the original thread with a link to the new submission.

Now, as kind of a summary of the answers to many of these questions and perhaps others:

If you want to see an example, take a look at and compare
   https://github.com/gitgitgadget/git/pull/1864
with
   https://lore.kernel.org/git/pull.1864.git.1740139296483.gitgitgadget@gmail.com/

You'll be able to see the cc in action, see where the commit message and pr description go, see how the subject has '[PATCH] ' auto-prepended, etc.