Subject: Re: [RFC PATCH] gitweb: use HEAD as primary sort key in git_get_heads_list()

From: Junio C Hamano <[email-masked]>
Date: Wed, 09 Jun 2021 09:15:00 +0900

Greg Hurrell <[email-masked]> writes:

> Prior to this commit, the "heads" section on a gitweb summary page would
> list the heads in `-committerdate` order (ie. the most recently-modified
> ones at the top), tie-breaking equal-dated refs using the implicit
> `refname` sort fallback.

Please lose "Prior to this commit"; when we talk about the state of
the code, we talk about what we have _without_ the proposed change,
so "Currently", etc. are noisewords.

And then we go on to explain why the current behaviour presented in
the first paragraph is undesirable, and how the proposal wants to
change the world to a better place.  That is missing here in the
proposed log message.

And then we give an order to the codebase to "become like so" in
imperative mood, perhaps turn this paragraph

> This commit adds another `--sort` parameter to the `git for-each-ref`
> invocation in `git_get_heads_list()`, ensuring that the `HEAD` ref
> always ends up getting sorted to the top, seeing as it is typically the
> "primary" line of development in some sense.

into:

    In addition to sorting with committerdate (most recent first),
    first show the primary branch that is pointed at with HEAD, by
    adding another `--sort` parameter ... 

> This seems to be a useful change, because I can't see anywhere else in
> the gitweb UI where we actually indicate to the user what the "default"
> branch is (ie. what they'll checkout if they run `git clone`).

The justification is a bit too weak to convince readers that using
%(HEAD) as the primary sort key to list the branch first in the list
view is *the* best way to solve the "it is unclear which one is the
defaul branch" problem, though.  An obvious alternative would be to
show '*' next to such a branch just like "git branch --list" does,
without changing the sort order at all, for example.

I am not sure if using it as the primary key is a good idea, though.
Wasn't your motivating example about tiebreaking between 'main' and
'master' that always point at the same commit?

> +		($limit ? '--count='.($limit+1) : ()),
> +		'--sort=-committerdate', '--sort=-HEAD',

Comparing %(HEAD), which is either ' ' or '*', for each ref?  It is
beyond "cute".  Nicely done.