Skip to contentSkip to conversation

gitweb: use HEAD as primary sort key in git_get_heads_list()

RFC PATCH New Greg Hurrell 3 participants 10 messages Jun 6, 2021 – Jun 9, 2021

lore
Share & tools
lore
#0 lore raw

RFC PATCH 1/1 gitweb: use HEAD as primary sort key in git_get_heads_list()

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

In my own repos I have started to move from "master" towards "main", but I keep "master" around and in sync with "main" so as not to break existing clones. As such, they always point at the same commit.

This means that in the "heads" listing of a gitweb instance, the display order ends up being determined by how git for-each-ref decides to tie-break "master" and "main"

For example, right now on a sample repo, gitweb shows the heads in this order, even though "master" and "main" reference the same commit. The tie-breaking evidently isn't happening lexicographically:

- master
- main
- pu
- next

So, 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:

- main
- master
- pu
- next

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

---
 gitweb/gitweb.perl | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
gitweb/gitweb.perl +2 -1
index e09e024a09..e5270b0291 100755
@@ -3796,7 +3796,8 @@ sub git_get_heads_list {
 	my @headslist;
 
 	open my $fd, '-|', git_cmd(), 'for-each-ref',
-		($limit ? '--count='.($limit+1) : ()), '--sort=-committerdate',
+		($limit ? '--count='.($limit+1) : ()),
+		'--sort=-committerdate', '--sort=-HEAD',
 		'--format=%(objectname) %(refname) %(subject)%00%(committer)',
 		@patterns
 		or return;
Signature · 1 line
2.29.2
#1 lore raw

RFC PATCH 1/1 gitweb: use HEAD as primary sort key in git_get_heads_list()

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

In my own repos I have started to move from "master" towards "main", but I keep "master" around and in sync with "main" so as not to break existing clones. As such, they always point at the same commit.

This means that in the "heads" listing of a gitweb instance, the display order ends up being determined by how git for-each-ref decides to tie-break "master" and "main"

For example, right now on a sample repo, gitweb shows the heads in this order, even though "master" and "main" reference the same commit. The tie-breaking evidently isn't happening lexicographically:

- master
- main
- pu
- next

So, 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:

- main
- master
- pu
- next

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

---

Resending because I forgot the Signed-off-by the first time. Sorry for the noise.

 gitweb/gitweb.perl | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
gitweb/gitweb.perl +2 -1
index e09e024a09..e5270b0291 100755
@@ -3796,7 +3796,8 @@ sub git_get_heads_list {
 	my @headslist;
 
 	open my $fd, '-|', git_cmd(), 'for-each-ref',
-		($limit ? '--count='.($limit+1) : ()), '--sort=-committerdate',
+		($limit ? '--count='.($limit+1) : ()),
+		'--sort=-committerdate', '--sort=-HEAD',
 		'--format=%(objectname) %(refname) %(subject)%00%(committer)',
 		@patterns
 		or return;
Signature · 1 line
2.29.2
#2 lore raw
Quoted 11 lines · Greg Hurrell

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

In my own repos I have started to move from "master" towards "main", but I keep "master" around and in sync with "main" so as not to break existing clones. As such, they always point at the same commit.

This means that in the "heads" listing of a gitweb instance, the display order ends up being determined by how git for-each-ref decides to tie-break "master" and "main"

Hmm. I'd have expected it to, because we start the list in lexicographic order. I suspect the sort we use simply isn't stable (in a simple 3-ref example I made, "main" did sort before "master" by default). That would be easy to fix, of course, but there may be value in using the HEAD rule anyway.

Quoted 9 lines

For example, right now on a sample repo, gitweb shows the heads in this order, even though "master" and "main" reference the same commit. The tie-breaking evidently isn't happening lexicographically:

- master
- main
- pu
- next

Quoted 8 lines

So, 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:

- main
- master
- pu
- next

In your earlier example, it sounded like you were primarily concerned with breaking ties. But here it sounds like you're proposing putting the HEAD first _regardless_ of the committer timestamp.

I don't have a strong feeling either way on that. It may surface an older branch, but in general I'd expect the HEAD to be reasonably up-to-date (unless somebody has a weird workflow that does not really use it at all, and expects people to always clone with "-b" or whatever. We can probably discount that).

It doesn't help the stability of non-HEAD branches that are in ties. I.e., I wonder if this should be two separate patches:

1. break ties by name, like:

       git for-each-ref --sort=refname --sort=-committerdate

2. emphasize the HEAD branch, even if it isn't the newest:

       git for-each-ref --sort=refname --sort=-committerdate --sort=-HEAD

-Peff

#3 lore raw
Quoted 4 lines · Jeff King

In your earlier example, it sounded like you were primarily concerned with breaking ties. But here it sounds like you're proposing putting the HEAD first _regardless_ of the committer timestamp.

I arrived there organically. My initial goal was merely to find out why "master" was sorting ahead of "main" even after I switched HEAD, as it seemed arbitrary and possibly hard-coded.

Adding --sort=-HEAD wallpapers over the problem by forcing HEAD to the top, but it doesn't address the underlying arbitrariness/non-determinism of how refs with equal committerdate get treated.

So I like your idea of splitting this into two separate changes much better:

Quoted 7 lines

1. break ties by name, like:

       git for-each-ref --sort=refname --sort=-committerdate

2. emphasize the HEAD branch, even if it isn't the newest:

       git for-each-ref --sort=refname --sort=-committerdate --sort=-HEAD

I think adding "1" is a clear improvement. "2" is more debatable (I think it would be of practical use, but as you said, HEAD is very often going to be the most recently committed thing anyway). In my specific use case (where "main" is the HEAD but "master" is kept in sync with it automatically so as not to break existing clones), sorting by refname _happens_ to mean that "main" will come before "master"; but that is of course a quirk of my branch naming choices and not something that should be relied upon.

In any case, splitting this into two pieces sounds good: we have the option of taking one or both (or none).

Cheers,
Greg

#4 lore raw

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.

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.

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

---

Quoted 8 lines · Greg Hurrell
Quoted 7 lines · Jeff King

1. break ties by name, like:

       git for-each-ref --sort=refname --sort=-committerdate

2. emphasize the HEAD branch, even if it isn't the newest:

       git for-each-ref --sort=refname --sort=-committerdate --sort=-HEAD

I was wracking my brains over this one trying to figure out why it wasn't already doing the right thing based on what I see in ref-filter.c. It sure looks like the --sort=refname fallback should be automatic, but I wasn't seeing it happen in my gitweb instance.

Turns out there was a bug that you fixed in 7c5045fc180ed09ed4cb5 which made it in soon after v2.20.4 fixing a problem. I was seeing different behavior on gitweb running on Amazon Linux AMI, because that's still using Git v2.18.5.

So, that means "1" isn't necessary. "2" is the only possibly interesting bit. I've reworded the commit text accordingly, still labeled as "RFC" to see if there is any consensus on this being a good idea or not.

Greg

 gitweb/gitweb.perl | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
gitweb/gitweb.perl +2 -1
index e09e024a09..e5270b0291 100755
@@ -3796,7 +3796,8 @@ sub git_get_heads_list {
 	my @headslist;
 
 	open my $fd, '-|', git_cmd(), 'for-each-ref',
-		($limit ? '--count='.($limit+1) : ()), '--sort=-committerdate',
+		($limit ? '--count='.($limit+1) : ()),
+		'--sort=-committerdate', '--sort=-HEAD',
 		'--format=%(objectname) %(refname) %(subject)%00%(committer)',
 		@patterns
 		or return;
Signature · 1 line
2.29.2
#5 lore raw
Quoted 5 lines · Greg Hurrell

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.

Quoted 8 lines

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.

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

Your use of "seems" in the final paragraph is a leftover from the earlier commit message, and I think weakens your message. It's OK to assert that it really _is_ a useful change, I would say. :)

This patch looks good to me overall. In addition to dropping the RFC tag, you're more likely to get attention by having a subject line without "Re:" in it (so people realize it's a patch to look at, and not just a continuation of the discussion).

Quoted 15 lines · Greg Hurrell
Quoted 8 lines · Jeff King
Quoted 7 lines

1. break ties by name, like:

       git for-each-ref --sort=refname --sort=-committerdate

2. emphasize the HEAD branch, even if it isn't the newest:

       git for-each-ref --sort=refname --sort=-committerdate --sort=-HEAD

I was wracking my brains over this one trying to figure out why it wasn't already doing the right thing based on what I see in ref-filter.c. It sure looks like the --sort=refname fallback should be automatic, but I wasn't seeing it happen in my gitweb instance.

Quoted 4 lines

Turns out there was a bug that you fixed in 7c5045fc180ed09ed4cb5 which made it in soon after v2.20.4 fixing a problem. I was seeing different behavior on gitweb running on Amazon Linux AMI, because that's still using Git v2.18.5.

Heh, OK. I almost suggested "gee, wouldn't it be nice if we used the refname as a fallback tie-breaker by default". You'd think I would either remember such fixes, or at least bother to look at the code. :)

Quoted 3 lines

So, that means "1" isn't necessary. "2" is the only possibly interesting bit. I've reworded the commit text accordingly, still labeled as "RFC" to see if there is any consensus on this being a good idea or not.

Yep, I agree on all counts.

In my experience gitweb doesn't tend to get a lot of interest from reviewers, and I consider it mostly in maintenance mode these days. So be prepared for silence. In that case, I'd give it a few days and repost the patch to see if Junio is interested in picking it up.

-Peff

#6 lore raw
In reply to Greg Hurrell
Quoted 4 lines · Greg Hurrell

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

Quoted 4 lines

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

Quoted 3 lines

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?

gitweb/gitweb.perl sub git_get_heads_list { · line 3800

Quoted 2 lines
gitweb/gitweb.perl +2 -0
+		($limit ? '--count='.($limit+1) : ()),
+		'--sort=-committerdate', '--sort=-HEAD',

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

#7 lore raw
Quoted 6 lines · Junio C Hamano
Quoted 3 lines · Greg Hurrell <[email protected] <mailto:greg%40hurrell.net>> writes:

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

Quoted 6 lines

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.

Yeah, I'm not 100% convinced either. Displaying a "*" indicator would be a straightforward change to git_heads_body(), but it would be a break with the visual style of all the other tables in the UI.

On the other hand, boosting HEAD to the top like the proposed commit does feel a bit arbitrary, given that the other list views in the UI seem mostly to be sorted by recency. (But then again, what HEAD is and what it means is quintessentially arbitrary, so maybe this _is_ appropriate.)

One thing I do notice is that there is already a current_head CSS class applied to the corresponding row, so it would be possible for the gitweb owner to make tha row stand out however they pleased.

In short, I am happy to amend the commit message but I fear the rationale for it is a bit weak. If nobody chimes in with a resounding endorsement, I am inclined to probably drop it.

Quoted 2 lines

Wasn't your motivating example about tiebreaking between 'main' and 'master' that always point at the same commit?

Yes indeed, that was the original motivation, although after the fix in 7c5045fc180ed09ed4cb5 the tie-breaking by refname already has the equivalent desired effect, albeit coincidentally.

Perhaps the sort keys _should_ be -committerdate, then -HEAD, then refname (implicit default); ie. --sort=-HEAD --sort=-committerdate (which is the opposite order to what I have in the patch). I would have prepared the patch in that way in the first place if my testing hadn't been confounded by the fact that I was running an older version of Git on the installation where I was trying it out.

I feel the argument for using HEAD as a tiebreaker is easier to make than the case for using it as a primary sort key, because it is a less invasive change. If there is support for that idea, I'll tweak the patch.

Cheers,
Greg

#8 lore raw
Quoted 22 lines · Greg Hurrell

One thing I do notice is that there is already a current_head CSS class applied to the corresponding row, so it would be possible for the gitweb owner to make tha row stand out however they pleased.

In short, I am happy to amend the commit message but I fear the rationale for it is a bit weak. If nobody chimes in with a resounding endorsement, I am inclined to probably drop it.

Quoted 2 lines

Wasn't your motivating example about tiebreaking between 'main' and 'master' that always point at the same commit?

Yes indeed, that was the original motivation, although after the fix in 7c5045fc180ed09ed4cb5 the tie-breaking by refname already has the equivalent desired effect, albeit coincidentally.

Perhaps the sort keys _should_ be -committerdate, then -HEAD, then refname (implicit default); ie. --sort=-HEAD --sort=-committerdate (which is the opposite order to what I have in the patch). I would have prepared the patch in that way in the first place if my testing hadn't been confounded by the fact that I was running an older version of Git on the installation where I was trying it out.

Quoted 4 lines

I feel the argument for using HEAD as a tiebreaker is easier to make than the case for using it as a primary sort key, because it is a less invasive change. If there is support for that idea, I'll tweak the patch.

I agree that using HEADness as a tiebreaker is a much easier sell.

Another idea would be to give site administrators (or even to the end users via UI) an option to tweak how they are sorted.

#9 lore raw

PATCH v2 1/1 gitweb: use HEAD as secondary sort key in git_get_heads_list()

The "heads" section on the gitweb summary page shows heads in -committerdate order (ie. the most recently-modified ones at the top), tie-breaking equal-dated refs using the implicit refname sort fallback. This recency-based ordering appears in multiple places in the UI, such as the project listing, the tags list, and even the shortlog and log views.

Given two equal-dated refs, however, sorting the HEAD ref before the non-HEAD ref provides more useful signal than merely sorting by refname. For example, say we had "master" and "trunk" both pointing at the same commit but "trunk" was HEAD, sorting "trunk" first helps communicate its special status as the default branch that you'll check out if you clone the repo.

Add -HEAD as a secondary sort key to the git for-each-ref call in git_get_heads_list() to provide the desired behavior. The most recently committed refs will appear first, but HEAD-ness will be used as a tie-breaker. Note that refname is the implicit fallback sort key, which means that two same-dated non-HEAD refs will continue to be sorted in lexicographical order, as they are today.

---

As per list discussion, this is an easier sell than the prior version of this patch (which made HEAD the _primary_ sort key). I'm dropping the RFC qualifier accordingly.

Sorry for the back-and-forth on this one. Using HEAD is the tie-breaker is what I wanted to do originally, but because I was testing on an ancient Git version with a sorting bug, the straightforward approach didn't work (:facepalm:), and I went off into the weeds.

 gitweb/gitweb.perl | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
gitweb/gitweb.perl +2 -1
index e09e024a09..fbd1c20a23 100755
@@ -3796,7 +3796,8 @@ sub git_get_heads_list {
 	my @headslist;
 
 	open my $fd, '-|', git_cmd(), 'for-each-ref',
-		($limit ? '--count='.($limit+1) : ()), '--sort=-committerdate',
+		($limit ? '--count='.($limit+1) : ()),
+		'--sort=-HEAD', '--sort=-committerdate',
 		'--format=%(objectname) %(refname) %(subject)%00%(committer)',
 		@patterns
 		or return;
Signature · 1 line
2.29.2