{"thread":{"id":"14332","subject":"[PATCH] gitweb: Describe projects_index format in more detail","startedAt":"2008-07-07T22:07:53Z","lastAt":"2008-07-07T22:07:53Z","messageCount":1,"participants":["Jakub Narebski"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"82498","messageId":"20080707220530.8439.33340.stgit@localhost.localdomain","threadId":"14332","inReplyTo":null,"subject":"[PATCH] gitweb: Describe projects_index format in more detail","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2008-07-07T22:07:53Z","receivedAt":"2008-07-07T22:07:53Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Update and extend information about $projects_list file format in\ngitweb/README and in gitweb/INSTALL.\n\nSigned-off-by: Jakub Narebski <jnareb@gmail.com>\n---\nThis was part of\n  \"gitweb: Extend project_index file format by project description\"\npatch send to git mailing list (but not applied).  I thought that\nupdating documentation can be done independently, so here it is (minus\nof course information about optional repository description field).\n\n gitweb/INSTALL |    6 ++++++\n gitweb/README  |   46 ++++++++++++++++++++++++++++++++++++++++------\n 2 files changed, 46 insertions(+), 6 deletions(-)\n\ndiff --git a/gitweb/INSTALL b/gitweb/INSTALL\nindex f7194db..26967e2 100644\n--- a/gitweb/INSTALL\n+++ b/gitweb/INSTALL\n@@ -144,6 +144,12 @@ Gitweb repositories\n   Spaces in both project path and project owner have to be encoded as either\n   '%20' or '+'.\n \n+  Other characters that have to be url-encoded, i.e. replaced by '%'\n+  followed by two-digit character number in octal, are: other whitespace\n+  characters (because they are field separator in a record), plus sign '+'\n+  (because it can be used as replacement for spaces), and percent sign '%'\n+  (which is used for encoding / escaping).\n+\n   You can generate the projects list index file using the project_index\n   action (the 'TXT' link on projects list page) directly from gitweb.\n \ndiff --git a/gitweb/README b/gitweb/README\nindex 356ab7b..6908036 100644\n--- a/gitweb/README\n+++ b/gitweb/README\n@@ -156,10 +156,11 @@ not include variables usually directly set during build):\n    set correctly for gitweb to find repositories.\n  * $projects_list\n    Source of projects list, either directory to scan, or text file\n-   with list of repositories (in the \"<URI-encoded repository path> SPC\n-   <URI-encoded repository owner>\" format).  Set to $GITWEB_LIST\n-   during installation.  If empty, $projectroot is used to scan for\n-   repositories.\n+   with list of repositories (in the \"<URI-encoded repository path> SP\n+   <URI-encoded repository owner>\" line format; actually there can be\n+   any sequence of whitespace in place of space (SP)).  Set to\n+   $GITWEB_LIST during installation.  If empty, $projectroot is used\n+   to scan for repositories.\n  * $my_url, $my_uri\n    URL and absolute URL of gitweb script; you might need to set those\n    variables if you are using 'pathinfo' feature: see also below.\n@@ -214,6 +215,39 @@ not include variables usually directly set during build):\n    ('-M'); set it to ('-C') or ('-C', '-C') to also detect copies, or\n    set it to () if you don't want to have renames detection.\n \n+\n+Projects list file format\n+~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+Instead of having gitweb find repositories by scanning filesystem starting\n+from $projectroot (or $projects_list, if it points to directory), you can\n+provide list of projects by setting $projects_list to a text file with list\n+of projects (and some additional info).  This file uses the following\n+format:\n+\n+One record (for project / repository) per line, whitespace separated fields;\n+does not support (at least for now) lines continuation (newline escaping).\n+Leading and trailing whitespace are ignored, any run of whitespace can be\n+used as field separator (rules for Perl's \"split(' ', $line)\").  Keyed by\n+the first field, which is project name, i.e. path to repository GIT_DIR\n+relative to $projectroot.  Fields use modified URI encoding, defined in\n+RFC 3986, section 2.1 (Percent-Encoding), or rather \"Query string encoding\"\n+(see http://en.wikipedia.org/wiki/Query_string#URL_encoding), the difference\n+being that SP (' ') can be encoded as '+' (and therefore '+' has to be also\n+percent-encoded).  Reserved characters are: '%' (used for encoding), '+'\n+(can be used to encode SPACE), all whitespace characters as defined in Perl,\n+including SP, TAB and LF, (used to separate fields in a record).\n+\n+Currently list of fields is\n+ * <repository path>  - path to repository GIT_DIR, relative to $projectroot\n+ * <repository owner> - displayed as repository owner, preferably full name,\n+                        or email, or both\n+\n+You can additionally use $projects_list file to limit which repositories\n+are visible, and together with $strict_export to limit access to\n+repositories (see \"Gitweb repositories\" section in gitweb/INSTALL).\n+\n+\n Per-repository gitweb configuration\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n@@ -225,8 +259,8 @@ You can use the following files in repository:\n  * README.html\n    A .html file (HTML fragment) which is included on the gitweb project\n    summary page inside <div> block element. You can use it for longer\n-   description of a project, to provide links for example to projects\n-   homepage, etc.\n+   description of a project, to provide links (for example to project's\n+   homepage), etc.\n  * description (or gitweb.description)\n    Short (shortened by default to 25 characters in the projects list page)\n    single line description of a project (of a repository). Plain text file;\n"}]}