{"thread":{"id":"5866","subject":"[PATCH] gitweb: Show project README if available","startedAt":"2006-10-10T02:56:28Z","lastAt":"2006-10-11T20:33:46Z","messageCount":14,"participants":["Petr Baudis","Junio C Hamano","Luben Tuikov","Andreas Ericsson","Jakub Narebski","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"28482","messageId":"20061010025627.19317.70511.stgit@rover","threadId":"5866","inReplyTo":null,"subject":"[PATCH] gitweb: Show project README if available","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2006-10-10T02:56:28Z","receivedAt":"2006-10-10T02:56:28Z","isPatch":true,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"If the project includes a README file, show it in the summary page.\nThe usual \"this should be in the config file\" argument does not apply here\nsince this can be larger and having such a big string in the config file\nwould be impractical.\n\nI don't know if this is suitable upstream, but it's one of the repo.or.cz\ncustom modifications that I've thought could be interesting for others\nas well.\n\nSigned-off-by: Petr Baudis \n---\n\n gitweb/gitweb.perl | 8 ++++++++\n 1 files changed, 8 insertions(+), 0 deletions(-)\n\ndiff --git a/gitweb/gitweb.perl b/gitweb/gitweb.perl\nindex 7547c4d..4e56af9 100755\n--- a/gitweb/gitweb.perl\n+++ b/gitweb/gitweb.perl\n@@ -2535,6 +2535,14 @@ sub git_summary {\n \t}\n \tprint \"\\n\";\n \n+\tif (-s \"$projectroot/$project/README\") {\n+\t\tif (open my $fd, \"$projectroot/$project/README\") {\n+\t\t\tprint \"
readme
\\n\";\n+\t\t\tprint $_ while (<$fd>);\n+\t\t\tclose $fd;\n+\t\t}\n+\t}\n+\n \topen my $fd, \"-|\", git_cmd(), \"rev-list\", \"--max-count=17\",\n \t\tgit_get_head_hash($project)\n \t\tor die_error(undef, \"Open git-rev-list failed\");\n"},{"id":"28483","messageId":"7vejtg97qh.fsf@assigned-by-dhcp.cox.net","threadId":"5866","inReplyTo":"20061010025627.19317.70511.stgit@rover","subject":"Re: [PATCH] gitweb: Show project README if available","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-10-10T03:20:54Z","receivedAt":"2006-10-10T03:20:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Petr Baudis writes:\n\n> If the project includes a README file, show it in the summary page.\n> The usual \"this should be in the config file\" argument does not apply here\n> since this can be larger and having such a big string in the config file\n> would be impractical.\n>\n> I don't know if this is suitable upstream, but it's one of the repo.or.cz\n> custom modifications that I've thought could be interesting for others\n> as well.\n\nI agree something like this would be very useful.\n\nI wonder how this should relate to .git/description file,\nthough. In other words, it _might_ make sense to change where\nwe show the contents of description right now to show the first\nline and take README from the same location.\n\nHaving said that I'd take this as is in \"next\" and wait for\npublic to decide having two separate files is Ok (which I\nsuspect is the case) or we'd be better off in the longer term to\ntry to minimize random files under $GIT_DIR.\n"},{"id":"28484","messageId":"7v7iz894ct.fsf@assigned-by-dhcp.cox.net","threadId":"5866","inReplyTo":"7vejtg97qh.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] gitweb: Show project README if available","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-10-10T04:33:54Z","receivedAt":"2006-10-10T04:33:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Petr Baudis writes:\n>\n>> If the project includes a README file, show it in the summary page.\n>...\n> I wonder how this should relate to .git/description file,\n> though. In other words, it _might_ make sense to change where\n> we show the contents of description right now to show the first\n> line and take README from the same location.\n\nAlso we might want to consider using this file (or description)\nfor git-daemon \"motd\" action if we were to enhance it. I\nremember that early days of git-daemon some people wanted to\nhave motd.\n"},{"id":"28486","messageId":"20061010051545.15859.qmail@web31801.mail.mud.yahoo.com","threadId":"5866","inReplyTo":"20061010025627.19317.70511.stgit@rover","subject":"Re: [PATCH] gitweb: Show project README if available","fromName":"Luben Tuikov","fromEmail":"ltuikov@yahoo.com","sentAt":"2006-10-10T05:15:45Z","receivedAt":"2006-10-10T05:15:45Z","isPatch":true,"sender":{"key":"ltuikov@yahoo.com","avatar":null},"body":"--- Petr Baudis wrote:\n> If the project includes a README file, show it in the summary page.\n> The usual \"this should be in the config file\" argument does not apply here\n> since this can be larger and having such a big string in the config file\n> would be impractical.\n> \n> I don't know if this is suitable upstream, but it's one of the repo.or.cz\n> custom modifications that I've thought could be interesting for others\n> as well.\n\nI don't see how a read-me file relates to gitweb.\n\nPeople may call those files \"00README\" or \"README.txt\"\nor \"README.TXT\" or \"README_001\", etc.\n\nThe contents of such a file has nothing to do with gitweb,\nand or git. It may work for repo.or.cz but is unlikely that\nit would work for all projects for all git repos and for all\ngitweb interfaces.\n\nThe contents of a read-me file could be quite large and thus\nnot suitable for the \"summary\" page. Both the contents and the\nsize may not be suitable. \"repo.or.cz\" is the exception, not\nthe rule.\n\nA readme file isn't written with the intent of git or gitweb.\nIt is a function of the project, not the SCM used to keep it in, or\nthe SCM web interface used to show it.\n\nI don't understand why the \"description\" file doesn't do what\nyou want? Do you need it to be multi-line or slightly larger?\nWhy not just extend \"description\" and/or create/use a second\nfile called \"description_long\" to store multi-line descriptions?\n\nOr why not extend the \"description\" file s.t. only the first\nline would be shown in the \"description\" line of \"summary\" and\ndown below, show the rest of the description file if present?\n\nThis way it is known that this is a function of gitweb.\n\n Luben\n\n> \n> Signed-off-by: Petr Baudis \n> ---\n> \n> gitweb/gitweb.perl | 8 ++++++++\n> 1 files changed, 8 insertions(+), 0 deletions(-)\n> \n> diff --git a/gitweb/gitweb.perl b/gitweb/gitweb.perl\n> index 7547c4d..4e56af9 100755\n> --- a/gitweb/gitweb.perl\n> +++ b/gitweb/gitweb.perl\n> @@ -2535,6 +2535,14 @@ sub git_summary {\n> \t}\n> \tprint \"\\n\";\n> \n> +\tif (-s \"$projectroot/$project/README\") {\n> +\t\tif (open my $fd, \"$projectroot/$project/README\") {\n> +\t\t\tprint \"
readme
\\n\";\n> +\t\t\tprint $_ while (<$fd>);\n> +\t\t\tclose $fd;\n> +\t\t}\n> +\t}\n> +\n> \topen my $fd, \"-|\", git_cmd(), \"rev-list\", \"--max-count=17\",\n> \t\tgit_get_head_hash($project)\n> \t\tor die_error(undef, \"Open git-rev-list failed\");\n> -\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n> \n"},{"id":"28502","messageId":"452B5AD6.7040301@op5.se","threadId":"5866","inReplyTo":"20061010051545.15859.qmail@web31801.mail.mud.yahoo.com","subject":"Re: [PATCH] gitweb: Show project README if available","fromName":"Andreas Ericsson","fromEmail":"ae@op5.se","sentAt":"2006-10-10T08:33:26Z","receivedAt":"2006-10-10T08:33:26Z","isPatch":true,"sender":{"key":"ae@op5.se","avatar":"https://gravatar.com/avatar/426e89595c75a8f5252dd0c989e5fabe5bcac616e68557427ad9aef6b0ca342a?d=mp&s=160"},"body":"Luben Tuikov wrote:\n> --- Petr Baudis wrote:\n>> If the project includes a README file, show it in the summary page.\n>> The usual \"this should be in the config file\" argument does not apply here\n>> since this can be larger and having such a big string in the config file\n>> would be impractical.\n>>\n>> I don't know if this is suitable upstream, but it's one of the repo.or.cz\n>> custom modifications that I've thought could be interesting for others\n>> as well.\n> \n> I don't see how a read-me file relates to gitweb.\n> \n> People may call those files \"00README\" or \"README.txt\"\n> or \"README.TXT\" or \"README_001\", etc.\n> \n> The contents of such a file has nothing to do with gitweb,\n> and or git. It may work for repo.or.cz but is unlikely that\n> it would work for all projects for all git repos and for all\n> gitweb interfaces.\n> \n\nWell, git isn't the right tool for everything, and umbrellas are only \ngood when it rains.\n\n> The contents of a read-me file could be quite large and thus\n> not suitable for the \"summary\" page. Both the contents and the\n> size may not be suitable. \"repo.or.cz\" is the exception, not\n> the rule.\n> \n> A readme file isn't written with the intent of git or gitweb.\n> It is a function of the project, not the SCM used to keep it in, or\n> the SCM web interface used to show it.\n> \n\nI can quite clearly envision usage for a README file for gitweb \nexclusive usage; It would show a link to coding guidelines, \nemail-addresses for mailing-lists and project maintainers, bugtracker \nurls and other things which are handy to find fast on the web but that \nyou don't necessarily want to dig around inside the repo for.\n\nthe project-root/README usually holds info along the lines of\n\"This program is really spiffy. It does this, this and that, and if you \nconfigure it properly, it will Make the World a Better Place(tm).\"; Too \nnewbie'ish info for people looking to submit bugs, patches and suggestions.\n\n\n> I don't understand why the \"description\" file doesn't do what\n> you want? Do you need it to be multi-line or slightly larger?\n> Why not just extend \"description\" and/or create/use a second\n> file called \"description_long\" to store multi-line descriptions?\n> \n\nI imagine description_long is what's discussed here, although README is \nthe suggested name.\n\n> Or why not extend the \"description\" file s.t. only the first\n> line would be shown in the \"description\" line of \"summary\" and\n> down below, show the rest of the description file if present?\n> \n\nJunio suggested this 2 hours before you sent your mail, and it seems as \nreasonable now as it did then. It also makes .git/description consistent \nwith how we write and show commit-messages.\n\n-- \nAndreas Ericsson andreas.ericsson@op5.se\nOP5 AB www.op5.se\nTel: +46 8-230225 Fax: +46 8-230231\n"},{"id":"28504","messageId":"egfndo$lg6$1@sea.gmane.org","threadId":"5866","inReplyTo":"20061010025627.19317.70511.stgit@rover","subject":"Re: [PATCH] gitweb: Show project README if available","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2006-10-10T09:00:41Z","receivedAt":"2006-10-10T09:00:41Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Petr Baudis wrote:\n\n> +                       print $_ while (<$fd>);\n\nWouldn't it be better to do it in slurp mode, i.e.\n\n {\n local $/\n print <$fd>;\n }\n\ninstead?\n\nDo you assume that README is HTML fragment? If not, you should esc_html it.\nBesides, we have similar (if assumed to have one line only) file, namely\ndescription.\n\nBesides, README for a project can be huge. Git README has 589 lines!\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n"},{"id":"28508","messageId":"20061010104149.GP20017@pasky.or.cz","threadId":"5866","inReplyTo":"egfndo$lg6$1@sea.gmane.org","subject":"Re: [PATCH] gitweb: Show project README if available","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2006-10-10T10:41:49Z","receivedAt":"2006-10-10T10:41:49Z","isPatch":true,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"Dear diary, on Tue, Oct 10, 2006 at 11:00:41AM CEST, I got a letter\nwhere Jakub Narebski said that...\n> Petr Baudis wrote:\n> \n> > +                       print $_ while (<$fd>);\n> \n> Wouldn't it be better to do it in slurp mode, i.e.\n> \n> {\n> local $/\n> print <$fd>;\n> }\n> \n> instead?\n\nI personally prefer my version as it prevents allocation of big chunks\nof memory, but I don't really care in this particular case.\n\n> Do you assume that README is HTML fragment? If not, you should esc_html it.\n> Besides, we have similar (if assumed to have one line only) file, namely\n> description.\n\nI _do_ assume that README is HTML fragment (so that you can use links,\nnon-proportional fonts, etc.), this is a difference to the description\nfile.\n\n> Besides, README for a project can be huge. Git README has 589 lines!\n\nThis is not /README from the tree but README in the .git directory, so\nit may not be the same. In the repo.or.cz admin interface, I limit\nREADME to 8kb.\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nStuff: http://pasky.or.cz/\n#!/bin/perl -sp0777i said that...\n> Junio C Hamano writes:\n> \n> > Petr Baudis writes:\n> >\n> >> If the project includes a README file, show it in the summary page.\n> >...\n> > I wonder how this should relate to .git/description file,\n> > though. In other words, it _might_ make sense to change where\n> > we show the contents of description right now to show the first\n> > line and take README from the same location.\n\nIn principle I like this idea. One problem is that description is not\nsupposed to contain HTML and my README is (perhaps it should read\nREADME.html instead), and I really want README to. And if it's not\nplaintext, division of the first line and the rest does not work so\nwell:\n\nIf you show first line of description as the \"short\" one and whole\ndescription as the \"full\" one in summary page, it will look awkward. If\nyou look at http://repo.or.cz/gitweb.cgi/hed.git, the first line in the\nfull description starts with boldened Hed, and is of course a separate\nparagraph etc.\n\n> Also we might want to consider using this file (or description)\n> for git-daemon \"motd\" action if we were to enhance it. I\n> remember that early days of git-daemon some people wanted to\n> have motd.\n\nI'd rather keep those separate...\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nStuff: http://pasky.or.cz/\n#!/bin/perl -sp0777i Dear diary, on Tue, Oct 10, 2006 at 06:33:54AM CEST, I got a letter\n> where Junio C Hamano said that...\n>> Junio C Hamano writes:\n>> \n>> > Petr Baudis writes:\n>> >\n>> >> If the project includes a README file, show it in the summary page.\n>> >...\n>> > I wonder how this should relate to .git/description file,\n>> > though. In other words, it _might_ make sense to change where\n>> > we show the contents of description right now to show the first\n>> > line and take README from the same location.\n> \n> In principle I like this idea. One problem is that description is not\n> supposed to contain HTML and my README is (perhaps it should read\n> README.html instead), and I really want README to. And if it's not\n> plaintext, division of the first line and the rest does not work so\n> well:\n\nPerhaps we should assume $GIT_DIR/README to be text/plain (and useable\nas motd), and $GIT_DIR/README.html as text/html, preffering the README.html.\nThe \"problem\" is if README.html is HTML _fragment_, or is it self contained\nHTML (and we should use iframe, object, or strip it).\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n"},{"id":"28596","messageId":"200610111423.00656.jnareb@gmail.com","threadId":"5866","inReplyTo":"20061010104149.GP20017@pasky.or.cz","subject":"Re: [PATCH] gitweb: Show project README if available","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2006-10-11T12:23:00Z","receivedAt":"2006-10-11T12:23:00Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Petr \"Pasky\" Baudis wrote:\n> Dear diary, on Tue, Oct 10, 2006 at 11:00:41AM CEST, I got a letter\n> where Jakub Narebski said that...\n> > Petr Baudis wrote:\n> > \n> > > +                       print $_ while (<$fd>);\n> > \n> > Wouldn't it be better to do it in slurp mode, i.e.\n> > \n> > {\n> > local $/\n> > print <$fd>;\n> > }\n> > \n> > instead?\n> \n> I personally prefer my version as it prevents allocation of big chunks\n> of memory, but I don't really care in this particular case.\n\nCan any Perl expert tell us how Perl truly solve this? What is the best\nway to dump whole [remaining] contents of file (from filehandle) to STDOUT?\n\n> > Do you assume that README is HTML fragment? If not, you should esc_html it.\n> > Besides, we have similar (if assumed to have one line only) file, namely\n> > description.\n> \n> I _do_ assume that README is HTML fragment (so that you can use links,\n> non-proportional fonts, etc.), this is a difference to the description\n> file.\n\nHmmm... perhaps better name would be description_long.html, or description.html\nOr at least README.html.\n\nDescription could be moved to the config file; your's project README couldn't.\n\n> > Besides, README for a project can be huge. Git README has 589 lines!\n> \n> This is not /README from the tree but README in the .git directory, so\n> it may not be the same. In the repo.or.cz admin interface, I limit\n> README to 8kb.\n\nSorry. My mistake.\n-- \nJakub Narebski\nPoland\n"},{"id":"28620","messageId":"20061011181729.GB2897@coredump.intra.peff.net","threadId":"5866","inReplyTo":"200610111423.00656.jnareb@gmail.com","subject":"Re: [PATCH] gitweb: Show project README if available","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2006-10-11T18:17:29Z","receivedAt":"2006-10-11T18:17:29Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Oct 11, 2006 at 02:23:00PM +0200, Jakub Narebski wrote:\n\n> Can any Perl expert tell us how Perl truly solve this? What is the best\n> way to dump whole [remaining] contents of file (from filehandle) to STDOUT?\n\nThe same you would in C: read fix-sized buffers and dump them. Reading\nthe whole file obviously has unbounded memory allocation. Reading lines\nrequires unnecessary parsing and may have unbounded memory allocation\n(though in practice for text files I doubt either is a big deal).\n\nYou can loop like this:\nwhile(1) {\n my $r = read(STDIN, my $buf, 4096);\n defined($r) or die \"error: $!\";\n $r or last;\n print STDOUT $buf;\n}\n\nOr you can use the File::Copy module, which is part of the standard\ndistribution (and I believe has been so for all perl5 versions, but I\ncould be wrong):\n use File::Copy qw(copy);\n copy(STDIN, STDOUT);\n\n-Peff\n"},{"id":"28621","messageId":"egje5k$5rn$1@sea.gmane.org","threadId":"5866","inReplyTo":"20061011181729.GB2897@coredump.intra.peff.net","subject":"Re: [PATCH] gitweb: Show project README if available","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2006-10-11T18:46:14Z","receivedAt":"2006-10-11T18:46:14Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jeff King wrote:\n\n> On Wed, Oct 11, 2006 at 02:23:00PM +0200, Jakub Narebski wrote:\n> \n>> Can any Perl expert tell us how Perl truly solve this? What is the best\n>> way to dump whole [remaining] contents of file (from filehandle) to STDOUT?\n> \n> The same you would in C: read fix-sized buffers and dump them.\n[...]\n> Or you can use the File::Copy module, which is part of the standard\n> distribution (and I believe has been so for all perl5 versions, but I\n> could be wrong):\n\nAnd \n\n {\n local $/;\n print <$fd>;\n }\n\ndoesn't do the right thing?\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n"},{"id":"28624","messageId":"7v3b9utzqi.fsf@assigned-by-dhcp.cox.net","threadId":"5866","inReplyTo":"egje5k$5rn$1@sea.gmane.org","subject":"Re: [PATCH] gitweb: Show project README if available","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-10-11T19:32:37Z","receivedAt":"2006-10-11T19:32:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jakub Narebski writes:\n\n> Jeff King wrote:\n>\n>> On Wed, Oct 11, 2006 at 02:23:00PM +0200, Jakub Narebski wrote:\n>> \n>>> Can any Perl expert tell us how Perl truly solve this? What is the best\n>>> way to dump whole [remaining] contents of file (from filehandle) to STDOUT?\n>> \n>> The same you would in C: read fix-sized buffers and dump them.\n> [...]\n>> Or you can use the File::Copy module, which is part of the standard\n>> distribution (and I believe has been so for all perl5 versions, but I\n>> could be wrong):\n>\n> And \n>\n> {\n> local $/;\n> print <$fd>;\n> }\n>\n> doesn't do the right thing?\n\nJakub, you asked for \"the best way\" not \"any way that would\nproduce a correct result\". Your 4-liner is shorter in the\nsource but it risks slurping a 10 megabyte file into memory\nfirst, only to discard it after immediately writing it out.\n\nYou can strace your Perl to see what yours does yourself:\n\n\tstrace perl -e 'print ' >/dev/null Jakub Narebski writes:\n> \n>> Jeff King wrote:\n>>\n>>> On Wed, Oct 11, 2006 at 02:23:00PM +0200, Jakub Narebski wrote:\n>>> \n>>>> Can any Perl expert tell us how Perl truly solve this? What is the best\n>>>> way to dump whole [remaining] contents of file (from filehandle) to STDOUT?\n>>> \n>>> The same you would in C: read fix-sized buffers and dump them.\n>> [...]\n>>> Or you can use the File::Copy module, which is part of the standard\n>>> distribution (and I believe has been so for all perl5 versions, but I\n>>> could be wrong):\n>>\n>> And \n>>\n>> {\n>> local $/;\n>> print <$fd>;\n>> }\n>>\n>> doesn't do the right thing?\n[...]\n> You can strace your Perl to see what yours does yourself:\n> \n> strace perl -e 'print ' >/dev/null \n> You will see a bunch of read(0, ..., 4096) and after all of that\n> finishes, finally you will see a bunch of write(1, ..., 4096).\n> Where do you think the data is in the meantime?\n\nPity that Perl does this that a way.\n\nShould we use File::Copy thorough the gitweb, instead of using slurp mode?\nWell, perhaps except small files, like $GIT_DIR/description...\n\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n"}]}