Subject: [RFC/PATCH] gitweb: Allow project description in project_index file

From: Jakub Narebski <[email-masked]>
Date: Fri, 2 May 2008 12:30:04 +0200

Change format of $projects_list file from
  <URI-encoded path> SPC <URI-encoded owner> LF
to
  <URI-encoded path> SPC <URI-encoded owner> [SPC <description>] LF
with optional project description.  To make it easier to read and edit
$projects_list file the description _is not_ URI encoded.  Please
remember that only single line of repository (project) description is
supported.  Note that SPC can be replaced by any whitespace
character.

This change required modifying git_get_projects_list() subroutine
(part when $projects_list is a file, not a directory to be scanned),
and git_get_project_description() subroutine.

The 'project_index' action creates projects list index file in the new
format, with project description.

Thi change is backwards compatibile: older gitweb with new projects
list format would work as it used to work; new gitweb with old format
would get (try to get) project description from other sources.

While at it some comments describing changes and changed subroutines
were added, and information about $projects_list format was updated in
gitweb/README.

Signed-off-by: Jakub Narebski <[email-masked]>
---
This is second patch in the yet to be written series improving projects
list page and related things.  I'm sending an early version of patch to
ask for comments.

The reason why it is an RFC is the decision to _not_ URI-decode (to not
force URI-encoding of e.g. spaces) in the project (repository)
description part of projects list page.  It makes projects index file
easier to read and to edit, but it closes possibility of extending this
format further.  And there is another thing that could be reasonably put
in this file: future project *categories* support.  So should I try to
add categories support first?

Note that without this patch future patches, dividing projects list page
into 100-items long pages, and adding projects search page, which are
meant to bring preformance improvements, would get less performance
improvements without this patch.

Comments appreciated...

 gitweb/README      |    9 +++++--
 gitweb/gitweb.perl |   61 +++++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 59 insertions(+), 11 deletions(-)

diff --git a/gitweb/README b/gitweb/README
index 8f7ea36..e58fe18 100644
--- a/gitweb/README
+++ b/gitweb/README
@@ -157,9 +157,12 @@ not include variables usually directly set during build):
  * $projects_list
    Source of projects list, either directory to scan, or text file
    with list of repositories (in the "<URI-encoded repository path> SPC
-   <URI-encoded repository owner>" format).  Set to $GITWEB_LIST
-   during installation.  If empty, $projectroot is used to scan for
-   repositories.
+   <URI-encoded repository owner>" line format, or optionally with
+   project description in "<URI-encoded repository path> SPC
+   <URI-encoded repository owner> SPC <single line description>";
+   actually there can be any whitespace in place of SPC).  Set to
+   $GITWEB_LIST during installation.  If empty, $projectroot is used
+   to scan for repositories.
  * $my_url, $my_uri
    URL and absolute URL of gitweb script; you might need to set those
    variables if you are using 'pathinfo' feature: see also below.
diff --git a/gitweb/gitweb.perl b/gitweb/gitweb.perl
index 6a28dca..dc3f99a 100755
--- a/gitweb/gitweb.perl
+++ b/gitweb/gitweb.perl
@@ -1702,13 +1702,43 @@ sub git_get_path_by_hash {
 ## ......................................................................
 ## git utility functions, directly accessing git repository
 
+# this is helper function for git_get_project_description()
+sub git_get_project_description_from_list {
+	my $path = shift;
+
+	open(my $fd, $projects_list)
+		or return;
+	while (my $line = <$fd>) {
+		chomp $line;
+		my ($pr, undef, $descr) = split(' ', $line, 3);
+		$pr = unescape($pr);
+		if ($pr eq $path) {
+			close $fd;
+			return $descr;
+		}
+	}
+	close $fd;
+	return;
+}
+
+# sources for project description are
+#  * project_list, if $project_list is a file, and it uses new format:
+#    URI_encoded(<path>) SPC URI_encoded(<owner>) SPC <description> LF
+#  * $GIT_DIR/description file in project repository, if it exists
+#  * gitweb.description configuration variable for a project
 sub git_get_project_description {
 	my $path = shift;
+	my $descr;
+
+	if (-f $projects_list) {
+		$descr = git_get_project_description_from_list($path);
+		return $descr if (defined $descr); # try other sources if needed
+	}
 
 	$git_dir = "$projectroot/$path";
 	open my $fd, "$git_dir/description"
 		or return git_get_project_config('description');
-	my $descr = <$fd>;
+	$descr = <$fd>;
 	close $fd;
 	if (defined $descr) {
 		chomp $descr;
@@ -1774,20 +1804,24 @@ sub git_get_projects_list {
 		}, "$dir");
 
 	} elsif (-f $projects_list) {
-		# read from file(url-encoded):
+		# read from file (whitespace separated, url-encoded):
 		# 'git%2Fgit.git Linus+Torvalds'
 		# 'libs%2Fklibc%2Fklibc.git H.+Peter+Anvin'
 		# 'linux%2Fhotplug%2Fudev.git Greg+Kroah-Hartman'
+		# optionally with description (which isn't url-encoded)
+		# 'git/git.git Junio+C+Hamano The core git plumbing'
+		# 'libs/klibc/klibc.git H.+Peter+Anvin klibc main development tree'
+		# 'linux/hotplug/udev.git Kay+Sievers udev development tree'
 		my %paths;
 		open my ($fd), $projects_list or return;
 	PROJECT:
 		while (my $line = <$fd>) {
 			chomp $line;
-			my ($path, $owner) = split ' ', $line;
+			my ($path, $owner, $descr) = split(' ', $line, 3);
 			$path = unescape($path);
 			$owner = unescape($owner);
 			if (!defined $path) {
-				next;
+				next PROJECT;
 			}
 			if ($filter ne '') {
 				# looking for forks;
@@ -1818,9 +1852,14 @@ sub git_get_projects_list {
 			}
 			if (check_export_ok("$projectroot/$path")) {
 				my $pr = {
-					path => $path,
+					path =>  to_utf8($path),
 					owner => to_utf8($owner),
 				};
+				if (defined $descr) {
+					$descr = to_utf8($descr);
+					$pr->{'descr_long'} = $descr;
+					$pr->{'descr'} = chop_str($descr, $projects_list_description_width, 5);
+				}
 				push @list, $pr;
 				(my $forks_path = $path) =~ s/\.git$//;
 				$paths{$forks_path}++;
@@ -4006,21 +4045,27 @@ sub git_project_index {
 	print $cgi->header(
 		-type => 'text/plain',
 		-charset => 'utf-8',
-		-content_disposition => 'inline; filename="index.aux"');
+		-content_disposition => 'inline; filename="projects_index.aux"');
 
 	foreach my $pr (@projects) {
 		if (!exists $pr->{'owner'}) {
 			$pr->{'owner'} = git_get_project_owner("$pr->{'path'}");
+			$pr->{'owner'} = to_utf8($pr->{'owner'});
+		}
+		if (!exists $pr->{'descr_long'}) {
+			$pr->{'descr_long'} = git_get_project_description($pr->{'path'}) || "";
+			$pr->{'descr_long'} = to_utf8($pr->{'descr_long'});
 		}
 
-		my ($path, $owner) = ($pr->{'path'}, $pr->{'owner'});
+		my ($path, $owner, $descr) = 
+			($pr->{'path'}, $pr->{'owner'}, $pr->{'descr_long'});
 		# quote as in CGI::Util::encode, but keep the slash, and use '+' for ' '
 		$path  =~ s/([^a-zA-Z0-9_.\-\/ ])/sprintf("%%%02X", ord($1))/eg;
 		$owner =~ s/([^a-zA-Z0-9_.\-\/ ])/sprintf("%%%02X", ord($1))/eg;
 		$path  =~ s/ /\+/g;
 		$owner =~ s/ /\+/g;
 
-		print "$path $owner\n";
+		print "$path $owner $descr\n";
 	}
 }
 
-- 
1.5.5