git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH/WIP] Starting work on a man page for /etc/gitweb.conf

From
Jonathan Nieder <jrnieder@gmail.com>
Date
May 12, 2011, 10:53 UTC
Message-ID
<20110512105325.GA13490@elie>
In-Reply-To
<1305141664.30104.11.camel@drew-northup.unet.maine.edu>
Hi Drew,
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.
Thanks!
Show 5 quoted lines
> 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/.

> If you don't really need (or want) to be on the CC list let me know. You were
> in the output of 'git blame'....

I've aggressively culled the cc list for my reply to avoid punishing kind people who improved gitweb by swamping them with mail.

Show 9 quoted lines
> --- /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.

> +
> +SYNOPSIS
> +--------
> +/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.

Show 6 quoted lines
> +
> +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.
Show 6 quoted lines
> 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` &#8211; 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.
Show 11 quoted lines
> +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?
Show 6 quoted lines
> +
> +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.

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.

Show 5 quoted lines
> +
> +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 &#8211; defined using the '%features' variable
> +&#8211; 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.
> +
> +CONFIGURATION SETTINGS
> +----------------------
Configuration settings as opposed to non-configuration settings? :)
Maybe something like
	VARIABLES
	---------
would be clearer.
> +Standard Options
> +~~~~~~~~~~~~~~~~~
> +The following are not typically set or overridden at build time:
I suppose the above is a paraphrase of
 (with the exception of $projectroot and $projects_list this list does
 not include variables usually directly set during build):

but this shortened version just left me confused (why do I care which variables people typically override at build time?). The original suggests that for build-time configuration I should look elsewhere, which made it a little clearer to me.

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

> +$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?

Show 5 quoted lines
> +$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)?

Show 7 quoted lines
> +$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.
[...]
Show 9 quoted lines
> +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.
[...]
> +Configuration File Example
> +~~~~~~~~~~~~~~~~~~~~~~~~~~

Ah, glad you did this. I would make "Example" or "Examples" a separate top-level section so they are easier to find.

Ok, that's all for now.  Still, hope that helps.

Regards, Jonathan

Previous: Drew NorthupNext: Jakub Narebski
Message 2 of 11 in “Starting work on a man page for /etc/gitweb.conf”
  1. Starting work on a man page for /etc/gitweb.confDrew Northup, May 11, 2011
  2. Jonathan NiederMay 12, 2011
  3. Jakub NarebskiMay 12, 2011
  4. Drew NorthupMay 12, 2011
  5. J.H.May 12, 2011
  6. Drew NorthupMay 12, 2011
  7. Jakub NarebskiMay 12, 2011
  8. Jakub NarebskiMay 12, 2011
  9. Drew NorthupMay 12, 2011
  10. Jakub NarebskiMay 12, 2011
  11. gitweb: Starting work on a man page for gitweb (WIP)Jakub Narebski, May 15, 2011

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.