threads / patch / 5866

patchgitweb: Show project README if available

Subject: [PATCH] gitweb: Show project README if available

## tl;dr

14 messages between Oct 10, 2006 and Oct 11, 2006. Diffs are folded; open one to read it.

replies: 13people: 6as markdown or json

Petr Baudis· Oct 10, 2006, 02:56 UTC · lore

If the project includes a README file, show it in the summary page. The usual "this should be in the config file" argument does not apply here since this can be larger and having such a big string in the config file would be impractical.

I don't know if this is suitable upstream, but it's one of the repo.or.cz custom modifications that I've thought could be interesting for others as well.

Signed-off-by: Petr Baudis <pasky@suse.cz>
---
 gitweb/gitweb.perl |    8 ++++++++
 1 files changed, 8 insertions(+), 0 deletions(-)
Show changes to gitweb/gitweb.perl +8 −0
diff --git a/gitweb/gitweb.perl b/gitweb/gitweb.perl
index 7547c4d..4e56af9 100755
--- a/gitweb/gitweb.perl
+++ b/gitweb/gitweb.perl
@@ -2535,6 +2535,14 @@ sub git_summary {
 	}
 	print "</table>\n";
 
+	if (-s "$projectroot/$project/README") {
+		if (open my $fd, "$projectroot/$project/README") {
+			print "<div class=\"title\">readme</div>\n";
+			print $_ while (<$fd>);
+			close $fd;
+		}
+	}
+
 	open my $fd, "-|", git_cmd(), "rev-list", "--max-count=17",
 		git_get_head_hash($project)
 		or die_error(undef, "Open git-rev-list failed");
Junio C Hamano· Oct 10, 2006, 03:20 UTC · re: Petr Baudis · lore

Re: [PATCH] gitweb: Show project README if available

Petr Baudis <pasky@suse.cz> writes:
Show 8 quoted lines
> If the project includes a README file, show it in the summary page.
> The usual "this should be in the config file" argument does not apply here
> since this can be larger and having such a big string in the config file
> would be impractical.
>
> I don't know if this is suitable upstream, but it's one of the repo.or.cz
> custom modifications that I've thought could be interesting for others
> as well.
I agree something like this would be very useful.

I wonder how this should relate to .git/description file, though. In other words, it _might_ make sense to change where we show the contents of description right now to show the first line and take README from the same location.

Having said that I'd take this as is in "next" and wait for public to decide having two separate files is Ok (which I suspect is the case) or we'd be better off in the longer term to try to minimize random files under $GIT_DIR.

Junio C Hamano· Oct 10, 2006, 04:33 UTC · re: Junio C Hamano · lore

Re: [PATCH] gitweb: Show project README if available

Junio C Hamano <junkio@cox.net> writes:
Show 8 quoted lines
> Petr Baudis <pasky@suse.cz> writes:
>
>> If the project includes a README file, show it in the summary page.
>...
> I wonder how this should relate to .git/description file,
> though.  In other words, it _might_ make sense to change where
> we show the contents of description right now to show the first
> line and take README from the same location.

Also we might want to consider using this file (or description) for git-daemon "motd" action if we were to enhance it. I remember that early days of git-daemon some people wanted to have motd.

Petr Baudis· Oct 10, 2006, 10:55 UTC · re: Junio C Hamano · lore

Re: [PATCH] gitweb: Show project README if available

Dear diary, on Tue, Oct 10, 2006 at 06:33:54AM CEST, I got a letter where Junio C Hamano <junkio@cox.net> said that...

Show 10 quoted lines
> Junio C Hamano <junkio@cox.net> writes:
> 
> > Petr Baudis <pasky@suse.cz> writes:
> >
> >> If the project includes a README file, show it in the summary page.
> >...
> > I wonder how this should relate to .git/description file,
> > though.  In other words, it _might_ make sense to change where
> > we show the contents of description right now to show the first
> > line and take README from the same location.

In principle I like this idea. One problem is that description is not supposed to contain HTML and my README is (perhaps it should read README.html instead), and I really want README to. And if it's not plaintext, division of the first line and the rest does not work so well:

If you show first line of description as the "short" one and whole description as the "full" one in summary page, it will look awkward. If you look at http://repo.or.cz/gitweb.cgi/hed.git, the first line in the full description starts with boldened Hed, and is of course a separate paragraph etc.

> Also we might want to consider using this file (or description)
> for git-daemon "motd" action if we were to enhance it.  I
> remember that early days of git-daemon some people wanted to
> have motd.
I'd rather keep those separate...
-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1
lK[d2%Sa2/d0$^Ixp"|dc`;s/\W//g;$_=pack('H*',/((..)*)$/)
Jakub Narebski· Oct 10, 2006, 11:21 UTC · re: Petr Baudis · lore

Re: [PATCH] gitweb: Show project README if available

Petr Baudis wrote:
Show 18 quoted lines
> Dear diary, on Tue, Oct 10, 2006 at 06:33:54AM CEST, I got a letter
> where Junio C Hamano <junkio@cox.net> said that...
>> Junio C Hamano <junkio@cox.net> writes:
>> 
>> > Petr Baudis <pasky@suse.cz> writes:
>> >
>> >> If the project includes a README file, show it in the summary page.
>> >...
>> > I wonder how this should relate to .git/description file,
>> > though.  In other words, it _might_ make sense to change where
>> > we show the contents of description right now to show the first
>> > line and take README from the same location.
> 
> In principle I like this idea. One problem is that description is not
> supposed to contain HTML and my README is (perhaps it should read
> README.html instead), and I really want README to. And if it's not
> plaintext, division of the first line and the rest does not work so
> well:

Perhaps we should assume $GIT_DIR/README to be text/plain (and useable as motd), and $GIT_DIR/README.html as text/html, preffering the README.html. The "problem" is if README.html is HTML _fragment_, or is it self contained HTML (and we should use iframe, object, or strip it).

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git
Luben Tuikov· Oct 10, 2006, 05:15 UTC · re: Petr Baudis · lore

Re: [PATCH] gitweb: Show project README if available

--- Petr Baudis <pasky@suse.cz> wrote:
Show 8 quoted lines
> If the project includes a README file, show it in the summary page.
> The usual "this should be in the config file" argument does not apply here
> since this can be larger and having such a big string in the config file
> would be impractical.
> 
> I don't know if this is suitable upstream, but it's one of the repo.or.cz
> custom modifications that I've thought could be interesting for others
> as well.
I don't see how a read-me file relates to gitweb.

People may call those files "00README" or "README.txt" or "README.TXT" or "README_001", etc.

The contents of such a file has nothing to do with gitweb, and or git. It may work for repo.or.cz but is unlikely that it would work for all projects for all git repos and for all gitweb interfaces.

The contents of a read-me file could be quite large and thus not suitable for the "summary" page. Both the contents and the size may not be suitable. "repo.or.cz" is the exception, not the rule.

A readme file isn't written with the intent of git or gitweb. It is a function of the project, not the SCM used to keep it in, or the SCM web interface used to show it.

I don't understand why the "description" file doesn't do what you want? Do you need it to be multi-line or slightly larger? Why not just extend "description" and/or create/use a second file called "description_long" to store multi-line descriptions?

Or why not extend the "description" file s.t. only the first line would be shown in the "description" line of "summary" and down below, show the rest of the description file if present?

This way it is known that this is a function of gitweb.
     Luben
Show 31 quoted lines
> 
> Signed-off-by: Petr Baudis <pasky@suse.cz>
> ---
> 
>  gitweb/gitweb.perl |    8 ++++++++
>  1 files changed, 8 insertions(+), 0 deletions(-)
> 
> diff --git a/gitweb/gitweb.perl b/gitweb/gitweb.perl
> index 7547c4d..4e56af9 100755
> --- a/gitweb/gitweb.perl
> +++ b/gitweb/gitweb.perl
> @@ -2535,6 +2535,14 @@ sub git_summary {
>  	}
>  	print "</table>\n";
>  
> +	if (-s "$projectroot/$project/README") {
> +		if (open my $fd, "$projectroot/$project/README") {
> +			print "<div class=\"title\">readme</div>\n";
> +			print $_ while (<$fd>);
> +			close $fd;
> +		}
> +	}
> +
>  	open my $fd, "-|", git_cmd(), "rev-list", "--max-count=17",
>  		git_get_head_hash($project)
>  		or die_error(undef, "Open git-rev-list failed");
> -
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>
Andreas Ericsson· Oct 10, 2006, 08:33 UTC · re: Luben Tuikov · lore

Re: [PATCH] gitweb: Show project README if available

Luben Tuikov wrote:
Show 20 quoted lines
> --- Petr Baudis <pasky@suse.cz> wrote:
>> If the project includes a README file, show it in the summary page.
>> The usual "this should be in the config file" argument does not apply here
>> since this can be larger and having such a big string in the config file
>> would be impractical.
>>
>> I don't know if this is suitable upstream, but it's one of the repo.or.cz
>> custom modifications that I've thought could be interesting for others
>> as well.
> 
> I don't see how a read-me file relates to gitweb.
> 
> People may call those files "00README" or "README.txt"
> or "README.TXT" or "README_001", etc.
> 
> The contents of such a file has nothing to do with gitweb,
> and or git.  It may work for repo.or.cz but is unlikely that
> it would work for all projects for all git repos and for all
> gitweb interfaces.
>

Well, git isn't the right tool for everything, and umbrellas are only good when it rains.

Show 9 quoted lines
> The contents of a read-me file could be quite large and thus
> not suitable for the "summary" page.  Both the contents and the
> size may not be suitable.  "repo.or.cz" is the exception, not
> the rule.
> 
> A readme file isn't written with the intent of git or gitweb.
> It is a function of the project, not the SCM used to keep it in, or
> the SCM web interface used to show it.
>

I can quite clearly envision usage for a README file for gitweb exclusive usage; It would show a link to coding guidelines, email-addresses for mailing-lists and project maintainers, bugtracker urls and other things which are handy to find fast on the web but that you don't necessarily want to dig around inside the repo for.

the project-root/README usually holds info along the lines of "This program is really spiffy. It does this, this and that, and if you configure it properly, it will Make the World a Better Place(tm)."; Too newbie'ish info for people looking to submit bugs, patches and suggestions.

Show 5 quoted lines
> I don't understand why the "description"  file doesn't do what
> you want?  Do you need it to be multi-line or slightly larger?
> Why not just extend "description" and/or create/use a second
> file called "description_long" to store multi-line descriptions?
>

I imagine description_long is what's discussed here, although README is the suggested name.

> Or why not extend the "description" file s.t. only the first
> line would be shown in the "description" line of "summary" and
> down below, show the rest of the description file if present?
>

Junio suggested this 2 hours before you sent your mail, and it seems as reasonable now as it did then. It also makes .git/description consistent with how we write and show commit-messages.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231
Jakub Narebski· Oct 10, 2006, 09:00 UTC · re: Petr Baudis · lore

Re: [PATCH] gitweb: Show project README if available

Petr Baudis wrote:
> +                       print $_ while (<$fd>);
Wouldn't it be better to do it in slurp mode, i.e.
        {
                local $/
                print <$fd>;
        }
instead?

Do you assume that README is HTML fragment? If not, you should esc_html it. Besides, we have similar (if assumed to have one line only) file, namely description.

Besides, README for a project can be huge. Git README has 589 lines!
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git
Petr Baudis· Oct 10, 2006, 10:41 UTC · re: Jakub Narebski · lore

Re: [PATCH] gitweb: Show project README if available

Dear diary, on Tue, Oct 10, 2006 at 11:00:41AM CEST, I got a letter where Jakub Narebski <jnareb@gmail.com> said that...

Show 12 quoted lines
> Petr Baudis wrote:
> 
> > +                       print $_ while (<$fd>);
> 
> Wouldn't it be better to do it in slurp mode, i.e.
> 
>         {
>                 local $/
>                 print <$fd>;
>         }
> 
> instead?

I personally prefer my version as it prevents allocation of big chunks of memory, but I don't really care in this particular case.

> Do you assume that README is HTML fragment? If not, you should esc_html it.
> Besides, we have similar (if assumed to have one line only) file, namely
> description.

I _do_ assume that README is HTML fragment (so that you can use links, non-proportional fonts, etc.), this is a difference to the description file.

> Besides, README for a project can be huge. Git README has 589 lines!

This is not /README from the tree but README in the .git directory, so it may not be the same. In the repo.or.cz admin interface, I limit README to 8kb.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1
lK[d2%Sa2/d0$^Ixp"|dc`;s/\W//g;$_=pack('H*',/((..)*)$/)
Jakub Narebski· Oct 11, 2006, 12:23 UTC · re: Petr Baudis · lore

Re: [PATCH] gitweb: Show project README if available

Petr "Pasky" Baudis wrote:
Show 17 quoted lines
> Dear diary, on Tue, Oct 10, 2006 at 11:00:41AM CEST, I got a letter
> where Jakub Narebski <jnareb@gmail.com> said that...
> > Petr Baudis wrote:
> > 
> > > +                       print $_ while (<$fd>);
> > 
> > Wouldn't it be better to do it in slurp mode, i.e.
> > 
> >         {
> >                 local $/
> >                 print <$fd>;
> >         }
> > 
> > instead?
> 
> I personally prefer my version as it prevents allocation of big chunks
> of memory, but I don't really care in this particular case.

Can any Perl expert tell us how Perl truly solve this? What is the best way to dump whole [remaining] contents of file (from filehandle) to STDOUT?

Show 7 quoted lines
> > Do you assume that README is HTML fragment? If not, you should esc_html it.
> > Besides, we have similar (if assumed to have one line only) file, namely
> > description.
> 
> I _do_ assume that README is HTML fragment (so that you can use links,
> non-proportional fonts, etc.), this is a difference to the description
> file.

Hmmm... perhaps better name would be description_long.html, or description.html Or at least README.html.

Description could be moved to the config file; your's project README couldn't.
Show 5 quoted lines
> > Besides, README for a project can be huge. Git README has 589 lines!
> 
> This is not /README from the tree but README in the .git directory, so
> it may not be the same. In the repo.or.cz admin interface, I limit
> README to 8kb.
Sorry. My mistake.
-- 
Jakub Narebski
Poland
Jeff King· Oct 11, 2006, 18:17 UTC · re: Jakub Narebski · lore

Re: [PATCH] gitweb: Show project README if available

On Wed, Oct 11, 2006 at 02:23:00PM +0200, Jakub Narebski wrote:
> Can any Perl expert tell us how Perl truly solve this? What is the best
> way to dump whole [remaining] contents of file (from filehandle) to STDOUT?

The same you would in C: read fix-sized buffers and dump them. Reading the whole file obviously has unbounded memory allocation. Reading lines requires unnecessary parsing and may have unbounded memory allocation (though in practice for text files I doubt either is a big deal).

You can loop like this:
while(1) {
  my $r = read(STDIN, my $buf, 4096);
  defined($r) or die "error: $!";
  $r or last;
  print STDOUT $buf;
}
Or you can use the File::Copy module, which is part of the standard
distribution (and I believe has been so for all perl5 versions, but I
could be wrong):
  use File::Copy qw(copy);
  copy(STDIN, STDOUT);
-Peff
Jakub Narebski· Oct 11, 2006, 18:46 UTC · re: Jeff King · lore

Re: [PATCH] gitweb: Show project README if available

Jeff King wrote:
Show 6 quoted lines
> On Wed, Oct 11, 2006 at 02:23:00PM +0200, Jakub Narebski wrote:
> 
>> Can any Perl expert tell us how Perl truly solve this? What is the best
>> way to dump whole [remaining] contents of file (from filehandle) to STDOUT?
> 
> The same you would in C: read fix-sized buffers and dump them.
[...]
> Or you can use the File::Copy module, which is part of the standard
> distribution (and I believe has been so for all perl5 versions, but I
> could be wrong):
And 
        {
                local $/;
                print <$fd>;
        }
doesn't do the right thing?
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git
Junio C Hamano· Oct 11, 2006, 19:32 UTC · re: Jakub Narebski · lore

Re: [PATCH] gitweb: Show project README if available

Jakub Narebski <jnareb@gmail.com> writes:
Show 21 quoted lines
> Jeff King wrote:
>
>> On Wed, Oct 11, 2006 at 02:23:00PM +0200, Jakub Narebski wrote:
>> 
>>> Can any Perl expert tell us how Perl truly solve this? What is the best
>>> way to dump whole [remaining] contents of file (from filehandle) to STDOUT?
>> 
>> The same you would in C: read fix-sized buffers and dump them.
> [...]
>> Or you can use the File::Copy module, which is part of the standard
>> distribution (and I believe has been so for all perl5 versions, but I
>> could be wrong):
>
> And 
>
>         {
>                 local $/;
>                 print <$fd>;
>         }
>
> doesn't do the right thing?

Jakub, you asked for "the best way" not "any way that would produce a correct result". Your 4-liner is shorter in the source but it risks slurping a 10 megabyte file into memory first, only to discard it after immediately writing it out.

You can strace your Perl to see what yours does yourself:
	strace perl -e 'print <STDIN>' >/dev/null <some-huge-file

You will see a bunch of read(0, ..., 4096) and after all of that finishes, finally you will see a bunch of write(1, ..., 4096). Where do you think the data is in the meantime?

Jeff gave you better ways that do not have that problem.
Jakub Narebski· Oct 11, 2006, 20:33 UTC · re: Junio C Hamano · lore

Re: [PATCH] gitweb: Show project README if available

Junio C Hamano wrote:
Show 23 quoted lines
> Jakub Narebski <jnareb@gmail.com> writes:
> 
>> Jeff King wrote:
>>
>>> On Wed, Oct 11, 2006 at 02:23:00PM +0200, Jakub Narebski wrote:
>>> 
>>>> Can any Perl expert tell us how Perl truly solve this? What is the best
>>>> way to dump whole [remaining] contents of file (from filehandle) to STDOUT?
>>> 
>>> The same you would in C: read fix-sized buffers and dump them.
>> [...]
>>> Or you can use the File::Copy module, which is part of the standard
>>> distribution (and I believe has been so for all perl5 versions, but I
>>> could be wrong):
>>
>> And 
>>
>>         {
>>                 local $/;
>>                 print <$fd>;
>>         }
>>
>> doesn't do the right thing?
[...]
Show 7 quoted lines
> You can strace your Perl to see what yours does yourself:
> 
>       strace perl -e 'print <STDIN>' >/dev/null <some-huge-file
> 
> You will see a bunch of read(0, ..., 4096) and after all of that
> finishes, finally you will see a bunch of write(1, ..., 4096).
> Where do you think the data is in the meantime?
Pity that Perl does this that a way.

Should we use File::Copy thorough the gitweb, instead of using slurp mode? Well, perhaps except small files, like $GIT_DIR/description...

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

← back to recent threads