On Thu, 12 May 2011, Jonathan Nieder wrote:
> Drew Northup wrote:
>
> > This is a work in progress. Much of what is in it has been pulled
> > directly from the README and INSTALL files of gitweb. No effort has yet
> > been made to de-duplicate any of this.
While it might be a good idea to split main part of gitweb/README into
gitweb.conf.txt (documenting configuration), and perhaps also separate
gitweb.txt (main page for gitweb, like SVN::Web manpage), I don't think
that much of gitweb/INSTALL should be moved.
> > TODO:
> > * Clean up README and INSTALL files
> > * Add Makefile rules to build man / HTML pages.
> > * Remove or rephrase redundant portions of original documentation
> > * A lot more...
>
> I agree with this TODO list. :) It should be possible to reuse rules from
> Documentation/Makefile if you put this under Documentation/. gitweb already
> keeps its tests under t/ for convenience; I think it's okay if it
> puts some documentation under Documentation/.
Note that git-gui and gitk both also keep their manpages in Documentation/
as Documentation/git-gui.txt and Documentation/gitk.txt
We can add "doc" target to gitweb/Makefile, which would delegate work to
../Documentation/Makefile, similarly to existing "test" target in
gitweb/Makefile.
> > --- /dev/null
> > +++ b/gitweb/gitweb.conf.txt
> > @@ -0,0 +1,294 @@
> > +gitweb.conf(5)
> > +==============
> > +
> > +NAME
> > +----
> > +gitweb.conf - Gitweb configuration file
>
> It sounds like a tautology. Maybe "configuration for git's web
> interface"? Except that there is at least one other web interface for
> git (cgit). Hm.
Let's take a look how it is done in other section 5 manpages documenting
configuration files:
dhclient.conf(5): dhclient.conf - DHCP client configuration file
ldap.conf(5): ldap.conf, .ldaprc - ldap configuration file
yum.con(5): yum.conf - Configuration file for yum(8).
So it is not much of tautology, I think.
> > +
> > +SYNOPSIS
> > +--------
> > +/etc/gitweb.conf
I'd say
+SYNOPSIS
+--------
+gitweb_conf.perl
+/etc/gitweb.conf
or
+SYNOPSIS
+--------
+$GITWEBDIR/gitweb_conf.perl
+/etc/gitweb.conf
> gitweb will also look for gitweb_config.perl along @INC, and
> the $GITWEB_CONFIG and $GITWEB_CONFIG_SYSTEM envvars can override
> these paths.
I think that we don't need to describe envvars in synopsis, but we
should have per-gitweb configuration file (gitweb_conf.perl) in
"Synopsis" section.
> > +
> > +DESCRIPTION
> > +-----------
> > +'Gitweb' is a CGI application for viewing Git repositories over the web. The
> > +configuration file is used to override the default settings that were built
> > +into gitweb at the time Git itself was compiled.
>
> Style nit: I'd launch into what gitweb.conf contains right away, like
> so:
>
> The gitweb CGI script for viewing Git repositories over the
> web uses a perl script fragment as its configuration file.
> You can set variables using "our $variable = value"; text
> from a "#" character until the end of a line is ignored.
> See *perlsyn*(1) for details.
>
> The configuration file is used to override the default
> settings that were built into gitweb at the time it was
> installed.
I agree with Jonathan here.
> > +While one could just alter
> > +the configuration settings in the gitweb CGI itself, those changes would be
> > +lost upon upgrade. Configuration settings my also be placed into a file in
> > +the same directory as the CGI script with the default name
> > +`gitweb_config.perl` – allowing one to have multiple gitweb instances
> > +with different configurations by the use of symlinks.
>
> Good point; I hadn't thought about the multiple-configurations use case.
Right.
> > +DISCUSSION
> > +----------
> > +
> > +The location of `gitweb.conf` is defined at compile time using the
> > +configuration value `GITWEB_CONFIG_SYSTEM` and defaults to /etc/gitweb.conf.
> > +The name of the per-instance configuration file is defined in gitweb by
> > +`GITWEB_CONFIG`.
> > +
> > +*NOTE:* Values defined in the per-instance configuration file override both
> > +values found in the gitweb CGI as well as values found in the sytem-wide
> > +gitweb.conf file.
>
> Doesn't gitweb_config.perl suppress the effect of gitweb.conf altogether?
Yes it does.
The sequence is as following:
1. Per-gitweb configuration file is given by envvar GITWEB_CONFIG; if it
is not set, then by default gitweb_conf.perl is used (one can override
the latter name via build-time configuration variable GITWEB_CONFIG).
Note: relative path means relative to installed gitweb.cgi script.
2. System-wide configuration file is given by envvar GITWEB_CONFIG_SYSTEM;
if it is not set, then by default /etc/gitweb.conf is used (one can
override the latter name via build-time configuration variable
GITWEB_CONFIG_SYSTEM). Note: sysconfdir is not taken into account
by gitweb/Makefile, but perhaps it should.
Gitweb obtains configuration data from the following sources in the
following order:
1. gitweb's installation configuration file ($GITWEBDIR/gitweb_conf.perl)
2. system-wide configuration file (/etc/gitweb.conf)
First existing config file is used.
Sidenote: we could replace GITWE_CONFIG and GITWEB_CONFIG_SYSTEM in
gitweb.conf.txt during building documentation.
> > +
> > +The syntax of the configuration files is that of PERL, as these files are
> > +indeed handled as fragments of PERL code (the language that gitweb itself is
> > +written in). Variables may be set using "'our $variable = value'"; text from
> > +"#" character until the end of a line is ignored. See the perlsyn(1) man page
> > +for more information.
Actually using 'our $variable = <value>' is a safety check: if newer gitweb
does no longer use given value, using 'our' wouldn't cause errors.
> The perl manual spells the name of that language as "Perl". I think
> it might make sense to mention the syntax earlier, since it makes it
> less daunting to dive into the file right away.
I think it might be good idea to provide bare-bones example here.
> > +
> > +One good reason to take advatage of the system-wide and local gitweb
> > +configuration files is that not all settings may be set up directly in the CGI
> > +itself. Optional features – defined using the '%features' variable
> > +– must be set in one of the two configuration files.
>
> I don't follow what this paragraph is saying. Is the idea something
> like this?
>
> The default configuration with no configuration file at all
> may work perfectly well for some installations. Still, a
> configuration file is useful for customizing or tweaking the
> behavior of gitweb in many ways, and some optional features
> will not be present unless explicitly enabled using the
> configurable %features variable.
I think the idea is that not all of configuration knobs can be tweaked
during "compile"-time. Some require setting from configuration file.
Note: we probably want to mention gitweb/config.mak or config.mak somewhere
as place to save build-time configuration, persistently.
> > +
> > +CONFIGURATION SETTINGS
> > +----------------------
>
> Configuration settings as opposed to non-configuration settings? :)
>
> Maybe something like
>
> VARIABLES
> ---------
>
> would be clearer.
Perhaps.
> > +Standard Options
> > +~~~~~~~~~~~~~~~~~
> > +The following are not typically set or overridden at build time:
[...]
> > +
> > +$GIT::
> > + Core git executable to use.
>
> Ah, what a variable to start with. Maybe this can be snuck later in
> the list somehow, so the reader can get to juicier bits first.
This is set at build time, by default to $(bindir)/git
> > +$version::
> > + Gitweb version, set automatically when creating gitweb.cgi from
> > + gitweb.perl. You might want to modify it if you are running modified
> > + gitweb.
>
> Why would I want to set this in the config file? Wouldn't my patch to
> gitweb.cgi modify $version?
Well, for running gitweb.perl (not build!) from command line I use
our $version = "current";
But this is I think rare case.
> > +$projectroot::
> > + 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 has to be
> > + set correctly for gitweb to find repositories.
>
> This is an interesting one. The description is not so clear to me ---
> I guess the idea is that if $projectroot = "/srv/git" then
>
> http://path/to/gitweb/installation/?p=foo/bar.git
>
> will map to /srv/git/foo/bar.git on the filesystem (and likewise for
> PATH_INFO based URLs)?
Yes.
> > +$projects_list::
> > + Source of projects list, either directory to scan, or text file
> > + with list of repositories (in the "`<URI-encoded repository path> SP
> > + <URI-encoded repository owner>`" line format; actually there can be
> > + any sequence of whitespace in place of space (SP)). Set to
> > + `$GITWEB_LIST` during installation. If empty, `$projectroot` is used
> > + to scan for repositories.
>
> Maybe clearer to emphasize the kinds of values it takes first? That
> is:
>
> Space-separated list of paths to files listing projects or
> directories to be scanned for projects. Project list files
> should list one project per line, with each line having the
> format "`<URI-encoded filesystem path to repository> SP
> <URI-encoded repository owner>`. The default is determined
> by the GITWEB_LIST makefile variable at installation time.
> If this variable is empty, gitweb will fall back to scanning
> the `$projectroot` for repositories.
I think to not have long wall of text here, we should reference part
of documentation that explains how gitweb finds repositories, including
format of $projects_list file.
> [...]
> > +Configuration Options Often Set at Compile Time
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +These configuration variables are often specified at compile time and are
> > +defined by default in the gitweb CGI itself:
> > +
> > +GIT_BINDIR::
> > + Points where to find the git executable. You should set it up to
> > + the place where the git binary was installed (usually /usr/bin) if you
> > + don't install git from sources together with gitweb. [Default: $(bindir)]
>
> I don't think there is a GIT_BINDIR configuration variable, though
> there is a makefile variable with that name used to determine the
> default value of $GIT.
>
> Likewise for the others. I don't think they belong in the manpage.
I agree. What is important during build time "only" should remain in
gitweb/INSTALL.
--
Jakub Narebski
Poland
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html