Re: [PATCH] revision: add --maximal option
- From
Derrick Stolee <stolee@gmail.com>
- Date
- Jan 18, 2026, 18:27 UTC
- Message-ID
- <b46885b1-5781-43d8-8751-d85048c45e5e@gmail.com>
- In-Reply-To
- <1da38e88-3f61-43df-9c75-5716d715bf80@kdbg.org>
On 1/18/26 4:05 AM, Johannes Sixt wrote:
Show 22 quoted lines
> Am 18.01.26 um 03:34 schrieb Derrick Stolee via GitGitGadget: >> diff --git a/Documentation/rev-list-options.adoc b/Documentation/rev-list-options.adoc >> index 453ec59057..f0d2ab32a9 100644 >> --- a/Documentation/rev-list-options.adoc >> +++ b/Documentation/rev-list-options.adoc >> @@ -444,6 +444,10 @@ The following options affect the way the simplification is performed: >> 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. >> >> +`--maximal`:: >> + Restrict the output commits to be those that are not reachable >> + from any other commits in the revision range. > > I had to read this sentence three times to understand what it wants to > say, and that even though I had a rough idea what it was supposed to > mean. I tried to come up with a better wording, but found it to be > really hard. > > Restrict output to the commits at the tips of the > revision range. > > is all I could do, but this isn't a lot better, I am afraid.
> > The option name is too generic IMHO. How about "--starting-point",
> "--topmost-only"? It's function is somewhat parallel to --boundary, but > at the positive end of the revision range. Perhaps we can use that as > inspiration.
My perspective is skewed, because "maximal" is a concrete term in the world of partially-ordered sets (such as commit history ordered by reachability across child-to-parent relationships). It's important to distinguish from "starting points" because the inputs to the command are a list of starting points, not all of which are maximal within the set. In fact, if some positive starting points are reachable from the negative starting points, then they are already excluded.
My familiarity with this term is skewed by my experience working with such terms, so I'm very open to new names for this option.
Your comparison to --boundary is interesting, because --boundary _adds_ commits to the range by selecting the commits from the negative range that are reachable from the output commits. --maximal as defined here _restricts_ to the output of commits in the range. It's interaction with --boundary is trivial because no boundary commits would be included as they are necessarily reachable from a maximal commit.
> The option is listed among options that affect the way the > simplification is performed. But is this true? Isn't it just an option > that changes what output is produced?
You're right that this is poorly placed. I'll put it in a better location in v2.
Thanks, -Stolee