[PATCH 00/11] www_coderepo: subjective web stuffs

[PATCH 00/11] www_coderepo: subjective web stuffs

[Eric Wong]

Aside from avoiding FD waste for /dev/null in common
deployments, there's not much _measurably_ better.

Eric Wong (11):
  qspawn: drop lineno from command failure warning
  viewvcs: add path name hint based on `b=' query param
  viewvcs: prepopulate search bar with dfpost + dfn
  www_coderepo: show /$INBOX/?t=$DATE link for commits
  www_coderepo: eliminate debug log footer
  http: reuse STDIN if it's already /dev/null
  viewvcs: expand on path names being "non-authoritative"
  viewvcs: show message for 404||500 errors
  solver_git: remove extraneous leading `-'
  www_coderepo: remove some needless return statements
  viewvcs: improve tree glossary view

 lib/PublicInbox/HTTP.pm        |  8 ++++-
 lib/PublicInbox/Qspawn.pm      |  2 +-
 lib/PublicInbox/RepoTree.pm    |  3 +-
 lib/PublicInbox/SolverGit.pm   |  2 +-
 lib/PublicInbox/ViewVCS.pm     | 56 ++++++++++++++++++++++++++--------
 lib/PublicInbox/WwwCoderepo.pm | 50 +++++++++++++++---------------
 t/solver_git.t                 |  2 +-
 7 files changed, 81 insertions(+), 42 deletions(-)

[PATCH 01/11] qspawn: drop lineno from command failure warning

[Eric Wong]

git, cgit, or any other command failing isn't an error
we can do anything about in qspawn, so don't have Perl
emit line number info and needlessly pollute logs.
---
 lib/PublicInbox/Qspawn.pm | 2 +-
 t/solver_git.t            | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/PublicInbox/Qspawn.pm b/lib/PublicInbox/Qspawn.pm
index cc81a4cd..5e4fd5cb 100644
--- a/lib/PublicInbox/Qspawn.pm
+++ b/lib/PublicInbox/Qspawn.pm
@@ -85,7 +85,7 @@ sub finalize ($) {
 		if (my $dst = $self->{qsp_err}) {
 			$$dst .= $$dst ? " $err" : "; $err";
 		}
-		warn "@{$self->{cmd}}: $err" if !$self->{-quiet};
+		warn "@{$self->{cmd}}: $err\n" if !$self->{-quiet};
 	}
 
 	my ($env, $qx_cb, $qx_arg, $qx_buf) =
diff --git a/t/solver_git.t b/t/solver_git.t
index 06d75816..122cf888 100644
--- a/t/solver_git.t
+++ b/t/solver_git.t
@@ -336,7 +336,7 @@ EOF
 			open $fh, '>', "$tmpdir/stderr.log" or xbail $!;
 			ok($s =~ s/^fatal: your current branch.*?\n//sm,
 				'got current branch warning');
-			ok($s =~ s/^.*? exit status=[1-9]+ .*?\n//sm,
+			ok($s =~ s/^.*? exit status=[1-9]+\n\z//sm,
 				'got exit status warning');
 			is($s, '', 'no unexpected warnings on empty coderepo');
 		}

[PATCH 02/11] viewvcs: add path name hint based on `b=' query param

[Eric Wong]

Of course, we need a note saying it's non-authoritative since
anybody can fiddle with the `b=' parameter in the URL.
---
 lib/PublicInbox/ViewVCS.pm | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/lib/PublicInbox/ViewVCS.pm b/lib/PublicInbox/ViewVCS.pm
index 37b688ed..00db8ff2 100644
--- a/lib/PublicInbox/ViewVCS.pm
+++ b/lib/PublicInbox/ViewVCS.pm
@@ -501,8 +501,13 @@ sub solve_result {
 	return show_tag($ctx, $res) if $type eq 'tag';
 	return show_other($ctx, $res) if $type ne 'blob';
 	my $paths = $ctx->{-paths} //= do {
-		my $path = to_filename($di->{path_b}//$hints->{path_b}//'blob');
+		my $fn = $di->{path_b} // $hints->{path_b};
+		my $path = to_filename($fn // 'blob');
 		my $raw_more = qq[(<a\nhref="$path">raw</a>)];
+
+		# XXX not sure if this is the correct wording
+		defined($fn) and $raw_more .=
+"\nname: ${\ascii_html($fn)} \t # note: path name is non-authoritative";
 		[ $path, $raw_more ];
 	};
 

[PATCH 03/11] viewvcs: prepopulate search bar with dfpost + dfn

[Eric Wong]

I'm not sure if this will get overlooked by users, but maybe
it can serve as a hint...
---
 lib/PublicInbox/RepoTree.pm | 2 ++
 lib/PublicInbox/ViewVCS.pm  | 6 +++++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/lib/PublicInbox/RepoTree.pm b/lib/PublicInbox/RepoTree.pm
index 7434e9b2..4c6ed840 100644
--- a/lib/PublicInbox/RepoTree.pm
+++ b/lib/PublicInbox/RepoTree.pm
@@ -56,6 +56,8 @@ sub tree_show { # git check_async callback
 	my ($bn) = ($ctx->{-path} =~ m!/?([^/]+)\z!);
 	if ($type eq 'blob') {
 		my $obj = ascii_html($ctx->{-obj});
+		$ctx->{-q_value_html} = 'dfn:'.ascii_html($ctx->{-path}) .
+			' dfpost:'.substr($oid, 0, 7);
 		$ctx->{-paths} = [ $bn, qq[(<a
 href="$ctx->{-upfx}$oid/s/$bn">raw</a>)
 \$ git show $obj\t# shows this blob on the CLI] ];
diff --git a/lib/PublicInbox/ViewVCS.pm b/lib/PublicInbox/ViewVCS.pm
index 00db8ff2..51a7bcbc 100644
--- a/lib/PublicInbox/ViewVCS.pm
+++ b/lib/PublicInbox/ViewVCS.pm
@@ -500,8 +500,8 @@ sub solve_result {
 	return show_tree($ctx, $res) if $type eq 'tree';
 	return show_tag($ctx, $res) if $type eq 'tag';
 	return show_other($ctx, $res) if $type ne 'blob';
+	my $fn = $di->{path_b} // $hints->{path_b};
 	my $paths = $ctx->{-paths} //= do {
-		my $fn = $di->{path_b} // $hints->{path_b};
 		my $path = to_filename($fn // 'blob');
 		my $raw_more = qq[(<a\nhref="$path">raw</a>)];
 
@@ -510,6 +510,10 @@ sub solve_result {
 "\nname: ${\ascii_html($fn)} \t # note: path name is non-authoritative";
 		[ $path, $raw_more ];
 	};
+	$ctx->{-q_value_html} //= do {
+		my $s = defined($fn) ? 'dfn:'.ascii_html($fn).' ' : '';
+		$s.'dfpost:'.substr($oid, 0, 7);
+	};
 
 	if ($size > $MAX_SIZE) {
 		return stream_large_blob($ctx, $res) if defined $ctx->{fn};

[PATCH 04/11] www_coderepo: show /$INBOX/?t=$DATE link for commits

[Eric Wong]

While we can't inexpensively search for git commits based on the
timestamp, coderepos configured for inboxes can still look up
messages based on the inbox URL.
---
 lib/PublicInbox/ViewVCS.pm | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/lib/PublicInbox/ViewVCS.pm b/lib/PublicInbox/ViewVCS.pm
index 51a7bcbc..b238e832 100644
--- a/lib/PublicInbox/ViewVCS.pm
+++ b/lib/PublicInbox/ViewVCS.pm
@@ -208,13 +208,15 @@ sub cmt_finalize {
 		$au =~ s/>/>$x/;
 	}
 	$_ = ascii_html($_) for ($au, $co);
+	my $ibx_url = ibx_url_for($ctx) // $upfx;
 	$au =~ s!(> +)([0-9]{4,}-\S+ \S+)!
 		my ($gt, $t) = ($1, $2);
 		$t =~ tr/ :-//d;
 		qq($gt<a
-href="$upfx?t=$t"
+href="$ibx_url?t=$t"
 title="list contemporary emails">$2</a>)
 		!e;
+
 	$ctx->{-title_html} = $s = $ctx->{-linkify}->to_html($s);
 	my ($P, $p, $pt) = delete @$ctx{qw(-cmt_P -cmt_p -cmt_pt)};
 	$_ = qq(<a href="$upfx$_/s/">).shift(@$p).'</a> '.shift(@$pt) for @$P;

[PATCH 05/11] www_coderepo: eliminate debug log footer

[Eric Wong]

WwwCoderepo is for viewing blobs already in code repositories,
so there's no place for a debug log showing which mails were
used to arrive at a given blob.  The debug footer remains for
/$INBOX/$OID/s/ URLs, of course.
---
 lib/PublicInbox/RepoTree.pm    |  1 -
 lib/PublicInbox/ViewVCS.pm     | 12 +++++++++---
 lib/PublicInbox/WwwCoderepo.pm | 17 +++++++++++++++--
 3 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/lib/PublicInbox/RepoTree.pm b/lib/PublicInbox/RepoTree.pm
index 4c6ed840..3a848c6f 100644
--- a/lib/PublicInbox/RepoTree.pm
+++ b/lib/PublicInbox/RepoTree.pm
@@ -51,7 +51,6 @@ sub tree_show { # git check_async callback
 	my ($oid, $type, $size, $ctx) = @_;
 	return find_missing($ctx) if $type eq 'missing';
 
-	open $ctx->{lh}, '<', \(my $dbg_log = '') or die "open(scalar): $!";
 	my $res = [ $ctx->{git}, $oid, $type, $size ];
 	my ($bn) = ($ctx->{-path} =~ m!/?([^/]+)\z!);
 	if ($type eq 'blob') {
diff --git a/lib/PublicInbox/ViewVCS.pm b/lib/PublicInbox/ViewVCS.pm
index b238e832..60cc1376 100644
--- a/lib/PublicInbox/ViewVCS.pm
+++ b/lib/PublicInbox/ViewVCS.pm
@@ -62,8 +62,11 @@ sub dbg_log ($) {
 		return '<pre>debug log seek error</pre>';
 	}
 	$log = do { local $/; <$log> } // do {
-		warn "readline(log): $!";
-		return '<pre>debug log read error</pre>';
+		if (!eof($log)) {
+			warn "readline(log): $!";
+			return '<pre>debug log read error</pre>';
+		}
+		'';
 	};
 	return '' if $log eq '';
 	$ctx->{-linkify} //= PublicInbox::Linkify->new;
@@ -586,7 +589,10 @@ sub show ($$;$) {
 	}
 	$ctx->{fn} = $fn;
 	$ctx->{-tmp} = File::Temp->newdir("solver.$oid_b-XXXX", TMPDIR => 1);
-	open $ctx->{lh}, '+>>', "$ctx->{-tmp}/solve.log" or die "open: $!";
+	unless ($ctx->{lh}) {
+		open $ctx->{lh}, '+>>', "$ctx->{-tmp}/solve.log" or
+			die "open: $!";
+	}
 	my $solver = PublicInbox::SolverGit->new($ctx->{ibx},
 						\&solve_result, $ctx);
 	$solver->{gits} //= [ $ctx->{git} ];
diff --git a/lib/PublicInbox/WwwCoderepo.pm b/lib/PublicInbox/WwwCoderepo.pm
index 5ca8ef55..024a9d8f 100644
--- a/lib/PublicInbox/WwwCoderepo.pm
+++ b/lib/PublicInbox/WwwCoderepo.pm
@@ -8,6 +8,7 @@
 package PublicInbox::WwwCoderepo;
 use v5.12;
 use File::Temp 0.19 (); # newdir
+use POSIX qw(O_RDWR F_GETFL);
 use PublicInbox::ViewVCS;
 use PublicInbox::WwwStatic qw(r);
 use PublicInbox::GitHTTPBackend;
@@ -60,6 +61,15 @@ sub new {
 	};
 	$self->{$_} = 10 for qw(summary_branches summary_tags);
 	$self->{$_} = 10 for qw(summary_log);
+
+	# try reuse STDIN if it's already /dev/null
+	open $self->{log_fh}, '+>', '/dev/null' or die "open: $!";
+	my @l = stat($self->{log_fh}) or die "stat: $!";
+	my @s = stat(STDIN) or die "stat(STDIN): $!";
+	if ("@l[0, 1]" eq "@s[0, 1]") {
+		my $f = fcntl(STDIN, F_GETFL, 0) // die "F_GETFL: $!";
+		$self->{log_fh} = *STDIN{IO} if $f & O_RDWR;
+	}
 	$self;
 }
 
@@ -216,12 +226,15 @@ sub srv { # endpoint called by PublicInbox::WWW
 	}
 	$path_info =~ m!\A/(.+?)/\z! and
 		($ctx->{git} = $cr->{$1}) and return summary($self, $ctx);
-	$path_info =~ m!\A/(.+?)/([a-f0-9]+)/s/([^/]+)?\z! and
-			($ctx->{git} = $cr->{$1}) and
+	if ($path_info =~ m!\A/(.+?)/([a-f0-9]+)/s/([^/]+)?\z! and
+			($ctx->{git} = $cr->{$1})) {
+		$ctx->{lh} = $self->{log_fh};
 		return PublicInbox::ViewVCS::show($ctx, $2, $3);
+	}
 
 	if ($path_info =~ m!\A/(.+?)/tree/(.*)\z! and
 			($ctx->{git} = $cr->{$1})) {
+		$ctx->{lh} = $self->{log_fh};
 		return PublicInbox::RepoTree::srv_tree($ctx, $2) // r(404);
 	}
 

[PATCH 06/11] http: reuse STDIN if it's already /dev/null

[Eric Wong]

It's typical for -netd/-httpd to have STDIN pointed to
/dev/null, so try to use that instead of opening another
file description.
---
 lib/PublicInbox/HTTP.pm | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/lib/PublicInbox/HTTP.pm b/lib/PublicInbox/HTTP.pm
index 0dba425d..ca162939 100644
--- a/lib/PublicInbox/HTTP.pm
+++ b/lib/PublicInbox/HTTP.pm
@@ -43,7 +43,13 @@ use Errno qw(EAGAIN);
 our $MAX_REQUEST_BUFFER = $ENV{GIT_HTTP_MAX_REQUEST_BUFFER} ||
 			(10 * 1024 * 1024);
 
-open(my $null_io, '<', '/dev/null') or die "failed to open /dev/null: $!";
+open(my $null_io, '<', '/dev/null') or die "open /dev/null: $!";
+{
+	my @n = stat($null_io) or die "stat(/dev/null): $!";
+	my @i = stat(STDIN) or die "stat(STDIN): $!";
+	$null_io = *STDIN{IO} if "@n[0, 1]" eq "@i[0, 1]";
+}
+
 my $http_date;
 my $prev = 0;
 sub http_date () {

[PATCH 07/11] viewvcs: expand on path names being "non-authoritative"

[Eric Wong]

Hopefully this makes sense...
---
 lib/PublicInbox/ViewVCS.pm | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/lib/PublicInbox/ViewVCS.pm b/lib/PublicInbox/ViewVCS.pm
index 60cc1376..0dfe6081 100644
--- a/lib/PublicInbox/ViewVCS.pm
+++ b/lib/PublicInbox/ViewVCS.pm
@@ -509,11 +509,19 @@ sub solve_result {
 	my $paths = $ctx->{-paths} //= do {
 		my $path = to_filename($fn // 'blob');
 		my $raw_more = qq[(<a\nhref="$path">raw</a>)];
+		my @def;
 
 		# XXX not sure if this is the correct wording
-		defined($fn) and $raw_more .=
-"\nname: ${\ascii_html($fn)} \t # note: path name is non-authoritative";
-		[ $path, $raw_more ];
+		if (defined($fn)) {
+			$raw_more .= qq(
+name: ${\ascii_html($fn)} \t # note: path name is non-authoritative<a
+href="#pathdef" id=top>(*)</a>);
+			$def[0] = "<hr><pre\nid=pathdef>" .
+'(*) Git path names are given by the tree(s) the blob belongs to.
+    Blobs themselves have no identifier aside from the hash of its contents.'.
+qq(<a\nhref="#top">^</a></pre>);
+		}
+		[ $path, $raw_more, @def ];
 	};
 	$ctx->{-q_value_html} //= do {
 		my $s = defined($fn) ? 'dfn:'.ascii_html($fn).' ' : '';
@@ -547,7 +555,7 @@ sub show_blob { # git->cat_async callback
 		return delete($ctx->{-wcb})->([200, $h, [ $$blob ]]);
 	}
 
-	my ($path, $raw_more) = @{delete $ctx->{-paths}};
+	my ($path, $raw_more, @def) = @{delete $ctx->{-paths}};
 	$bin and return html_page($ctx, 200,
 				"<pre>blob $oid $size bytes (binary)" .
 				" $raw_more</pre>".dbg_log($ctx));
@@ -574,7 +582,7 @@ sub show_blob { # git->cat_async callback
 	$x .= '</pre></td><td><pre> </pre></td>'. # pad for non-CSS users
 		"<td\nclass=lines><pre\nstyle='white-space:pre'><code>";
 	html_page($ctx, 200, $x, $ctx->{-linkify}->linkify_2($$blob),
-		'</code></pre></td></tr></table>'.dbg_log($ctx));
+		'</code></pre></td></tr></table>'.dbg_log($ctx), @def);
 }
 
 # GET /$INBOX/$GIT_OBJECT_ID/s/

[PATCH 08/11] viewvcs: show message for 404||500 errors

[Eric Wong]

Since the debug log isn't present from the /$REPO/ URLs,
the lack of debug log makes 404s look confusing.
---
 lib/PublicInbox/ViewVCS.pm | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/lib/PublicInbox/ViewVCS.pm b/lib/PublicInbox/ViewVCS.pm
index 0dfe6081..99f5e24f 100644
--- a/lib/PublicInbox/ViewVCS.pm
+++ b/lib/PublicInbox/ViewVCS.pm
@@ -497,8 +497,9 @@ sub show_tag ($$) {
 sub solve_result {
 	my ($res, $ctx) = @_;
 	my $hints = delete $ctx->{hints};
-	$res or return html_page($ctx, 404, dbg_log($ctx));
-	ref($res) eq 'ARRAY' or return html_page($ctx, 500, dbg_log($ctx));
+	$res or return html_page($ctx, 404, 'Not found', dbg_log($ctx));
+	ref($res) eq 'ARRAY' or
+		return html_page($ctx, 500, 'Internal error', dbg_log($ctx));
 
 	my ($git, $oid, $type, $size, $di) = @$res;
 	return show_commit($ctx, $res) if $type eq 'commit';

[PATCH 09/11] solver_git: remove extraneous leading `-'

[Eric Wong]

It was a harmless negation, I must've pasted a line from a diff
and forgotten to chop off the first character :x

Fixes: 6f5b238bae5c "solver: early make hints detection more robust"
---
 lib/PublicInbox/SolverGit.pm | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/PublicInbox/SolverGit.pm b/lib/PublicInbox/SolverGit.pm
index 16521ba7..38fba0ca 100644
--- a/lib/PublicInbox/SolverGit.pm
+++ b/lib/PublicInbox/SolverGit.pm
@@ -82,7 +82,7 @@ sub solve_existing ($$) {
 	my ($oid_full, $type, $size) = $git->check($oid_b);
 
 	if ($oid_b eq ($oid_full // '') || (defined($type) &&
--				(!$self->{have_hints} || $type eq 'blob'))) {
+				(!$self->{have_hints} || $type eq 'blob'))) {
 		delete $want->{try_gits};
 		return [ $git, $oid_full, $type, int($size) ]; # done, success
 	}

[PATCH 10/11] www_coderepo: remove some needless return statements

[Eric Wong]

Maybe it makes control flow a little easier to rely on
implicit return (IIRC, it's slightly faster, too).
---
 lib/PublicInbox/WwwCoderepo.pm | 37 ++++++++++++----------------------
 1 file changed, 13 insertions(+), 24 deletions(-)

diff --git a/lib/PublicInbox/WwwCoderepo.pm b/lib/PublicInbox/WwwCoderepo.pm
index 024a9d8f..8dcd9772 100644
--- a/lib/PublicInbox/WwwCoderepo.pm
+++ b/lib/PublicInbox/WwwCoderepo.pm
@@ -220,38 +220,27 @@ sub srv { # endpoint called by PublicInbox::WWW
 	my $git;
 	# handle clone requests
 	my $cr = $self->{pi_cfg}->{-code_repos};
-	if ($path_info =~ m!\A/(.+?)/($PublicInbox::GitHTTPBackend::ANY)\z!x) {
-		$git = $cr->{$1} and return
+	if ($path_info =~ m!\A/(.+?)/($PublicInbox::GitHTTPBackend::ANY)\z!x and
+		($git = $cr->{$1})) {
 			PublicInbox::GitHTTPBackend::serve($ctx->{env},$git,$2);
-	}
-	$path_info =~ m!\A/(.+?)/\z! and
-		($ctx->{git} = $cr->{$1}) and return summary($self, $ctx);
-	if ($path_info =~ m!\A/(.+?)/([a-f0-9]+)/s/([^/]+)?\z! and
+	} elsif ($path_info =~ m!\A/(.+?)/\z! and ($ctx->{git} = $cr->{$1})) {
+		summary($self, $ctx)
+	} elsif ($path_info =~ m!\A/(.+?)/([a-f0-9]+)/s/([^/]+)?\z! and
 			($ctx->{git} = $cr->{$1})) {
 		$ctx->{lh} = $self->{log_fh};
-		return PublicInbox::ViewVCS::show($ctx, $2, $3);
-	}
-
-	if ($path_info =~ m!\A/(.+?)/tree/(.*)\z! and
+		PublicInbox::ViewVCS::show($ctx, $2, $3);
+	} elsif ($path_info =~ m!\A/(.+?)/tree/(.*)\z! and
 			($ctx->{git} = $cr->{$1})) {
 		$ctx->{lh} = $self->{log_fh};
-		return PublicInbox::RepoTree::srv_tree($ctx, $2) // r(404);
-	}
-
-	# snapshots:
-	if ($path_info =~ m!\A/(.+?)/snapshot/([^/]+)\z! and
+		PublicInbox::RepoTree::srv_tree($ctx, $2) // r(404);
+	} elsif ($path_info =~ m!\A/(.+?)/snapshot/([^/]+)\z! and
 			($ctx->{git} = $cr->{$1})) {
 		$ctx->{wcr} = $self;
-		return PublicInbox::RepoSnapshot::srv($ctx, $2) // r(404);
-	}
-
-	if ($path_info =~ m!\A/(.+?)/atom/(.*)\z! and
+		PublicInbox::RepoSnapshot::srv($ctx, $2) // r(404);
+	} elsif ($path_info =~ m!\A/(.+?)/atom/(.*)\z! and
 			($ctx->{git} = $cr->{$1})) {
-		return PublicInbox::RepoAtom::srv_atom($ctx, $2) // r(404);
-	}
-
-	# enforce trailing slash:
-	if ($path_info =~ m!\A/(.+?)\z! and ($git = $cr->{$1})) {
+		PublicInbox::RepoAtom::srv_atom($ctx, $2) // r(404);
+	} elsif ($path_info =~ m!\A/(.+?)\z! and ($git = $cr->{$1})) {
 		my $qs = $ctx->{env}->{QUERY_STRING};
 		my $url = $git->base_url($ctx->{env});
 		$url .= "?$qs" if $qs ne '';

[PATCH 11/11] viewvcs: improve tree glossary view

[Eric Wong]

Adding an <hr> helps delineate the glossary, note that
submodules are rare, and avoid needlessly defining the
commits-in-trees case since the extra information is likely
to overwhelm new users.
---
 lib/PublicInbox/ViewVCS.pm | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/lib/PublicInbox/ViewVCS.pm b/lib/PublicInbox/ViewVCS.pm
index 99f5e24f..5fd46610 100644
--- a/lib/PublicInbox/ViewVCS.pm
+++ b/lib/PublicInbox/ViewVCS.pm
@@ -409,7 +409,7 @@ EOM
 		$pfx = '';
 		$$bref .= qq[  (<a href=#path>path</a> unknown)\n];
 	}
-	my ($x, $m, $t, $oid, $sz, $f, $n);
+	my ($x, $m, $t, $oid, $sz, $f, $n, $gitlink);
 	$$bref .= "\n	size	name";
 	for (@ent) {
 		($x, $f) = split(/\t/, $_, 2);
@@ -420,6 +420,7 @@ EOM
 		$n = ascii_html($f);
 		if ($m eq 'g') { # gitlink submodule commit
 			$$bref .= "\ng\t\t$n @ <a\nhref=#g>commit</a>$oid";
+			$gitlink = 1;
 			next;
 		}
 		my $q = 'b='.ascii_html(uri_escape_path($pfx.$f));
@@ -430,17 +431,20 @@ EOM
 	}
 	$$bref .= dbg_log($ctx);
 	$$bref .= <<EOM;
-<pre>glossary
+<hr><pre>glossary
 --------
 <dfn
 id=tree>Tree</dfn> objects belong to commits or other tree objects.  Trees may
-reference blobs, sub-trees, or commits of submodules.
+reference blobs, sub-trees, or (rarely) commits of submodules.
 
 <dfn
 id=path>Path</dfn> names are stored in tree objects, but trees do not know
 their own path name.  A tree's path name comes from their parent tree,
 or it is the root tree referenced by a commit object.  Thus, this web UI
 relies on the `b=' URI parameter as a hint to display the path name.
+EOM
+
+	$$bref .= <<EOM if $gitlink;
 
 <dfn title="submodule commit"
 id=g>Commit</dfn> objects may be stored in trees to reference submodules.</pre>