[PATCH] gitweb: Document that gitweb deals with bare repositories

[Jakub Narebski <jnareb@gmail.com>]

Add reminders to gitweb/README and gitweb/INSTALL that gitweb works
with bare repositories.  While it might be obvious to us, it is not
apparently as evident for newcomers.

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
On Thu, 1 Jan 2009, Jakub Narebski wrote:

> The longer explanation (which probably should made into gitweb/README
> or gitweb/INSTALL) is that gitweb is meant to deal with _bare_ 
> repositories; gitweb doesn't touch and doesn't examine working area
> of "live" (non-bare) repository. If you host git repositories (like
> kernel.org, freedesktop.org or repo.or.cz) you usually host them bare
> (public repositories should be bare); but you might want to have
> gitweb for your own repository too.

And here it is.

By the way, I was wondering if to mark this patch as an RFC, because
I am not completely sure about the wording I used...

 gitweb/INSTALL |   14 ++++++++++++++
 gitweb/README  |   12 +++++++-----
 2 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/gitweb/INSTALL b/gitweb/INSTALL
index 18c9ce3..f43e233 100644
--- a/gitweb/INSTALL
+++ b/gitweb/INSTALL
@@ -127,6 +127,20 @@ GITWEB_CONFIG file:
 Gitweb repositories
 -------------------
 
+- Gitweb deals with bare repositories, which means that gitweb scans for
+  (in the case where $projects_list is a directory to search for
+  repositories) or has to be provided with list of (in the case where
+  $projects_list is a text file) bare repositories, i.e. $GIT_DIR for
+  each repository. The consequence of that is the fact that if you use
+  gitweb to view non-bare repository named 'repo' then gitweb would show
+  (or would have to be provided with) 'repo/.git'.
+
+  If you want to view a buch of non-bare repositories in gitweb but want
+  them named 'repo.git' as is the standard for bare repositories, you
+  can as a workaround populare $projectroot / $project_list with
+  symbolic links to $GIT_DIR of each project you want to publish (have
+  shown) in gitweb.
+
 - By default all git repositories under projectroot are visible and
   available to gitweb. The list of projects is generated by default by
   scanning the projectroot directory for git repositories (for object
diff --git a/gitweb/README b/gitweb/README
index 825162a..6dbfcd5 100644
--- a/gitweb/README
+++ b/gitweb/README
@@ -34,10 +34,11 @@ You can specify the following configuration variables when building GIT:
  * GITWEB_LIST
    Points to a directory to scan for projects (defaults to project root
    if not set / if empty) or to a file with explicit listing of projects
-   (together with projects' ownership). See "Generating projects list
-   using gitweb" in INSTALL file for gitweb to find out how to generate
-   such file from scan of a directory. [No default, which means use root
-   directory for projects]
+   (together with projects' ownership). Note that gitweb deals with bare
+   repositories; it shows/uses $GIT_DIR for each repository. See also
+   "Generating projects list using gitweb" in INSTALL file for gitweb to
+   find out how to generate such file from scan of a directory. 
+   [No default, which means use root directory for projects]
  * GITWEB_EXPORT_OK
    Show repository only if this file exists (in repository).  Only
    effective if this variable evaluates to true.  [No default / Not set]
@@ -153,7 +154,8 @@ not include variables usually directly set during build):
    Absolute filesystem path which will be prepended to project path;
    the path to repository is $projectroot/$project.  Set to
    $GITWEB_PROJECTROOT during installation.  This variable have to be
-   set correctly for gitweb to find repositories.
+   set correctly for gitweb to find repositories.  (Note that gitweb deals
+   with bare repositories.)
  * $projects_list
    Source of projects list, either directory to scan, or text file
    with list of repositories (in the "<URI-encoded repository path> SP
-- 
1.6.0.4