[PATCH] gitweb: Show project README if available

[PATCH] gitweb: Show project README if available

[Petr Baudis]

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

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");

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

[Junio C Hamano]

Petr Baudis <pasky@suse.cz> writes:

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

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

[Junio C Hamano]

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.

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.

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

[Luben Tuikov]

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

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

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

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

[Andreas Ericsson]

Luben Tuikov wrote:
> --- 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.

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


> 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

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

[Jakub Narebski]

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

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

[Petr Baudis]

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.

> 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*',/((..)*)$/)

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

[Petr Baudis]

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:

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*',/((..)*)$/)

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

[Jakub Narebski]

Petr Baudis wrote:

> 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

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

[Horst H. von Brand]

Junio C Hamano <junkio@cox.net> wrote:

[...]

> 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 consider motd to be a system-wide property, not of a particular
project/repository...
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                    Fono: +56 32 2654431
Universidad Tecnica Federico Santa Maria             +56 32 2654239
Casilla 110-V, Valparaiso, Chile               Fax:  +56 32 2797513

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

[Jakub Narebski]

Petr "Pasky" Baudis wrote:
> 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?

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

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

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

[Jeff King]

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

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

[Jakub Narebski]

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 Narebski
Warsaw, Poland
ShadeHawk on #git

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

[Junio C Hamano]

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?

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.

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

[Jakub Narebski]

Junio C Hamano wrote:

> 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?
[...]
> 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