Re: [PATCH] revision: add --maximal option

From: Derrick Stolee <stolee@gmail.com>
Date: Jan 19, 2026, 16:44 UTC
Message-ID: <3fab80c8-f602-44d5-8e7d-436982a5e3a8@gmail.com>
In-Reply-To: <1ce18cac-f988-4741-b9dd-6c1cf2d4e6af@kdbg.org>

On 1/19/2026 6:15 AM, Johannes Sixt wrote:

Show 20 quoted lines

> Am 18.01.26 um 19:27 schrieb Derrick Stolee:
>> On 1/18/26 4:05 AM, Johannes Sixt wrote:
>>> Am 18.01.26 um 03:34 schrieb Derrick Stolee via GitGitGadget:
>>>> 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.
> 
> AFAICS, we don't have options named after graph- or set-theoretical
> terms, but tend to stick to terms established in the Git ecosystem. I
> assume that "maximal" isn't a meaning that an average Git user would
> associate with the operation that is performed here.

My mindset is usually "all words are made up by somebody" and since there isn't an established term for this in the existing Git ecosystem, it is up to us to create a term. Borrowing one that exists elsewhere is a valuable way to build upon any context that term brings with it.

It is also helpful that the term has an explicit technical definition that means exactly what we're using it for here. It explicitly differentiates from any "maximum" or confusion with a collapse to a total order (such as Git's --date-order or --topo-order apply).

> But even if we decide to use "maximal", the option must be named
> something other than *just* "--maximal"; this is simply too generic.
> Perhaps "--only-maximal" or "--maximal-only".

When the argument is moved in the documentation into the set of
filters, then the fact that --maximal restricts the set of commits
makes any modifier such as "only" redundant.

Show 6 quoted lines

> Other ideas:
> - --hide-reachable
> - --range-head
> - --range-head-only
> - --most-recent
> - --most-recent-only

These all have issues, such as being technically wrong (maximal commits are reachable) or imply total orders, date orders, or generally only a single result.

Show 8 quoted lines

>> [--maximal]'s interaction with
>> --boundary is trivial because no boundary commits would be included as
>> they are necessarily reachable from a maximal commit.
> 
> So, --boundary --maximal shows only the maximal commits? That sounds
> unexpected. Boundary commits are shown with additional mark-up; they
> don't need to be suppressed. But in a first iteration it's probably
> better to just make the two options incompatible.

Sure. But I'd like to counter that filters like --author also restrict the set, including not showing boundary commits that don't fit the --author pattern. It just happens that no boundary commits are also maximal by definition.

I do sense that a lot of this is a matter of taste, and that you and I differ greatly in our tastes on this topic. I look forward to more opinions that can lead us towards one side or another (or in a new direction).

Thanks, -Stolee