* [PATCH/RFCv4 0/4] Moving gitweb documentation to manpages
@ 2011-09-18 13:34 Jakub Narebski
2011-09-18 13:34 ` [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages Jakub Narebski
` (3 more replies)
0 siblings, 4 replies; 12+ messages in thread
From: Jakub Narebski @ 2011-09-18 13:34 UTC (permalink / raw)
To: git, Drew Northup
Cc: Jonathan Nieder, John 'Warthog9' Hawley, admin,
Jakub Narebski
The original patch adding manpage for /etc/gitweb.conf was sent by
Drew Northup; I have added manpage for gitweb itself, inspired by his
patch. Unfortunately Drew doesn't currently have time to work on this
patch (patch series), so that is why it is me resending this series.
It is closer to final version, but still is a bit work in progres.
The main improvement is that documentation now renders correctly as
HTML.
Note that we should probably add gitweb(1) and gitweb.conf(5) manpages
to the list in git(1) manpage.
Table of contents:
~~~~~~~~~~~~~~~~~~
1. The changes to Documentation/Makefile adding gitweb-doc target and
to gitweb/Makefile adding doc target are now upfront as a separate
patch, compared to previous version of this series:
"[RFC/PATCHv3 0/5] Improving gitweb documentation, creating manpages"
http://thread.gmane.org/gmane.comp.version-control.git/175140
This is mainly so that description of ideas, which is common for both
gitweb.conf.txt and gitweb.txt, is in a separate upfront commit
message.
2. The man page for /etc/gitweb.conf is modified, extended and
improved version of original patch by Drew Northup from
"[PATCH/WIP] Starting work on a man page for /etc/gitweb.conf"
http://thread.gmane.org/gmane.comp.version-control.git/173422
Drew version was mostly pulled directly from the README and INSTALL
files of gitweb. I have tried to incorporate comments in mentioned
thread, and to group config variables by category. This version
is also checked that it renders correctly as HTML and as manpage,
compared to version send earlier in
"[RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)"
http://thread.gmane.org/gmane.comp.version-control.git/175140/focus=175145
This version now moves, rather than copies, contents from
gitweb/README file. It now has up-to-date commit message.
It was also updated to include new gitweb-comon.conf config file
(common system-wide config file, used *in addition to* per-instance
gitweb_config.perl config file).
3. The man page for gitweb is improved version of patch I have sent to
git mailing list as
"[RFC/PATCHv3 5/5] gitweb: Starting work on a man page for gitweb (WIP)"
http://thread.gmane.org/gmane.comp.version-control.git/175140/focus=175146
This version was fixed to render correctly as HTML and as manpage, and
has update commit message.
4. The addition of gitweb manpages to 'gitweb' subpackage in
gitweb.spec (via gitweb.spec.in) is new in this series.
Shortlog:
~~~~~~~~~
Drew Northup (1):
gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation)
Jakub Narebski (3):
Documentation: Preparation for gitweb manpages
gitweb: Add manpage for gitweb
gitweb: Add gitweb manpages to 'gitweb' package in git.spec
Diffstat:
~~~~~~~~~
Documentation/Makefile | 7 +-
Documentation/gitweb.conf.txt | 789 +++++++++++++++++++++++++++++++++++++++++
Documentation/gitweb.txt | 703 ++++++++++++++++++++++++++++++++++++
git.spec.in | 7 +
gitweb/INSTALL | 96 +-----
gitweb/Makefile | 7 +-
gitweb/README | 411 ++--------------------
7 files changed, 1540 insertions(+), 480 deletions(-)
create mode 100644 Documentation/gitweb.conf.txt
create mode 100644 Documentation/gitweb.txt
--
1.7.6
^ permalink raw reply [flat|nested] 12+ messages in thread* [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages 2011-09-18 13:34 [PATCH/RFCv4 0/4] Moving gitweb documentation to manpages Jakub Narebski @ 2011-09-18 13:34 ` Jakub Narebski 2011-09-19 23:37 ` Jonathan Nieder 2011-09-18 13:34 ` [PATCH/RFCv4 2/4] gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation) Jakub Narebski ` (2 subsequent siblings) 3 siblings, 1 reply; 12+ messages in thread From: Jakub Narebski @ 2011-09-18 13:34 UTC (permalink / raw) To: git, Drew Northup Cc: Jonathan Nieder, John 'Warthog9' Hawley, admin, Jakub Narebski Gitweb documentation currently consist of gitweb/README, gitweb/INSTALL and comments in gitweb source code. This is harder to find, use and browse that manpages ("man gitweb" or "git help gitweb") and HTML documentation ("git help --web gitweb"). The goal is to move documentation out of gitweb/README to gitweb.txt and gitweb.conf.txt manpages, reducing its size 10x from around 500 to around 50 lines (two pages), and move information not related drectly to building and installing gitweb out of gitweb/INSTALL there. The idea is to have gitweb manpage sources reside in AsciiDoc format in Documentation/ directory, like for gitk and git-gui. Alternate solution would be to have gitweb documentation in gitweb/ directory, perhaps in POD format (see perlpod(1)). This patch adds infrastructure for easy generating gitweb-related manpages. It adds currently empty 'gitweb-doc' target to Documentation/Makefile, and 'doc' proxy target to gitweb's Makefile. This way to build gitweb documentation one can use make -C gitweb doc or cd gitweb; make doc The gitweb.conf(5) and gitweb(1) manpages will be added in subsequent commits. Signed-off-by: Jakub Narebski <jnareb@gmail.com> --- This changes were part of patch adding first gitweb manpage in previous version of this series. Compared to v3 series it lacks the following hunk (at the very end of Documentation/Makefile): @@ -334,4 +337,4 @@ quick-install-man: quick-install-html: '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REF) $(DESTDIR)$(htmldir) -.PHONY: FORCE +.PHONY: FORCE gitweb-doc This is because it would introduce inconsistency, as 'gitweb-doc' would be only one of many phony targets in Documentation/Makefile that is explicitly marked .PHONY So this is something left for other commit. Documentation/Makefile | 3 +++ gitweb/Makefile | 7 ++++++- 2 files changed, 9 insertions(+), 1 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 6346a75..44be67b 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -170,6 +170,9 @@ info: git.info gitman.info pdf: user-manual.pdf +GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7)) +gitweb-doc: $(GITWEB_DOC) + install: install-man install-man: man diff --git a/gitweb/Makefile b/gitweb/Makefile index 1c85b5f..3014d80 100644 --- a/gitweb/Makefile +++ b/gitweb/Makefile @@ -174,6 +174,11 @@ test-installed: GITWEB_TEST_INSTALLED='$(DESTDIR_SQ)$(gitwebdir_SQ)' \ $(MAKE) -C ../t gitweb-test +### Documentation + +doc: + $(MAKE) -C ../Documentation gitweb-doc + ### Installation rules install: all @@ -187,5 +192,5 @@ install: all clean: $(RM) gitweb.cgi static/gitweb.min.js static/gitweb.min.css GITWEB-BUILD-OPTIONS -.PHONY: all clean install test test-installed .FORCE-GIT-VERSION-FILE FORCE +.PHONY: all clean install test test-installed doc .FORCE-GIT-VERSION-FILE FORCE -- 1.7.6 ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages 2011-09-18 13:34 ` [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages Jakub Narebski @ 2011-09-19 23:37 ` Jonathan Nieder 2011-09-20 0:10 ` Jakub Narebski 2011-09-20 20:11 ` Jakub Narebski 0 siblings, 2 replies; 12+ messages in thread From: Jonathan Nieder @ 2011-09-19 23:37 UTC (permalink / raw) To: Jakub Narebski; +Cc: git, Drew Northup, John 'Warthog9' Hawley, admin Jakub Narebski wrote: > Gitweb documentation currently consist of gitweb/README, gitweb/INSTALL > and comments in gitweb source code. This is harder to find, use and > browse that manpages ("man gitweb" or "git help gitweb") and HTML > documentation ("git help --web gitweb"). Language nits: s/consist/consists/; s/that manpages/than manpages/. I completely agree. > The goal is to move documentation out of gitweb/README to gitweb.txt and > gitweb.conf.txt manpages, reducing its size 10x from around 500 to > around 50 lines (two pages), and move information not related drectly to > building and installing gitweb out of gitweb/INSTALL there. I guess you mean this patch prepares for or is part of a larger project or series with that goal? Wording nits: s/and move information/and to move information/; s/drectly/directly/; s/ there//. > The idea is to have gitweb manpage sources reside in AsciiDoc format > in Documentation/ directory, like for gitk and git-gui. Alternate > solution would be to have gitweb documentation in gitweb/ directory, > perhaps in POD format (see perlpod(1)). Language nits: missing "the" before "Documentation/ directory" and "gitweb manpage sources"; missing "An" before "Alternate solution". I guess this is the most controversial aspect of the patch; your idea seems sane enough to me. > This patch adds infrastructure for easy generating gitweb-related > manpages. It adds currently empty 'gitweb-doc' target to > Documentation/Makefile, and 'doc' proxy target to gitweb's Makefile. Language nits: s/easy/easily/; missing "a" before "currently empty 'gitweb-doc' target" and "'doc' proxy target". > This way to build gitweb documentation one can use > > make -C gitweb doc > > or > > cd gitweb; make doc Language nit: a comma after "This way" would disambiguate. Does "make -CDocumentation man html" build the gitweb documentation, too (and "make install-doc" install it)? [...] > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -170,6 +170,9 @@ info: git.info gitman.info > > pdf: user-manual.pdf > > +GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7)) > +gitweb-doc: $(GITWEB_DOC) Looks like no, alas. Except for that detail, this looks good. Thanks, Jonathan ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages 2011-09-19 23:37 ` Jonathan Nieder @ 2011-09-20 0:10 ` Jakub Narebski 2011-09-20 20:11 ` Jakub Narebski 1 sibling, 0 replies; 12+ messages in thread From: Jakub Narebski @ 2011-09-20 0:10 UTC (permalink / raw) To: Jonathan Nieder; +Cc: git, Drew Northup, John 'Warthog9' Hawley, admin Thanks a lot for all language fixes. Nb. I'll respond to other comments separately. On Tue, 20 Sep 2011, Jonathan Nieder wrote: > Jakub Narebski wrote: > > This way to build gitweb documentation one can use > > > > make -C gitweb doc > > > > or > > > > cd gitweb; make doc Actually it should read "to build only gitweb documentation"... > Does "make -CDocumentation man html" build the gitweb documentation, > too (and "make install-doc" install it)? > > [...] > > --- a/Documentation/Makefile > > +++ b/Documentation/Makefile > > @@ -170,6 +170,9 @@ info: git.info gitman.info > > > > pdf: user-manual.pdf > > > > +GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7)) > > +gitweb-doc: $(GITWEB_DOC) > > Looks like no, alas. ... because of the fact that gitweb.txt is in DOC_MAN1, and gitweb.conf.txt is in DOC_MAN5, then 'make doc' would among others build gitweb documentation. 'make -C Documentation gitweb-doc' / 'make -C gitweb doc' just builds a _subset_ of said documentation. > > Except for that detail, this looks good. Nb. what is also missing is having links to gitweb(1) and gitweb.conf(5) in git(1) manpages together with the rest. -- Jakub Narebski Poland ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages 2011-09-19 23:37 ` Jonathan Nieder 2011-09-20 0:10 ` Jakub Narebski @ 2011-09-20 20:11 ` Jakub Narebski 2011-09-20 20:19 ` Jonathan Nieder 1 sibling, 1 reply; 12+ messages in thread From: Jakub Narebski @ 2011-09-20 20:11 UTC (permalink / raw) To: Jonathan Nieder; +Cc: git, Drew Northup Thanks again for all language fixes. English is my secondary language... Jonathan Nieder wrote: > Jakub Narebski wrote: > > The goal is to move documentation out of gitweb/README to gitweb.txt and > > gitweb.conf.txt manpages, reducing its size 10x from around 500 to > > around 50 lines (two pages), and move information not related drectly to > > building and installing gitweb out of gitweb/INSTALL there. > > I guess you mean this patch prepares for or is part of a larger > project or series with that goal? [...] [...] > > This way to build gitweb documentation one can use > > > > make -C gitweb doc > > > > or > > > > cd gitweb; make doc > > Language nit: a comma after "This way" would disambiguate. > > Does "make -CDocumentation man html" build the gitweb documentation, > too (and "make install-doc" install it)? Jonathan Nieder wrote: > Maybe its commit message could > be clarified to mention that the new targets build a subset of the pages > built by the ordinary "make doc" et al targets. I hope that this version is more clear: -- >8 -- From: Jakub Narebski <jnareb@gmail.com> Subject: [PATCH/RFCv5 1/4] Documentation: Preparation for gitweb manpages Gitweb documentation currently consists of gitweb/README, gitweb/INSTALL and comments in gitweb source code. This is harder to find, use and browse than manpages ("man gitweb" or "git help gitweb") and HTML documentation ("git help --web gitweb"). The goal of the next two commits is to move documentation out of gitweb/README to gitweb.txt and gitweb.conf.txt manpages, reducing its size 10x from around 500 to around 50 lines (two pages), and to move information not related directly to building and installing gitweb out of gitweb/INSTALL. The idea is to have the gitweb manpage sources reside in AsciiDoc format in the Documentation/ directory, like for gitk and git-gui. This means that building git documentation (with "make doc") would also build gitweb manpages. An alternate solution would be to have gitweb documentation in the gitweb/ directory, perhaps in POD format (see perlpod(1)). This patch adds infrastructure for easy generation of only gitweb-related manpages. It adds a currently empty 'gitweb-doc' target to Documentation/Makefile, and a 'doc' proxy target to gitweb/Makefile. This way to build only gitweb documentation in both 'man' and 'html' formats one can use make -C gitweb doc or cd gitweb; make doc This somewhat follows the idea of 'full-svn-test' and 'gitweb-test' in t/Makefile. Note also that with alternate solution, where source of gitweb manpages would reside in the gitweb/ directory, "make doc" would invoke "make -C gitweb doc" to generate formatted docs. The gitweb.conf(5) and gitweb(1) manpages will be added in subsequent commits. Signed-off-by: Jakub Narebski <jnareb@gmail.com> --- Documentation/Makefile | 3 +++ gitweb/Makefile | 7 ++++++- 2 files changed, 9 insertions(+), 1 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 6346a75..44be67b 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -170,6 +170,9 @@ info: git.info gitman.info pdf: user-manual.pdf +GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7)) +gitweb-doc: $(GITWEB_DOC) + install: install-man install-man: man diff --git a/gitweb/Makefile b/gitweb/Makefile index 1c85b5f..3014d80 100644 --- a/gitweb/Makefile +++ b/gitweb/Makefile @@ -174,6 +174,11 @@ test-installed: GITWEB_TEST_INSTALLED='$(DESTDIR_SQ)$(gitwebdir_SQ)' \ $(MAKE) -C ../t gitweb-test +### Documentation + +doc: + $(MAKE) -C ../Documentation gitweb-doc + ### Installation rules install: all @@ -187,5 +192,5 @@ install: all clean: $(RM) gitweb.cgi static/gitweb.min.js static/gitweb.min.css GITWEB-BUILD-OPTIONS -.PHONY: all clean install test test-installed .FORCE-GIT-VERSION-FILE FORCE +.PHONY: all clean install test test-installed doc .FORCE-GIT-VERSION-FILE FORCE -- 1.7.6 ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages 2011-09-20 20:11 ` Jakub Narebski @ 2011-09-20 20:19 ` Jonathan Nieder 2011-09-20 20:33 ` Jakub Narebski 0 siblings, 1 reply; 12+ messages in thread From: Jonathan Nieder @ 2011-09-20 20:19 UTC (permalink / raw) To: Jakub Narebski; +Cc: git, Drew Northup Jakub Narebski wrote: > I hope that this version is more clear: Yep, it doesn't leave me confused any more. Thanks, this looks good (and sorry for my carelessness in reading the patch before). ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages 2011-09-20 20:19 ` Jonathan Nieder @ 2011-09-20 20:33 ` Jakub Narebski 0 siblings, 0 replies; 12+ messages in thread From: Jakub Narebski @ 2011-09-20 20:33 UTC (permalink / raw) To: Jonathan Nieder; +Cc: git, Drew Northup Jonathan Nieder wrote: > Jakub Narebski wrote: > > > I hope that this version is more clear: > > Yep, it doesn't leave me confused any more. Thanks, this looks good > (and sorry for my carelessness in reading the patch before). No, your concern was valid. It's better to be more explicit. -- Jakub Narebski Poland ^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH/RFCv4 2/4] gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation) 2011-09-18 13:34 [PATCH/RFCv4 0/4] Moving gitweb documentation to manpages Jakub Narebski 2011-09-18 13:34 ` [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages Jakub Narebski @ 2011-09-18 13:34 ` Jakub Narebski 2011-09-20 4:41 ` Jonathan Nieder 2011-09-18 13:34 ` [PATCH/RFCv4 3/4] gitweb: Add manpage for gitweb Jakub Narebski 2011-09-18 13:34 ` [PATCH/RFCv4 4/4] gitweb: Add gitweb manpages to 'gitweb' package in git.spec Jakub Narebski 3 siblings, 1 reply; 12+ messages in thread From: Jakub Narebski @ 2011-09-18 13:34 UTC (permalink / raw) To: git, Drew Northup Cc: Jonathan Nieder, John 'Warthog9' Hawley, admin, Jakub Narebski From: Drew Northup <drew.northup@maine.edu> Much of what is in gitweb.conf.txt has been pulled directly from the README file of gitweb. The manpage was supplemented with description of missing gitweb config variables, and with description of gitweb's %features. There remains a bit of redundancy, which should be reduced if possible... but I think some of duplication of information is inevitable. [jn: Improved, extended, removed duplicate info from README] Signed-off-by: Drew Northup <drew.northup@maine.edu> Signed-off-by: Jakub Narebski <jnareb@gmail.com> --- Differences from v3 version include: * SYNOPSIS changed from ssh_config(5) like to gitignore(5) like, i.e. [verse] changed to straight list of files * The beginning of DISCUSSION section now mentions new gitweb-common.conf file, and was significantly rewritten for better readibility, following gitweb/README. * FILES and ENVIRONMENT section mention /etc/gitweb-common.conf and GITWEB_CONFIG_COMMON, respectively. * Added information about inclusion mechanism, i.e. read_config_file() subroutine. * Fixed formatting of continued description list * Infrastructure for supporting "make -C gitweb doc" (used to test formatted output of manpages from those patches) is now moved to a separate, earlier commit. Documentation/Makefile | 2 +- Documentation/gitweb.conf.txt | 781 +++++++++++++++++++++++++++++++++++++++++ gitweb/README | 133 +------- 3 files changed, 783 insertions(+), 133 deletions(-) create mode 100644 Documentation/gitweb.conf.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index 44be67b..6d71943 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -3,7 +3,7 @@ MAN1_TXT= \ $(wildcard git-*.txt)) \ gitk.txt git.txt MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \ - gitrepository-layout.txt + gitrepository-layout.txt gitweb.conf.txt MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \ gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \ gitdiffcore.txt gitnamespaces.txt gitrevisions.txt gitworkflows.txt diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt new file mode 100644 index 0000000..2769302 --- /dev/null +++ b/Documentation/gitweb.conf.txt @@ -0,0 +1,781 @@ +gitweb.conf(5) +============== + +NAME +---- +gitweb.conf - Gitweb (git web interface) configuration file + +SYNOPSIS +-------- +/etc/gitweb.conf, /etc/gitweb-common.conf, $GITWEBDIR/gitweb_config.perl + +DESCRIPTION +----------- + +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. + +An example: + + # gitweb configuration file for http://git.example.org + # + our $projectroot = "/srv/git"; # FHS recommendation + our $site_name = 'Example.org >> Repos'; + + +The configuration file is used to override the default settings that +were built into gitweb at the time 'gitweb.cgi' script was generated. + +While one could just alter the configuration settings in the gitweb +CGI itself, those changes would be lost upon upgrade. Configuration +settings might 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. + + +DISCUSSION +---------- +Gitweb obtains configuration data from the following sources in the +following order: + + * built-in values (some set during build stage), + + * common system-wide configuration file (defaults to + '/etc/gitweb-common.conf'), + + * either per-instance configuration file (defaults to 'gitweb_config.perl' + in the same directory as the installed gitweb), or if it does not exists + then system-wide configuration file (defaults to '/etc/gitweb.conf'). + +Values obtained in later configuration files override values obtained earlier +in above sequence. + +The location of common system-wide configuration file, of fallback system-wide +configuration file and of per-instance configuration file is defined at compile +time using the build-time Makefile configuration variables, respectively +`GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG`. + +You can override location of gitweb configuration files during runtime +by setting respective environment variables: `GITWEB_CONFIG_COMMON`, +`GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG` to non-empty value. + + +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` qualifier in `our $variable = <value>;` is a safety +check: if newer gitweb does no longer use given variable, by using `our` we +won't get syntax errors. + +You can include other configuration file using read_config_file() +subroutine. For example, you can read defaults in fallback +system-wide GITWEB_CONFIG_SYSTEM from GITWEB_CONFIG by adding + + read_config_file($GITWEB_CONFIG_SYSTEM); + +at very beginning of per-instance GITWEB_CONFIG file. In this case +settings in said per-instance file will override settings from +system-wide configuration file. Note that read_config_file checks +itself that the file it reads exists. + + +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 (see also "Configuring gitweb +features" section below). + + +CONFIGURATION VARIABLES +----------------------- +Some of configuration variables have their default values (embedded in CGI +file) set during building gitweb -- if that is the case, it is put in their +description. See gitweb's 'INSTALL' file for instructions on building and +installing gitweb. + + +Location of repositories +~~~~~~~~~~~~~~~~~~~~~~~~ +Configuration variables described below control finding git repositories by +gitweb, and control display and access to repositories. + +$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. ++ +For example if `$projectroot` is set to "/srv/git" by putting the following +in gitweb config file: ++ +---------------------------------------------------------------------------- +our $projectroot = "/srv/git"; +---------------------------------------------------------------------------- ++ +then ++ +------------------------------------------------ +http://git.example.com/gitweb.cgi?p=foo/bar.git +------------------------------------------------ ++ +or its path_info based equivalent ++ +------------------------------------------------ +http://git.example.com/gitweb.cgi/foo/bar.git +------------------------------------------------ ++ +will map to path '/srv/git/foo/bar.git' on filesystem. + +$project_maxdepth:: + Filesystem traversing depth limit for recursively scanning for git + repositories, used if `$projects_list` (below) is unset. The default + value of this variable is determined by build-time configuration + variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to 2007. + +$projects_list:: + Plain text file listing projects or name of directory + to be scanned for projects. ++ +Project list files should list one project per line, with each line +having the following format ++ +----------------------------------------------------------------------------- +<URI-encoded filesystem path to repository> SP <URI-encoded repository owner> +----------------------------------------------------------------------------- ++ +The default value of this variable is determined by the `GITWEB_LIST` +makefile variable at installation time. If this variable is empty, gitweb +will fall back to scanning the `$projectroot` directory for repositories. + +$export_ok:: + Show repository only if this file exists (in repository). Only + effective if this variable evaluates to true. Can be set during + building gitweb via `GITWEB_EXPORT_OK`. [No default / Not set] + +$export_auth_hook:: + Show repository only if this subroutine returns true, when given as + the only parameter the full path to the project. Example: ++ +---------------------------------------------------------------------------- +our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; }; +---------------------------------------------------------------------------- ++ +though the above might be done by using `$export_ok` instead ++ +---------------------------------------------------------------------------- +our $export_ok = "git-daemon-export-ok"; +---------------------------------------------------------------------------- + +$strict_export:: + Only allow viewing of repositories also shown on the overview page. + This for example makes `$gitweb_export_ok` file decide if repository is + available and not only if it is shown. If `$gitweb_list` points to + file with list of project, only those repositories listed would be + available for gitweb. Can be set during building gitweb via + `GITWEB_STRICT_EXPORT`. [No default / Not set] + + +Finding files +~~~~~~~~~~~~~ +Those configuration variables tell gitweb where to find files. Values of +those variables are paths on filesystem. Of those only `$GIT` is required +to be (correctly) set for gitweb to be able to work; all the rest are +required only for extra configuration or extra features. + +$GIT:: + Core git executable to use. By default set to `$GIT_BINDIR/git`, which + in turn is by default set to `$(bindir)/git`. If you use git from binary + package, set this to "/usr/bin/git". This can just be "git" if your + webserver has a sensible PATH. If you have multiple git versions installed + it can be used to choose which one to use. + +$mimetypes_file:: + File to use for (filename extension based) guessing of MIME types before + trying '/etc/mime.types'. Path, if relative, is taken currently as + relative to the current git repository. [Unset by default] + +$highlight_bin:: + Path to the highlight executable to use (must be the one from + http://www.andre-simon.de due to assumptions about parameters and output). + Useful if 'highlight' is not installed on your webserver's PATH. + [Default: 'highlight'] ++ +*NOTE*: if you want to add support for new syntax (supported by +"highlight" but not used by gitweb), you need to modify `%highlight_ext` +or `%highlight_basename`, depending on whether you detect type of file +based on extension (for example "*.sh") or on its basename (for example +"Makefile"). Keys of those hashes are extension or basename, +respectively, and value for given key is name of syntax to be passed via +`--syntax <syntax>` to highlighter. + + +Links and their targets +~~~~~~~~~~~~~~~~~~~~~~~ +Configuration variables described below configure some of gitweb links: +their target and their look (text or image), and where to find page +prerequisites (stylesheet, favicon, images, scripts). Usually they are left +at their default values, with the possible exception of `@stylesheets` +variable. + +@stylesheets:: + List of URIs of stylesheets (relative to base URI of a page). You + might specify more than one stylesheet, for example use gitweb.css + as base, with site specific modifications in separate stylesheet + to make it easier to upgrade gitweb. You can add a `site` stylesheet + for example by putting ++ +---------------------------------------------------------------------------- +push @stylesheets, "gitweb-site.css"; +---------------------------------------------------------------------------- ++ +in the gitweb config file. Those values that are relative paths, are +relative to base URI of gitweb. ++ +This list should contain URI of gitweb's stylesheet. The URI of gitweb +stylesheet is set during build time via `GITWEB_CSS` variable. It's default +value is 'static/gitweb.css' (or 'static/gitweb.min.css' if the `CSSMIN` +variable is defined, i.e. if CSS minifier is used during build). ++ +*Note*: there is also legacy `$stylesheet` configuration variable, which was +used by older gitweb. + +$logo:: + Points to the location where you put 'git-logo.png' on your web + server, or to be more generic URI of logo, 72x27 size). This image + is displayed in top right corner of each gitweb page, and used as + logo for Atom feed. Relative to base URI of gitweb (as a path). + Can be adjusted during building gitweb using `GITWEB_LOGO` variable + [Default: 'static/git-logo.png'] + +$favicon:: + Points to the location where you put 'git-favicon.png' on your web + server, or to be more generic URI of favicon, assumed to be + "image/png" type; web browsers that support favicons (website icons) + may display them in the browser's URL bar and next to site name in + bookmarks. Relative to base URI of gitweb. Can be adjusted during + build time using `GITWEB_FAVICON` variable. + [Default: 'static/git-favicon.png'] + +$javascript:: + Points to the location where you put 'gitweb.js' on your web server, + or to be more generic URI of JavaScript code used by gitweb. + Relative to base URI of gitweb. Set during build time using + `GITWEB_JS` build-time configuration variable. ++ +Default value is either 'static/gitweb.js', or 'static/gitweb.min.js' if +`JSMIN` build variable is defined, i.e. if JavaScript minifier is used +during build. *Note* that this single file is build (composed) of +individual JavaScript "modules". + +$home_link:: + Target of the home link on top of all pages (the first part of view + "breadcrumbs"). By default set to absolute URI of a page ($my_uri). + +$home_link_str:: + Description of the home link on top of all pages, leading to $home_link + (usually main gitweb page, which means projects list). Used as first + part of gitweb view "breadcrumb trail": `<home> / <project> / <view>`. + Can be set during build time using `GITWEB_HOME_LINK_STR` variable. + [Default: "projects"] + +$logo_url:: +$logo_label:: + URI and label (title) of GIT logo link (or your site logo, if you choose + to use different logo image). By default they point to git homepage; + in the past they pointed to git documentation at www.kernel.org. + + +Changing gitweb look +~~~~~~~~~~~~~~~~~~~~ +You can adjust how pages generated by gitweb look using variables described +below. You can change site name, add common headers and footers for all +pages, and add description of gitweb installation on its main page (which is +projects list page), etc. + +$site_name:: + Name of your site or organization to appear in page titles. Set it + to something descriptive for clearer bookmarks etc. If not set (if + empty) then gitweb uses value of `SERVER_NAME` CGI environment + variable setting prefix of each page title to "$SERVER_NAME Git", or + "Untitled Git" if this variable is not set (e.g. if running gitweb + as standalone script). ++ +Can be set using `GITWEB_SITENAME` during building. [No default] + +$site_header:: + Filename of html text to include at top of each page. Relative to + 'gitweb.cgi' script. Can be set using `GITWEB_SITE_HEADER` during + building. [No default] + +$site_footer:: + Filename of html text to include at bottom of each page. Relative to + gitweb.cgi script. Can be set using `GITWEB_SITE_FOOTER` during + building. [No default] + +$home_text:: + Points to an HTML file which, if it exists, is included on the + gitweb projects overview page ("projects_list" view). Relative to + gitweb.cgi script. Default value can be adjusted using during build + via `GITWEB_HOMETEXT` variable. + [Default: 'indextext.html'] + +$projects_list_description_width:: + The width (in characters) of the projects list "Description" column. + Longer descriptions will be cut (trying to cut at word boundary); + full description is available as 'title' attribute (usually shown on + mouseover). By default set to 25, which might be too small if you + use long project descriptions. + +$default_projects_order:: + Default value of ordering of projects on projects list page. Valid + values are "none" (unsorted), "project" (by project name, i.e. path + to repository relative to `$projectroot`), "descr" (project + description), "owner", and "age" (by date of most current commit). ++ +Default value is "project". Unknown value means unsorted. + + +Changing gitweb behavior +~~~~~~~~~~~~~~~~~~~~~~~~ +Those configuration variables control _internal_ gitweb behavior. + +$default_blob_plain_mimetype:: + Default mimetype for blob_plain (raw) view, if mimetype checking + doesn't result in some other type; by default "text/plain". + +$default_text_plain_charset:: + Default charset for text files. If not set, web server configuration + would be used. + +$fallback_encoding:: + Gitweb assumes this charset if line contains non-UTF-8 characters. + Fallback decoding is used without error checking, so it can be even + "utf-8". Value must be valid encoding; see *Encoding::Supported*(3pm) + man page for a list. By default "latin1", aka. "iso-8859-1". + +@diff_opts:: + Rename detection options for git-diff and git-diff-tree. By default + (\'-M'); set it to (\'-C') or (\'-C', \'-C') to also detect copies, + or set it to () i.e. empty list if you don't want to have renames + detection. + +Extra features, administrative +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Most of features are configured via `%feature` hash; however some of extra +gitweb features can be turned on and configured using variables described +below. This list beside configuration variables that control how gitweb +looks does contain variables configuring administrative side of gitweb +(e.g. cross-site scripting prevention; admittedly this as side effect +affects how "summary" pages look like, or load limiting). + +@git_base_url_list:: + List of git base URLs used for URL to where fetch project from, shown + in project summary page. Full URL is "`$git_base_url/$project`". You + can setup multiple base URLs (for example one for `git://` protocol + access, and one for `http://` "dumb" protocol access). Note that per + repository configuration can be set in '$GIT_DIR/cloneurl' file, or as + values of multi-value `gitweb.url` configuration variable in project + config. ++ +You can setup one single value (single entry/item in this list) during +building by using `GITWEB_BASE_URL` built-time configuration variable. +[No default] + +$projects_list_group_categories:: + Enables the grouping of projects by category on the project list page. + The category of a project is determined by the `$GIT_DIR/category` file + or the `gitweb.category` variable in its repository configuration. + [Disabled by default]. + +$project_list_default_category:: + Default category for projects for which none is specified. If set to + the empty string, such projects will remain uncategorized and listed at + the top, above categorized projects. Used only if project cateories are + enabled, which means if `$projects_list_group_categories` is true. + [Default: "" (empty string)] + +$prevent_xss:: + If true, some gitweb features are disabled to prevent content in + repositories from launching cross-site scripting (XSS) attacks. Set this + to true if you don't trust the content of your repositories. + [Default: false]. + +$maxload:: + Used to set the maximum load that we will still respond to gitweb queries. + If server load exceed this value then return "503 Service Unavailable" + error. Server load is taken to be 0 if gitweb cannot determine its value. + Set it to undefined value to turn it off. [Default: 300] + +$per_request_config:: + If set to code reference, it would be run once per each request. You can + set parts of configuration that change per session, e.g. by adding + the following code to gitweb configuration file ++ +-------------------------------------------------------------------------------- +our $per_request_config = sub { + $ENV{GL_USER} = $cgi->remote_user || "gitweb"; +}; +-------------------------------------------------------------------------------- ++ +Otherwise it is treated as boolean value: if true gitweb would process +config file once per request, if false it would process config file only +once. [Default: true] ++ +*NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default +values before every request, so if you want to change them, be sure to set +this variable to true or a code reference effecting the desired changes. + + +Other variables +~~~~~~~~~~~~~~~ +Usually you should not need to change (adjust) any of configuration +variables described below; they should be automatically set by gitweb to +correct value. + + +$version:: + Gitweb version, set automatically when creating gitweb.cgi from + gitweb.perl. You might want to modify it if you are running modified + gitweb, for example ++ +--------------------------------------------------- +our $version .= " with caching"; +--------------------------------------------------- + +$my_url:: +$my_uri:: + Full URL and absolute URL of gitweb script; + in earlier versions of gitweb you might have need to set those + variables, now there should be no need to do it. See + `$per_request_config` if you need to set them still. + +$base_url:: + Base URL for relative URLs in pages generated by gitweb, + (e.g. `$logo`, `$favicon`, `@stylesheets` if they are relative URLs), + needed and used only for URLs with nonempty PATH_INFO via + '<base href="$base_url">'. Usually gitweb sets its value correctly, + and there is no need to set this variable, e.g. to $my_uri or "/". + See `$per_request_config` if you need to set it anyway. + + +CONFIGURING GITWEB FEATURES +--------------------------- +Many gitweb features can be enabled (or disabled) and configured using the +`%feature` hash. Names of gitweb features are keys of this hash. + +Each `%feature` hash element is a hash reference and has the following +structure: +---------------------------------------------------------------------- +"<feature_name>" => { + "sub" => <feature-sub (subroutine)>, + "override" => <allow-override (boolean)>, + "default" => [ <options>... ] +}, +---------------------------------------------------------------------- +Some of features does not support project specific override. For those +features the structure of appropriate `%feature` hash element has a simpler +form: +---------------------------------------------------------------------- +"<feature_name>" => { + "override" => 0, + "default" => [ <options>... ] +}, +---------------------------------------------------------------------- +As one can see it lacks \'sub' element. + +The meaning of respective parts of feature configuration are described +below: + +default:: + List (array reference) of feature parameters (if there are any), + used also to toggle (enable or disable) given feature. ++ +Note that it is currently *always* an array reference, even if +feature doesn't accept any configuration parameters, and \'default' +is used only to turn it on or off. In such case you turn feature on +by setting this element to `[1]`, and torn it off by setting it to +`[0]`. See also part about "blame" feature in the "Examples" +section. ++ +To disable feature that accepts parameters (is configurable), you +need to set this element to empty list i.e. `[]`. + +override:: + If it has a true value then given feature is overridable, which + means that it can be configured (or enabled/disabled) on + per-repository basis. ++ +Usually given "<feature>" is configurable via `gitweb.<feature>` +config variable in per-repository git configuration file. ++ +*Note* that no feature is overridable by default. + +sub:: + Subroutine that will be called with default options as parameters to + examine per-repository configuration, but only if feature is + overridable (\'override' is set to true). If not present then + per-repository override for given feature is not supported. ++ +You wouldn't need to ever change it in gitweb config file. + + +Features in `%feature` +~~~~~~~~~~~~~~~~~~~~~~ +Below there are described gitweb features that are configurable via +`%feature` hash. For a complete list please consult gitweb sources. + +blame:: + Enable the "blame" and "blame_incremental" blob views, showing for + each line the last commit that modified it; see linkgit:git-blame[1]. + This can be very CPU-intensive and is therefore disabled by default. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.blame` configuration variable (boolean). + +snapshot:: + Enable and configure "snapshot" action, providing a compressed + archive of any tree or commit; see also linkgit:git-archive[1]. + This can potentally generate high traffic if you have large project. ++ +The value (of \'default') is a list of names of snapshot formats +defined in `%known_snapshot_formats` hash, that you wish to offer. +Among supported formats are "tgz", "tbz2", "txz" (gzip/bzip2/xz +compressed tar archive) and "zip"; please consult gitweb sources for +a definitive list. By default only "tgz" is offered. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.blame` configuration variable, which contains +a comma separated list of formats, or "none" to disable snapshots. +Unknown values will be ignored. + +grep:: + Enable grep search, which will list the files in currently selected + tree (directory) containing the given string; see linkgit:git-grep[1]. + This can be potentially CPU-intensive, of course. Enabled by default. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.grep` configuration variable (boolean). + +pickaxe:: + Enable the so called pickaxe search, which will list the commits + that modified a given string in a file. This can be practical and + quite faster alternative to "blame" action, but still potentially + CPU-intensive. Enabled by default. ++ +The pickaxe search is described in linkgit:git-log[1] (the +description of `-S<string>` option, which refers to pickaxe entry in +linkgit:gitdiffcore[7] for more details). ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.pickaxe` configuration variable (boolean). + +show-sizes:: + Enable showing size of blobs (ordinary files) in a "tree" view, in a + separate column, similar to what `ls -l` does; see description of + `-l` option in linkgit:git-ls-tree[1] manpage. This cost a bit of + I/O. Enabled by default. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.showsizes` configuration variable (boolean). + +patches:: + Configure "patches" view, which displays list of commits in email + (plain text) output format; see also linkgit:git-format-patch[1]. + The value is the maximum number of patches in a patchset generated + in "patches" view. Set this to 0 or undef to disable patch view, or + to a negative number to remove any limit. Default value is 16. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.patches` configuration variable (integer). + +avatar:: + Avatar support. When this feature is enabled, views such as + "shortlog" or "commit" will display an avatar associated with + the email of the committer(s) and/or author(s). ++ +Currently available providers are *"gravatar"* and *"picon"*. +If an unknown provider is specified, the feature is disabled. +*Note* that some provides might require extra Perl packages to be +installed; see 'gitweb/INSTALL' for more details. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.avatar` configuration variable. ++ +See also `%avatar_size` with pixel sizes for icons and avatars +("default" is used for one-line like "log" and "shortlog", "double" +is used for two-line like "commit", "commitdiff" or "tag"). If the +default font sizes or lineheights are changed (e.g. via adding extra +CSS stylesheet in `@stylesheets`), it may be appropriate to change +these values. + +highlight:: + Server-side syntax hightlight support in "blob" view. It requires + `$highlight_bin` program available (see description of this variable + in "Configuration variables" section above), and therefore is + disabled by default. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.highlight` configuration variable (boolean). + +remote_heads:: + Enable displaying remote heads (remote-tracking branches) in the "heads" + list. In most cases it is unnecessary internal private detail, and it + is therefore disabled by default. linkgit:git-instaweb[1], which is + usually used to browse local repositories, enables and uses this + feature. ++ +This feature can be configured on a per-repository basis via +repository's `gitweb.remote_heads` configuration variable (boolean). + + +The list below presents features that do not allow project specific +overrides. + +search:: + Enable text search, which will list the commits which match author, + committer or commit text to a given string; see description of + `--author`, `--committer` and `--grep` options in linkgit:git-log[1] + manpage. Enabled by default. ++ +Project specific override is not supported. + +forks:: + Make gitweb consider projects in subdirectories of project root + (basename) to be forks of existing projects. Given project + `$projname.git`, projects matching `$projname/*.git` will not be + shown in the main projects list, instead a \'+' mark will be added + to `$projname` there and a "forks" view will be enabled for the + project, listing all the forks. If project list is taken from a + file, forks have to be listed after the main project. ++ +Project specific override is not supported. + +actions:: + Insert custom links to the action bar of all project pages. This + enables you to link to third-party scripts integrating into gitweb. ++ +The "default" value consists of a list of triplets in the form +`("<label>", "<link>", "<position>")` where "position" is the label +after which to insert the link, "link" is a format string where `%n` +expands to the project name, `%f` to the project path within the +filesystem, `%h` to the current hash (\'h' gitweb parameter) and +`%b` to the current hash base (\'hb' gitweb parameter); `%%` expands +to \'%'. ++ +For example http://repo.or.cz git hosting site sets it to the +following to enable graphical log (via third party tool +*git-browser*): ++ +---------------------------------------------------------------------- +$feature{'actions'}{'default'} = + [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')]; +---------------------------------------------------------------------- ++ +This adds link titled "graphiclog" after "summary" link, leading to +`git-browser` script, passing `r=<project>` as a query parameter. ++ +Project specific override is not supported. + +timed:: + Enable displaying how much time and how many git commands it took to + generate and display page in the page footer (at the bottom of + page). For example it might be: "This page took 6.53325 seconds and + 13 git commands to generate." Disabled by default. ++ +Project specific override is not supported. + +javascript-timezone:: + Enable and configure ability to change common timezone for dates in + gitweb output via JavaScript. Dates in gitweb output include + authordate and comitterdate in "commit", "commitdiff" and "log" + views, and taggerdate in "tag" view. Enabled by default. ++ +Value is list of three values: default timezone (if client didn't +select other timezone and saved it in a cookie), name of cookie +where to store selected timezone, and CSS class used to mark up +dates for manipulation. If you want to turn it off, set "default" +to empty list: `[]`. ++ +In most case you would want to change only default timezone: ++ +--------------------------------------------------------------------------- +$feature{'javascript-timezone'}{'default'}[0] = "utc"; +--------------------------------------------------------------------------- ++ +Timezone value can be "local" (for local timezone that browser uses), "utc" +(what gitweb uses when JavaScript or this feature is disabled), or numerical +timezone in the form of "+/-HHMM" for example "+0200". This way is +guaranteed to be backward compatibile. ++ +Project specific override is not supported. + + +EXAMPLES +-------- + +To enable blame, pickaxe search, and snapshot support (allowing "tar.gz" and +"zip" snapshots), while allowing individual projects to turn them off, put +the following in your GITWEB_CONFIG file: + + $feature{'blame'}{'default'} = [1]; + $feature{'blame'}{'override'} = 1; + + $feature{'pickaxe'}{'default'} = [1]; + $feature{'pickaxe'}{'override'} = 1; + + $feature{'snapshot'}{'default'} = ['zip', 'tgz']; + $feature{'snapshot'}{'override'} = 1; + +If you allow overriding for the snapshot feature, you can specify which +snapshot formats are globally disabled. You can also add any command line +options you want (such as setting the compression level). For instance, you +can disable Zip compressed snapshots and set *gzip*(1) to run at level 6 by +adding the following lines to your gitweb configuration file: + + $known_snapshot_formats{'zip'}{'disabled'} = 1; + $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6']; + +ENVIRONMENT +----------- +The location of per-instance and system-wide configuration files can be set +using the following environment variables: + +GITWEB_CONFIG:: + Sets location of per-instance configuration file. +GITWEB_CONFIG_SYSTEM:: + Sets location of fallback system-wide configuration file. + This file is read only if per-instance one does not exist. +GITWEB_CONFIG_COMMON:: + Sets location of common system-wide configuration file. + + +FILES +----- +gitweb_config.perl:: + This is default value for per-instance configuration file. The + format of this file is described above. +/etc/gitweb.conf:: + This is default value for fallback system-wide configuration + file. This file is used only if per-instance configuration + variable is not found. +/etc/gitweb-common.conf:: + This is default value for common system-wide configuration + file. + + +SEE ALSO +-------- +linkgit:gitweb[1], linkgit:git-instaweb[1] + +'gitweb/README', 'gitweb/INSTALL' + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/gitweb/README b/gitweb/README index a998820..cf528d3 100644 --- a/gitweb/README +++ b/gitweb/README @@ -41,139 +41,8 @@ Ultimate description on how to reconfigure the default features setting in your `GITWEB_CONFIG` or per-project in `project.git/config` can be found as comments inside 'gitweb.cgi'. -See also the "Gitweb config file" (with an example of config file), and -the "Gitweb repositories" sections in INSTALL file for gitweb. - - -The gitweb config file is a fragment of perl code. You can set variables -using "our $variable = value"; text from "#" character until the end -of a line is ignored. See perlsyn(1) man page for details. - -Below is the list of variables which you might want to set in gitweb config. -See the top of 'gitweb.cgi' for the full list of variables and their -descriptions. - -Gitweb config file variables -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can set, among others, the following variables in gitweb config files -(with the exception of $projectroot and $projects_list this list does -not include variables usually directly set during build): - * $GIT - Core git executable to use. By default set to "$GIT_BINDIR/git", which - in turn is by default set to "$(bindir)/git". If you use git from binary - package, set this to "/usr/bin/git". This can just be "git" if your - webserver has a sensible PATH. If you have multiple git versions - installed it can be used to choose which one to use. - * $version - Gitweb version, set automatically when creating gitweb.cgi from - gitweb.perl. You might want to modify it if you are running modified - gitweb. - * $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 have to be - set correctly for gitweb to find 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 - <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. - * $my_url, $my_uri - Full URL and absolute URL of gitweb script; - in earlier versions of gitweb you might have need to set those - variables, now there should be no need to do it. See - $per_request_config if you need to set them still. - * $base_url - Base URL for relative URLs in pages generated by gitweb, - (e.g. $logo, $favicon, @stylesheets if they are relative URLs), - needed and used only for URLs with nonempty PATH_INFO via - <base href="$base_url">. Usually gitweb sets its value correctly, - and there is no need to set this variable, e.g. to $my_uri or "/". - See $per_request_config if you need to set it anyway. - * $home_link - Target of the home link on top of all pages (the first part of view - "breadcrumbs"). By default set to absolute URI of a page ($my_uri). - * @stylesheets - List of URIs of stylesheets (relative to base URI of a page). You - might specify more than one stylesheet, for example use gitweb.css - as base, with site specific modifications in separate stylesheet - to make it easier to upgrade gitweb. You can add 'site' stylesheet - for example by using - push @stylesheets, "gitweb-site.css"; - in the gitweb config file. - * $logo_url, $logo_label - URI and label (title) of GIT logo link (or your site logo, if you choose - to use different logo image). By default they point to git homepage; - in the past they pointed to git documentation at www.kernel.org. - * $projects_list_description_width - The width (in characters) of the projects list "Description" column. - Longer descriptions will be cut (trying to cut at word boundary); - full description is available as 'title' attribute (usually shown on - mouseover). By default set to 25, which might be too small if you - use long project descriptions. - * $projects_list_group_categories - Enables the grouping of projects by category on the project list page. - The category of a project is determined by the $GIT_DIR/category - file or the 'gitweb.category' variable in its repository configuration. - Disabled by default. - * $project_list_default_category - Default category for projects for which none is specified. If set - to the empty string, such projects will remain uncategorized and - listed at the top, above categorized projects. - * @git_base_url_list - List of git base URLs used for URL to where fetch project from, shown - in project summary page. Full URL is "$git_base_url/$project". - You can setup multiple base URLs (for example one for git:// protocol - access, and one for http:// "dumb" protocol access). Note that per - repository configuration in 'cloneurl' file, or as values of gitweb.url - project config. - * $default_blob_plain_mimetype - Default mimetype for blob_plain (raw) view, if mimetype checking - doesn't result in some other type; by default 'text/plain'. - * $default_text_plain_charset - Default charset for text files. If not set, web server configuration - would be used. - * $mimetypes_file - File to use for (filename extension based) guessing of MIME types before - trying /etc/mime.types. Path, if relative, is taken currently as - relative to the current git repository. - * $fallback_encoding - Gitweb assumes this charset if line contains non-UTF-8 characters. - Fallback decoding is used without error checking, so it can be even - 'utf-8'. Value must be valid encoding; see Encoding::Supported(3pm) man - page for a list. By default 'latin1', aka. 'iso-8859-1'. - * @diff_opts - Rename detection options for git-diff and git-diff-tree. By default - ('-M'); set it to ('-C') or ('-C', '-C') to also detect copies, or - set it to () if you don't want to have renames detection. - * $prevent_xss - If true, some gitweb features are disabled to prevent content in - repositories from launching cross-site scripting (XSS) attacks. Set this - to true if you don't trust the content of your repositories. The default - is false. - * $maxload - Used to set the maximum load that we will still respond to gitweb queries. - If server load exceed this value then return "503 Service Unavailable" error. - Server load is taken to be 0 if gitweb cannot determine its value. Set it to - undefined value to turn it off. The default is 300. - * $highlight_bin - Path to the highlight executable to use (must be the one from - http://www.andre-simon.de due to assumptions about parameters and output). - Useful if highlight is not installed on your webserver's PATH. - [Default: highlight] - * $per_request_config - If set to code reference, it would be run once per each request. You can - set parts of configuration that change per session, e.g. by setting it to - sub { $ENV{GL_USER} = $cgi->remote_user || "gitweb"; } - Otherwise it is treated as boolean value: if true gitweb would process - config file once per request, if false it would process config file only - once. Note: $my_url, $my_uri, and $base_url are overwritten with - their default values before every request, so if you want to change - them, be sure to set this variable to true or a code reference effecting - the desired changes. The default is true. +See also gitweb.conf(5) manpage. + Projects list file format ~~~~~~~~~~~~~~~~~~~~~~~~~ -- 1.7.6 ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: [PATCH/RFCv4 2/4] gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation) 2011-09-18 13:34 ` [PATCH/RFCv4 2/4] gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation) Jakub Narebski @ 2011-09-20 4:41 ` Jonathan Nieder 2011-09-22 13:41 ` Jakub Narebski 0 siblings, 1 reply; 12+ messages in thread From: Jonathan Nieder @ 2011-09-20 4:41 UTC (permalink / raw) To: Jakub Narebski; +Cc: git, Drew Northup, John 'Warthog9' Hawley, admin Jakub Narebski wrote: > [jn: Improved, extended, removed duplicate info from README] Hoorah! I have very little to add to what's already been done --- mostly I can just lend my ear as a native English speaker. [...] > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -3,7 +3,7 @@ MAN1_TXT= \ > $(wildcard git-*.txt)) \ > gitk.txt git.txt > MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \ > - gitrepository-layout.txt > + gitrepository-layout.txt gitweb.conf.txt I take back what I wrote about patch 1. Maybe its commit message could be clarified to mention that the new targets build a subset of the pages built by the ordinary "make doc" et al targets. [...] > +++ b/Documentation/gitweb.conf.txt > @@ -0,0 +1,781 @@ [...] > +The configuration file is used to override the default settings that > +were built into gitweb at the time 'gitweb.cgi' script was generated. > + > +While one could just alter the configuration settings in the gitweb > +CGI itself, those changes would be lost upon upgrade. Configuration > +settings might 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. This reads nicely now. Language nit: missing "the" before "'gitweb.cgi' script". [...] > +DISCUSSION > +---------- > +Gitweb obtains configuration data from the following sources in the > +following order: > + > + * built-in values (some set during build stage), > + > + * common system-wide configuration file (defaults to > + '/etc/gitweb-common.conf'), > + > + * either per-instance configuration file (defaults to 'gitweb_config.perl' > + in the same directory as the installed gitweb), or if it does not exists > + then system-wide configuration file (defaults to '/etc/gitweb.conf'). Usage nit: in the first sentence, "reads" would be more natural than "obtains". In the third item, I'd suggest the phrase "the fallback system-wide configuration file" to emphasize how it differs from gitweb-common.conf. > + > +Values obtained in later configuration files override values obtained earlier > +in above sequence. Language nit: missing "the" before "above sequence". > + > +The location of common system-wide configuration file, of fallback system-wide > +configuration file and of per-instance configuration file is defined at compile > +time using the build-time Makefile configuration variables, respectively > +`GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG`. Language nits: missing "the" before "common system-wide configuration file", "fallback system-wide configuration file", and "per-instance configuration files". The subject ("The location") and verb should be plural because we are talking about multiple locations. Would sound a bit more natural in English (unlike French) if the preposition "of" were used once instead of repeated. Another language nit: it sounds a little better without the "the" before "build-time Makefile configuration variables", like so: ... are defined at compile time using build-time Makefile variables, namely `GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM`, and `GITWEB_CONFIG`. > + > +You can override location of gitweb configuration files during runtime > +by setting respective environment variables: `GITWEB_CONFIG_COMMON`, > +`GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG` to non-empty value. Language nit: missing "the" before "location" and "gitweb configuration files". "location" should probably be plural. In place of "respective", "the following" sounds a little more natural. Might be nice to add an "also" after 'can' to emphasize the relationship to the previous paragraph --- in addition to being able to override the default locations at compile time, you can override them at run time by setting environment variables. > + > + > +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` qualifier in `our $variable = <value>;` is a safety > +check: if newer gitweb does no longer use given variable, by using `our` we > +won't get syntax errors. Language nit: for "indeed", something like "internally" might be more natural. The syntax and the typical idiom were already described in the DESCRIPTION section, so the emphasis should be somehow different here to avoid boring the reader. One way might be to plunge directly into what the second paragraph above says: The syntax of the configuration files is that of Perl, since these files are handled by sourcing them as fragments of Perl code (the language that gitweb itself is written in). Variables are typically set using the `our` qualifier (as in "`our $variable = <value>;`") to avoid syntax errors if a new version of gitweb no longer uses a variable and therefore stops declaring it. > + > +You can include other configuration file using read_config_file() > +subroutine. For example, you can read defaults in fallback > +system-wide GITWEB_CONFIG_SYSTEM from GITWEB_CONFIG by adding > + > + read_config_file($GITWEB_CONFIG_SYSTEM); > + > +at very beginning of per-instance GITWEB_CONFIG file. In this case > +settings in said per-instance file will override settings from > +system-wide configuration file. Note that read_config_file checks > +itself that the file it reads exists. Language nits: missing "the" before "fallback systemwide $GITWEB_CONFIG_SYSTEM file" and "very beginning"; missing "a" before "per-instance $GITWEB_CONFIG file"; "case" should perhaps be "example" and followed by a comma. The reader wonders: After checking that the file exists, what does read_config_file do (does it silently skip it or error out)? And why would I use this trick instead of just writing a gitweb-common.conf file? (Was read_config_file introduced before gitweb-common.conf, making this useful when creating a configuration that should be usable with older versions of gitweb?) [...] > +CONFIGURATION VARIABLES > +----------------------- > +Some of configuration variables have their default values (embedded in CGI > +file) set during building gitweb -- if that is the case, it is put in their > +description. See gitweb's 'INSTALL' file for instructions on building and > +installing gitweb. Language nit: "Some of configuration variables" should be "Some configuration variables"; missing "the" before "CGI script"; "it is" should be "they are" to agree with 'variables'. > + > + > +Location of repositories > +~~~~~~~~~~~~~~~~~~~~~~~~ > +Configuration variables described below control finding git repositories by > +gitweb, and control display and access to repositories. Language nits: missing "The" before "Configuration variables described below"; "finding git repositories by gitweb" sounds more natural when paraphrased as "how gitweb finds git repositories" and "display and access to repositories" paraphrased as "how repositories are displayed and accessed"; it seems that the sentence scans a little better when not repeating the verb "control". [...] > +For example if `$projectroot` is set to "/srv/git" by putting the following > +in gitweb config file: > ++ > +---------------------------------------------------------------------------- > +our $projectroot = "/srv/git"; > +---------------------------------------------------------------------------- > ++ > +then > ++ > +------------------------------------------------ > +http://git.example.com/gitweb.cgi?p=foo/bar.git > +------------------------------------------------ > ++ > +or its path_info based equivalent > ++ > +------------------------------------------------ > +http://git.example.com/gitweb.cgi/foo/bar.git > +------------------------------------------------ > ++ > +will map to path '/srv/git/foo/bar.git' on filesystem. Language nits: missing comma after "For example"; "or" should be "and"; missing "the" before "path '/srv/git/foo/bar.git'" and "filesystem". > + > +$project_maxdepth:: > + Filesystem traversing depth limit for recursively scanning for git > + repositories, used if `$projects_list` (below) is unset. The default > + value of this variable is determined by build-time configuration > + variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to 2007. "Filesystem traversing depth limit" is quite a long stack of nouns :), and unfortunately I don't know what it means. Is this the depth of nested subdirectories below $project_root that gitweb will look at when discovering repositories? If I have no subdirectories in the projectroot except the repositories themselves, should I set this to 1 or 0? What happens with forks? Is this just a convenience feature or can it be used for security or to create performance gaurantees? By the way, what happens if projectroot contains a symlink to some directory elsewhere in the filesystem containing repositories --- will gitweb traverse it? What if I want this to be infinite (i.e., to disable the feature) --- would I be crazy? Language nit: missing "the" before "`GITWEB_PROJECT_MAXDEPTH` Makefile variable used at build time, which defaults to 2007". > + > +$projects_list:: > + Plain text file listing projects or name of directory > + to be scanned for projects. > ++ > +Project list files should list one project per line, with each line > +having the following format > ++ > +----------------------------------------------------------------------------- > +<URI-encoded filesystem path to repository> SP <URI-encoded repository owner> > +----------------------------------------------------------------------------- > ++ > +The default value of this variable is determined by the `GITWEB_LIST` > +makefile variable at installation time. If this variable is empty, gitweb > +will fall back to scanning the `$projectroot` directory for repositories. Language nit: missing "Path to a" or "Name of a" before "Plain text file". When this is a relative path, what is it taken relative to? > + > +$export_ok:: > + Show repository only if this file exists (in repository). Only > + effective if this variable evaluates to true. Can be set during > + building gitweb via `GITWEB_EXPORT_OK`. [No default / Not set] This is always a relative path, right? What is it relative to --- $GIT_DIR, I guess? Usage nits: the phrase starting with "during" reads more naturally if "during" is replaced with "when" and "via" replaced with "by setting". If there were no default, that would mean that gitweb errors out when gitweb.conf does not set this variable; instead, the default seems to be "undef" (or 'false') if I understand correctly. > + > +$export_auth_hook:: > + Show repository only if this subroutine returns true, when given as > + the only parameter the full path to the project. Example: > ++ > +---------------------------------------------------------------------------- > +our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; }; > +---------------------------------------------------------------------------- > ++ > +though the above might be done by using `$export_ok` instead > ++ > +---------------------------------------------------------------------------- > +our $export_ok = "git-daemon-export-ok"; > +---------------------------------------------------------------------------- Style nit: commands in this kind of documentation should be directed to the reader, not gitweb, so it would be nicer to explain this in terms of what the $export_auth_hook is. That is, something like the following: $export_auth_hook:: Function used to determine which repositories should be shown. This subroutine should take one parameter, the full path to a project, and if it returns true, that project will be included in the projects list and can be accessed through gitweb as long as it fulfills the other requirements described by $export_ok, $projects_list, and $projects_maxdepth. Example: Is "our $export_auth_hook = undef;" a valid configuration? What is the default? > + > +$strict_export:: > + Only allow viewing of repositories also shown on the overview page. > + This for example makes `$gitweb_export_ok` file decide if repository is > + available and not only if it is shown. If `$gitweb_list` points to > + file with list of project, only those repositories listed would be > + available for gitweb. Can be set during building gitweb via > + `GITWEB_STRICT_EXPORT`. [No default / Not set] Is the default behavior as though this were true or false? > +Finding files > +~~~~~~~~~~~~~ > +Those configuration variables tell gitweb where to find files. Values of > +those variables are paths on filesystem. Of those only `$GIT` is required > +to be (correctly) set for gitweb to be able to work; all the rest are > +required only for extra configuration or extra features. Language nit: "Those" should be "The following" in the first sentence and "these" in remaining sentences; missing "The" before "Values of those variables" and "filesystem"; missing comma after "Of these". When you say the remainder are only required in special cases, does that mean that they are ignored unless some other enabling variable is set or that they can be set to "undef" to disable the relevant feature? > + > +$GIT:: > + Core git executable to use. By default set to `$GIT_BINDIR/git`, which > + in turn is by default set to `$(bindir)/git`. If you use git from binary > + package, set this to "/usr/bin/git". This can just be "git" if your > + webserver has a sensible PATH. If you have multiple git versions installed > + it can be used to choose which one to use. Language nit: missing "a" or "your operating system distributor's" before "binary package". > + > +$mimetypes_file:: > + File to use for (filename extension based) guessing of MIME types before > + trying '/etc/mime.types'. Path, if relative, is taken currently as > + relative to the current git repository. [Unset by default] Language nit: missing "The" before "Path". The use of "currently" sounds like an apology. Does that mean that gitweb ought to be rejecting relative paths for this variable? > + > +$highlight_bin:: > + Path to the highlight executable to use (must be the one from > + http://www.andre-simon.de due to assumptions about parameters and output). > + Useful if 'highlight' is not installed on your webserver's PATH. > + [Default: 'highlight'] > ++ > +*NOTE*: if you want to add support for new syntax (supported by > +"highlight" but not used by gitweb), you need to modify `%highlight_ext` > +or `%highlight_basename`, depending on whether you detect type of file > +based on extension (for example "*.sh") or on its basename (for example > +"Makefile"). Keys of those hashes are extension or basename, > +respectively, and value for given key is name of syntax to be passed via > +`--syntax <syntax>` to highlighter. Language nits: missing "it" before "must be the one"; "new syntax" should probably be "a new file type" or something like that; missing "The" before "Keys of those hashes"; "those" should be "these"; "or" should be "and". Is "*.sh" actually an example of an extension? I.e., do I write the following? our %highlight_ext; $highlight_ext{"*.sh"} = "sh"; > + > + > +Links and their targets > +~~~~~~~~~~~~~~~~~~~~~~~ > +Configuration variables described below configure some of gitweb links: > +their target and their look (text or image), and where to find page > +prerequisites (stylesheet, favicon, images, scripts). Usually they are left > +at their default values, with the possible exception of `@stylesheets` > +variable. Language nits: missing "The" before "Configuration variables described below"; missing "some" before "supporting files". > + > +@stylesheets:: > + List of URIs of stylesheets (relative to base URI of a page). You > + might specify more than one stylesheet, for example use gitweb.css > + as base, with site specific modifications in separate stylesheet > + to make it easier to upgrade gitweb. You can add a `site` stylesheet > + for example by putting > ++ > +---------------------------------------------------------------------------- > +push @stylesheets, "gitweb-site.css"; > +---------------------------------------------------------------------------- > ++ > +in the gitweb config file. Those values that are relative paths, are > +relative to base URI of gitweb. Language nits: missing "the" before "base URI". What is a base URI --- is it set by another variable? Missing "to" before "use gitweb.css as a base"; there should not be a comma before "with site-specific modifications" or before "are relative"; missing "a" before "separate stylesheet"; missing commas surrounding "for example" (or even better, "For example," could move to the start of the sentence). > ++ > +This list should contain URI of gitweb's stylesheet. The URI of gitweb > +stylesheet is set during build time via `GITWEB_CSS` variable. It's default > +value is 'static/gitweb.css' (or 'static/gitweb.min.css' if the `CSSMIN` > +variable is defined, i.e. if CSS minifier is used during build). > ++ > +*Note*: there is also legacy `$stylesheet` configuration variable, which was > +used by older gitweb. Language nits: missing "the" before "URI of gitweb's standard stylesheet"; missing "default" before "URI of the gitweb stylesheet"; "is set during" should be "can be set at"; "via `GITWEB_CSS` variable" should be "using the `GITWEB_CSS` makefile variable"; extra apostrophe in "It's"; missing "a" before "legacy `$stylesheet` configuration variable". If I am new on the job and find the $stylesheet variable set, what should I interpret it to mean? How can it be translated to the newer @stylesheets style? What happens if both variables are set --- does one override the other, or are they combined somehow? > + > +$logo:: > + Points to the location where you put 'git-logo.png' on your web > + server, or to be more generic URI of logo, 72x27 size). This image > + is displayed in top right corner of each gitweb page, and used as > + logo for Atom feed. Relative to base URI of gitweb (as a path). > + Can be adjusted during building gitweb using `GITWEB_LOGO` variable > + [Default: 'static/git-logo.png'] Language nits: missing "the" before "generic URI", "top-right corner", "Atom feed", and "base URI of gitweb"; missing "a" before "logo"; there should not be a comma before "and used"; "during" sounds more natural when it is replaced with "when". > + > +$favicon:: > + Points to the location where you put 'git-favicon.png' on your web > + server, or to be more generic URI of favicon, assumed to be > + "image/png" type; web browsers that support favicons (website icons) > + may display them in the browser's URL bar and next to site name in > + bookmarks. Relative to base URI of gitweb. Can be adjusted during > + build time using `GITWEB_FAVICON` variable. > + [Default: 'static/git-favicon.png'] Language nits: missing "the" before "generic URI", "site name", and "base URI"; missing "your chosen" before "favicon"; "assumed to be" should be "which will be served as" or something like that; would be easier to read with the semicolon before "web browsers" replaced by a full stop; "may" should be "will"; "during" sounds more natural when it is replaced with "at". > + > +$javascript:: > + Points to the location where you put 'gitweb.js' on your web server, > + or to be more generic URI of JavaScript code used by gitweb. > + Relative to base URI of gitweb. Set during build time using > + `GITWEB_JS` build-time configuration variable. > ++ > +Default value is either 'static/gitweb.js', or 'static/gitweb.min.js' if > +`JSMIN` build variable is defined, i.e. if JavaScript minifier is used > +during build. *Note* that this single file is build (composed) of > +individual JavaScript "modules". Language nits: missing "the" before "URI", "Javascript library", "base URI", "`GITWEB_JS`" makefile variable", "Default value", and "`JSMIN` makefile variable"; "Set during" sounds more natural when it is replaced by "Can be set at"; "is defined" and "is used" should be "was defined" and "was used" to reflect installation probably already having occured; "during build" sounds more natural when it is replaced by "at build time"; "build of" should be "built from" or "generated from multiple". > + > +$home_link:: > + Target of the home link on top of all pages (the first part of view > + "breadcrumbs"). By default set to absolute URI of a page ($my_uri). Language nit: missing "the" before "top" and "absolute URI". Which page does "a page" refer to here (doesn't $my_uri change from request to request)? > + > +$home_link_str:: > + Description of the home link on top of all pages, leading to $home_link > + (usually main gitweb page, which means projects list). Used as first > + part of gitweb view "breadcrumb trail": `<home> / <project> / <view>`. > + Can be set during build time using `GITWEB_HOME_LINK_STR` variable. > + [Default: "projects"] Language nits: "Description of" means "Label for", I suppose; "home link" should be "home page link" (?); "on top" is "at the top"; missing "the" before "main gitweb page"; "which means projects list" is more friendly if paraphrased as "which contains the projects list"; "part of gitweb view" could be paraphrased as "component of gitweb's"; "during" sounds more natural if replaced by "at"; missing "the" before "`GITWEB_HOME_LINK_STR` makefile variable". > + > +$logo_url:: > +$logo_label:: > + URI and label (title) of GIT logo link (or your site logo, if you choose > + to use different logo image). By default they point to git homepage; > + in the past they pointed to git documentation at www.kernel.org. Language nits: "of GIT logo link" should probably be "for the Git logo link"; "choose" should be "chose" since that's in the past when the admin is setting this variable; missing comma after "By default" and "in the past"; the first "they" should be "these both". > + > + > +Changing gitweb look > +~~~~~~~~~~~~~~~~~~~~ > +You can adjust how pages generated by gitweb look using variables described > +below. You can change site name, add common headers and footers for all > +pages, and add description of gitweb installation on its main page (which is > +projects list page), etc. Language nits: missing "'s" in "Changing gitweb's look"; missing "the" before "variables described below", "site name", and "project list page"; missing "a" before "description"; missing "this" before "gitweb installation". > + > +$site_name:: > + Name of your site or organization to appear in page titles. Set it > + to something descriptive for clearer bookmarks etc. If not set (if > + empty) then gitweb uses value of `SERVER_NAME` CGI environment > + variable setting prefix of each page title to "$SERVER_NAME Git", or > + "Untitled Git" if this variable is not set (e.g. if running gitweb > + as standalone script). > ++ > +Can be set using `GITWEB_SITENAME` during building. [No default] Language nits: missing comma after "organization" and before "for use in page titles"; missing "the" before "the value", "`SERVER_NAME` environment variable", and "`GITWEB_SITENAME` makefile variable"; "If not set" is missing a subject --- "If this variable is unset or empty, then gitweb will ..."; "during building" sounds more natural when replaced by "at build time". > + > +$site_header:: > + Filename of html text to include at top of each page. Relative to > + 'gitweb.cgi' script. Can be set using `GITWEB_SITE_HEADER` during > + building. [No default] Language nits: "Filename of html text to include" should be "Name of a file with HTML to be included" (or "Path to ..."); "'gitweb.cgi' script" should be "the directory containing the 'gitweb.cgi' script"; "during building" sounds more natural when replaced by "at build time". > + > +$site_footer:: > + Filename of html text to include at bottom of each page. Relative to > + gitweb.cgi script. Can be set using `GITWEB_SITE_FOOTER` during > + building. [No default] Likewise. > + > +$home_text:: > + Points to an HTML file which, if it exists, is included on the > + gitweb projects overview page ("projects_list" view). Relative to > + gitweb.cgi script. Default value can be adjusted using during build > + via `GITWEB_HOMETEXT` variable. > + [Default: 'indextext.html'] Likewise. > + > +$projects_list_description_width:: > + The width (in characters) of the projects list "Description" column. > + Longer descriptions will be cut (trying to cut at word boundary); > + full description is available as 'title' attribute (usually shown on > + mouseover). By default set to 25, which might be too small if you > + use long project descriptions. Language nit: 'project list "Description" column' sounds more natural when rearranged to 'the "Description" column of the project list'; "cut" should be "truncated"; missing "the" before "full description"; "as 'title' attribute" sounds better as "in the 'title' attribute"; instead of "By default set to", it is clearer to say "The default is". > + > +$default_projects_order:: > + Default value of ordering of projects on projects list page. Valid > + values are "none" (unsorted), "project" (by project name, i.e. path > + to repository relative to `$projectroot`), "descr" (project > + description), "owner", and "age" (by date of most current commit). > ++ > +Default value is "project". Unknown value means unsorted. What does "Default" mean here (i.e., what overrides it)? > + > + > +Changing gitweb behavior > +~~~~~~~~~~~~~~~~~~~~~~~~ > +Those configuration variables control _internal_ gitweb behavior. Language nits: missing "'s" in "gitweb's behavior"; "Those" should be "These". Does internal behavior mean "functionality as opposed to appearance and input location" or something like that? > + > +$default_blob_plain_mimetype:: > + Default mimetype for blob_plain (raw) view, if mimetype checking > + doesn't result in some other type; by default "text/plain". Language nit: missing "the" before "blob_plain (raw) view". Where can I look to read more about mimetype autodetection? > + > +$default_text_plain_charset:: > + Default charset for text files. If not set, web server configuration > + would be used. Language nits: to make clear that it is not the web server configuration that is not set, "If not set" could be paraphrased to "If this is unset"; "would" should be "will" (yes, conditionals in English are weird); missing "the" before "web server's usual configuration". > + > +$fallback_encoding:: > + Gitweb assumes this charset if line contains non-UTF-8 characters. > + Fallback decoding is used without error checking, so it can be even > + "utf-8". Value must be valid encoding; see *Encoding::Supported*(3pm) > + man page for a list. By default "latin1", aka. "iso-8859-1". Language nits: "if" should be "when"; missing "a" before "line" and "valid encoding"; missing "The" before "Fallback encoding", "Value", and "Encoding::Supported(3pm) manpage"; "By default" sounds a little better as "The default is" or "Default:". > + > +@diff_opts:: > + Rename detection options for git-diff and git-diff-tree. By default > + (\'-M'); set it to (\'-C') or (\'-C', \'-C') to also detect copies, > + or set it to () i.e. empty list if you don't want to have renames > + detection. Language nit: "By default" sounds a little better as "The default is". Probably worth mentioning that GNU patch still has problems with some rename patches, especially when they involve file copies ['-C'] or criss-cross renames ['-B'] (see [1] and [2], for example). [1] http://savannah.gnu.org/bugs/?31058 [2] http://thread.gmane.org/gmane.linux.ports.sh.devel/8697/focus=8773 > + > +Extra features, administrative > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > +Most of features are configured via `%feature` hash; however some of extra > +gitweb features can be turned on and configured using variables described > +below. This list beside configuration variables that control how gitweb > +looks does contain variables configuring administrative side of gitweb > +(e.g. cross-site scripting prevention; admittedly this as side effect > +affects how "summary" pages look like, or load limiting). Language nit: the title sounds like these are going to be extra administrative features --- might be best to spell it out ("Some optional features and policies" or something like that). > + > +@git_base_url_list:: > + List of git base URLs used for URL to where fetch project from, shown > + in project summary page. Full URL is "`$git_base_url/$project`". You > + can setup multiple base URLs (for example one for `git://` protocol > + access, and one for `http://` "dumb" protocol access). Note that per > + repository configuration can be set in '$GIT_DIR/cloneurl' file, or as > + values of multi-value `gitweb.url` configuration variable in project > + config. > ++ > +You can setup one single value (single entry/item in this list) during > +building by using `GITWEB_BASE_URL` built-time configuration variable. > +[No default] Language nits: "git base URLs used for URL to where fetch project from" means something like "Git URLs relative to which projects can be fetched"; missing "The" before and 'for the `"$projectroot/$project"` repository' after "Full URL"; "setup" as a verb is spelled "set up" or "set" (2x); "http://" access is not necessarily passive; "during building" sounds better as "at build time"; "using" should be "setting the"; "built-time configuration variable" is spelled as "build-time configu..." or even better as "makefile variable"; "No default" does not seem quite right --- I think the default is "Default: ()" (i.e., it defaults to the empty list). Is the per repository cloneurl added to this list, or does it override it? > + > +$projects_list_group_categories:: > + Enables the grouping of projects by category on the project list page. > + The category of a project is determined by the `$GIT_DIR/category` file > + or the `gitweb.category` variable in its repository configuration. > + [Disabled by default]. Language nits: "its repository configuration" probably means "each repository's configuration"; "Enables" can be rephrased more clearly as "Whether to enable" (assuming this is boolean). > + > +$project_list_default_category:: > + Default category for projects for which none is specified. If set to > + the empty string, such projects will remain uncategorized and listed at > + the top, above categorized projects. Used only if project cateories are > + enabled, which means if `$projects_list_group_categories` is true. > + [Default: "" (empty string)] Language nit: "If set to the empty string" is clearer as "If this is set to the empty string" since it is not the projects but this variable that is being set to the empty string. > + > +$prevent_xss:: > + If true, some gitweb features are disabled to prevent content in > + repositories from launching cross-site scripting (XSS) attacks. Set this > + to true if you don't trust the content of your repositories. > + [Default: false]. Nice. > + > +$maxload:: > + Used to set the maximum load that we will still respond to gitweb queries. > + If server load exceed this value then return "503 Service Unavailable" > + error. Server load is taken to be 0 if gitweb cannot determine its value. > + Set it to undefined value to turn it off. [Default: 300] Probably worth spelling out that this is a "load average" (as shown by uptime(1)). Language nits: missing "the" before "server load" (2x); instead of "exceed", use "exceeds" (singular); missing subject "gitweb" before "will return the"; clearer to say it is "this feature" rather than "it" that can be turned off by setting this var to undef. > + > +$per_request_config:: > + If set to code reference, it would be run once per each request. You can > + set parts of configuration that change per session, e.g. by adding > + the following code to gitweb configuration file > ++ > +-------------------------------------------------------------------------------- > +our $per_request_config = sub { > + $ENV{GL_USER} = $cgi->remote_user || "gitweb"; > +}; > +-------------------------------------------------------------------------------- Language nits: missing "this is" before "set to a code reference"; "would" should be "will" (those crazy English conditionals again); the appropriate preposition before "each request" is "for", not "per"; missing "this way" after "change per session"; would be clearer with a full stop before the example, and with the example made into a full sentence ("For example, one might use the following code in a gitweb configuration file:"). > ++ > +Otherwise it is treated as boolean value: if true gitweb would process > +config file once per request, if false it would process config file only > +once. [Default: true] > ++ > +*NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default > +values before every request, so if you want to change them, be sure to set > +this variable to true or a code reference effecting the desired changes. At this point, I've forgotten what the "Otherwise" is contrasting with; probably best to repeat it ("If $per_request_config is not a code reference, it is interpreted as a boolean value."); "would" should be "will" again (2x); missing "the" or "each" before "config file" (2x); missing "and" before "if it is false"; "it" could be "gitweb" to avoid confusion in this pronoun-heavy sentence; missing "each time it is executed" after "process the config file only once". Probably worth mentioning that this variable starts to shine when one gitweb instance is used to serve multiple requests, with CGI replacements like mod_perl, fastcgi, plackup, and so on. > + > + > +Other variables > +~~~~~~~~~~~~~~~ > +Usually you should not need to change (adjust) any of configuration > +variables described below; they should be automatically set by gitweb to > +correct value. > + > + > +$version:: > + Gitweb version, set automatically when creating gitweb.cgi from > + gitweb.perl. You might want to modify it if you are running modified > + gitweb, for example > ++ > +--------------------------------------------------- > +our $version .= " with caching"; > +--------------------------------------------------- Might be worth mentioning this is only used in HTML comments and the "generator" metadata field, nothing more special than that. > + > +$my_url:: > +$my_uri:: > + Full URL and absolute URL of gitweb script; > + in earlier versions of gitweb you might have need to set those > + variables, now there should be no need to do it. See > + `$per_request_config` if you need to set them still. Language nits: missing "the" before "gitweb script" and "but" before "now". What is the difference between a full URL and an absolute URL? > + > +$base_url:: > + Base URL for relative URLs in pages generated by gitweb, > + (e.g. `$logo`, `$favicon`, `@stylesheets` if they are relative URLs), > + needed and used only for URLs with nonempty PATH_INFO via > + '<base href="$base_url">'. Usually gitweb sets its value correctly, > + and there is no need to set this variable, e.g. to $my_uri or "/". > + See `$per_request_config` if you need to set it anyway. Language nits: clearer with "via '<base ...>'" moved before "only for URLs with nonempty PATH_INFO"; "no need to set" could be "no need to override". > + > + > +CONFIGURING GITWEB FEATURES > +--------------------------- > +Many gitweb features can be enabled (or disabled) and configured using the > +`%feature` hash. Names of gitweb features are keys of this hash. > + > +Each `%feature` hash element is a hash reference and has the following > +structure: > +---------------------------------------------------------------------- > +"<feature_name>" => { > + "sub" => <feature-sub (subroutine)>, > + "override" => <allow-override (boolean)>, > + "default" => [ <options>... ] > +}, > +---------------------------------------------------------------------- Nice. > +Some of features does not support project specific override. For those > +features the structure of appropriate `%feature` hash element has a simpler > +form: > +---------------------------------------------------------------------- > +"<feature_name>" => { > + "override" => 0, > + "default" => [ <options>... ] > +}, > +---------------------------------------------------------------------- > +As one can see it lacks \'sub' element. Language nits: the "of" in "Some of features" is extraneous; "does" should be "do" (plural) because we are talking about multiple features, or, better, be replaced by "cannot be overriden per project" (so: "Some features cannot be overridden per project"); missing "the" before "'sub' field". > + > +The meaning of respective parts of feature configuration are described > +below: Language nit: "respective parts" should be "each part", "each field", or something like that; "are" needs to be "is" to agree with the subject ('meaning'). > + > +default:: > + List (array reference) of feature parameters (if there are any), > + used also to toggle (enable or disable) given feature. > ++ > +Note that it is currently *always* an array reference, even if > +feature doesn't accept any configuration parameters, and \'default' > +is used only to turn it on or off. In such case you turn feature on > +by setting this element to `[1]`, and torn it off by setting it to > +`[0]`. See also part about "blame" feature in the "Examples" > +section. > ++ > +To disable feature that accepts parameters (is configurable), you > +need to set this element to empty list i.e. `[]`. Nits: "part" means "passage" here; missing "the" before "passage" and '"blame" feature'; "feature" should be "features", "accepts" should be "accept", and "is configurable" should be "are configurable". > + > +override:: > + If it has a true value then given feature is overridable, which > + means that it can be configured (or enabled/disabled) on > + per-repository basis. > ++ > +Usually given "<feature>" is configurable via `gitweb.<feature>` > +config variable in per-repository git configuration file. > ++ > +*Note* that no feature is overridable by default. Nits: better to spell out what "it" is ("this field", I guess); missing "the" before "given feature", "`gitweb.<feature>` configuration variable", and "per-repository Git configuration file". > + > +sub:: > + Subroutine that will be called with default options as parameters to > + examine per-repository configuration, but only if feature is > + overridable (\'override' is set to true). If not present then > + per-repository override for given feature is not supported. > ++ > +You wouldn't need to ever change it in gitweb config file. Language nits: "default options as parameters" means "the array referred to by the 'default' field as parameter list", I guess. Missing "the" before "feature is overridable" and "gitweb configuration files". "given feature" -> "this feature". "not supported" -> "not enabled", maybe. Actually, I'm not sure I understand this one. Are users supposed to set this field? Where can they look to find out what features have it set by default? Who calls this function, and what does that person or code path do with the return value? If it is not part of the gitweb configuration that an administrator might modify (the subject of this manpage), why not just say that ("subroutine used internally; present if and only if this feature can be made overridable with the "override" field; you should not change it") and leave it at that? > + > + > +Features in `%feature` > +~~~~~~~~~~~~~~~~~~~~~~ > +Below there are described gitweb features that are configurable via > +`%feature` hash. For a complete list please consult gitweb sources. Language nit: "Below there are described gitweb features ..." -> "The gitweb features ... are listed below". The second sentence could probably be more apologetic, something like "Currently the only authoritative and complete list is in the comments in the gitweb.cgi source code." > + > +blame:: > + Enable the "blame" and "blame_incremental" blob views, showing for > + each line the last commit that modified it; see linkgit:git-blame[1]. > + This can be very CPU-intensive and is therefore disabled by default. > ++ > +This feature can be configured on a per-repository basis via > +repository's `gitweb.blame` configuration variable (boolean). Nice. > + > +snapshot:: > + Enable and configure "snapshot" action, providing a compressed > + archive of any tree or commit; see also linkgit:git-archive[1]. > + This can potentally generate high traffic if you have large project. > ++ > +The value (of \'default') is a list of names of snapshot formats > +defined in `%known_snapshot_formats` hash, that you wish to offer. > +Among supported formats are "tgz", "tbz2", "txz" (gzip/bzip2/xz > +compressed tar archive) and "zip"; please consult gitweb sources for > +a definitive list. By default only "tgz" is offered. > ++ > +This feature can be configured on a per-repository basis via > +repository's `gitweb.blame` configuration variable, which contains > +a comma separated list of formats, or "none" to disable snapshots. > +Unknown values will be ignored. Language nits: missing "the" before "snapshot action"; "providing" would be clearer if replaced by "which allows users to download" or "which serves" or something like that; instead of "see also" it might be nice to say "as produced by" because more precise; would be clearer without parentheses around "of 'default'"; missing comma before "defined in the %known_snapshot_formats hash"; "Among supported formats are" is clearer as "Supported formats include"; comma before "or 'none' to disable snapshots" is extraneous; "will be ignored" should be "are ignored". > + > +grep:: > + Enable grep search, which will list the files in currently selected > + tree (directory) containing the given string; see linkgit:git-grep[1]. > + This can be potentially CPU-intensive, of course. Enabled by default. > ++ > +This feature can be configured on a per-repository basis via > +repository's `gitweb.grep` configuration variable (boolean). Language nit: "will list" should be "lists". Nice. > + > +pickaxe:: > + Enable the so called pickaxe search, which will list the commits > + that modified a given string in a file. This can be practical and > + quite faster alternative to "blame" action, but still potentially > + CPU-intensive. Enabled by default. > ++ > +The pickaxe search is described in linkgit:git-log[1] (the > +description of `-S<string>` option, which refers to pickaxe entry in > +linkgit:gitdiffcore[7] for more details). > ++ > +This feature can be configured on a per-repository basis via > +repository's `gitweb.pickaxe` configuration variable (boolean). I think "modified" means "introduced or removed" (as an approximation to "changes the number of occurences of"). Missing "it is" before "still potentially CPU-intensive". "via" seems to mean "using the". (By the way, is there any way for the the very paranoid to limit the length of regexes used or CPU time used per request, to get some reasonable cap on this sort of thing? I guess that's more in the realm of web server configuration than something gitweb should be responsible for --- but if there's some common practice or well known reference on the topic, it could be worth mentioning at the top of this GITWEB FEATURES section some day.) > + > +show-sizes:: > + Enable showing size of blobs (ordinary files) in a "tree" view, in a > + separate column, similar to what `ls -l` does; see description of > + `-l` option in linkgit:git-ls-tree[1] manpage. This cost a bit of > + I/O. Enabled by default. > ++ > +This feature can be configured on a per-repository basis via > +repository's `gitweb.showsizes` configuration variable (boolean). Nit: "cost" -> "costs". Interesting (I guess packv4 will help with the CPU [decompression] cost of this when it comes). > + > +patches:: > + Configure "patches" view, which displays list of commits in email > + (plain text) output format; see also linkgit:git-format-patch[1]. > + The value is the maximum number of patches in a patchset generated > + in "patches" view. Set this to 0 or undef to disable patch view, or > + to a negative number to remove any limit. Default value is 16. > ++ > +This feature can be configured on a per-repository basis via > +repository's `gitweb.patches` configuration variable (integer). "Configure" -> "Enable and configure" and "Set this to ..." -> "Set the 'default' field to a list containing the single item ...", I guess. > + > +avatar:: > + Avatar support. When this feature is enabled, views such as > + "shortlog" or "commit" will display an avatar associated with > + the email of the committer(s) and/or author(s). > ++ > +Currently available providers are *"gravatar"* and *"picon"*. > +If an unknown provider is specified, the feature is disabled. > +*Note* that some provides might require extra Perl packages to be > +installed; see 'gitweb/INSTALL' for more details. "commiter(s) and/or author(s)" -> "each committer and author". If I set 'default' to ["gravator", "picon", "unknown"], will that really disable the feature? > ++ > +This feature can be configured on a per-repository basis via > +repository's `gitweb.avatar` configuration variable. > ++ > +See also `%avatar_size` with pixel sizes for icons and avatars > +("default" is used for one-line like "log" and "shortlog", "double" > +is used for two-line like "commit", "commitdiff" or "tag"). If the > +default font sizes or lineheights are changed (e.g. via adding extra > +CSS stylesheet in `@stylesheets`), it may be appropriate to change > +these values. What is the syntax of the "[gitweb] avatar" value --- space delimited? comma delimited? > + > +highlight:: > + Server-side syntax hightlight support in "blob" view. It requires > + `$highlight_bin` program available (see description of this variable > + in "Configuration variables" section above), and therefore is > + disabled by default. > ++ > +This feature can be configured on a per-repository basis via > +repository's `gitweb.highlight` configuration variable (boolean). Language nit: missing "to be" before "available", "the" before "description" and '"Configuration variables" section'; the comma before "and" is extraneous. > + > +remote_heads:: > + Enable displaying remote heads (remote-tracking branches) in the "heads" > + list. In most cases it is unnecessary internal private detail, and it > + is therefore disabled by default. linkgit:git-instaweb[1], which is > + usually used to browse local repositories, enables and uses this > + feature. > ++ > +This feature can be configured on a per-repository basis via > +repository's `gitweb.remote_heads` configuration variable (boolean). Could clarify that "it" means "the list of remote-tracking branches" first and then "this feature". Missing "an" before "irrelevant, private detail". > + > + > +The list below presents features that do not allow project specific > +overrides. If we consider it one list: "The remaining features cannot be overridden on a per project basis". > + > +search:: > + Enable text search, which will list the commits which match author, > + committer or commit text to a given string; see description of > + `--author`, `--committer` and `--grep` options in linkgit:git-log[1] > + manpage. Enabled by default. > ++ > +Project specific override is not supported. Nice. I prefer "Enables" over "Enable" so commands can be directed at the reader only, but the current text is clear enough. Missing "the" before "descriptions". > + > +forks:: > + Make gitweb consider projects in subdirectories of project root > + (basename) to be forks of existing projects. Given project > + `$projname.git`, projects matching `$projname/*.git` will not be > + shown in the main projects list, instead a \'+' mark will be added > + to `$projname` there and a "forks" view will be enabled for the > + project, listing all the forks. If project list is taken from a > + file, forks have to be listed after the main project. > ++ > +Project specific override is not supported. To avoid questions of who made it happen: "If this feature is enabled, gitweb considers projects in subdirectories ...". If I understand correctly, "Given project `$projname.git`, projects matching `$projname/*.git`" can be written as "If the project `$projname.git` exists, projects in the `$projname/` directory". Is it just projects in that directory, or are subdirectories included, as in the following example? project.git project/foo/bar/baz/qux.git Replacing the comma before "instead" with a full stop, adding a comma after "instead", and putting the sentence in the present tense ("Instead, a '+' mark is shown next to `$projname` and links to a "forks" view that lists projects in the $projname/ subdirectory) seems to make it clearer. Missing "the" before "project list"; missing "in that file" after "after the main project"; "have to be" probably means "are only recognized if". > + > +actions:: > + Insert custom links to the action bar of all project pages. This > + enables you to link to third-party scripts integrating into gitweb. > ++ > +The "default" value consists of a list of triplets in the form > +`("<label>", "<link>", "<position>")` where "position" is the label > +after which to insert the link, "link" is a format string where `%n` > +expands to the project name, `%f` to the project path within the > +filesystem, `%h` to the current hash (\'h' gitweb parameter) and > +`%b` to the current hash base (\'hb' gitweb parameter); `%%` expands > +to \'%'. Interesting. "enables" should be "allows" here. Is %f an absolute path (i.e., starting with '/')? > ++ > +For example http://repo.or.cz git hosting site sets it to the > +following to enable graphical log (via third party tool > +*git-browser*): > ++ > +---------------------------------------------------------------------- > +$feature{'actions'}{'default'} = > + [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')]; > +---------------------------------------------------------------------- > ++ > +This adds link titled "graphiclog" after "summary" link, leading to > +`git-browser` script, passing `r=<project>` as a query parameter. Missing ", at the time this page was written, the" after "For example" (with "sets" replaced by "set" to match); "via" sounds more natural when replaced by "using the"; missing "a" before "link"; missing "the" before "summary link on the project listing and project pages". > ++ > +Project specific override is not supported. > + > +timed:: > + Enable displaying how much time and how many git commands it took to > + generate and display page in the page footer (at the bottom of > + page). For example it might be: "This page took 6.53325 seconds and > + 13 git commands to generate." Disabled by default. > ++ > +Project specific override is not supported. Missing "each" between "display" and "page". "it might be" -> "the footer might contain". > + > +javascript-timezone:: > + Enable and configure ability to change common timezone for dates in > + gitweb output via JavaScript. Dates in gitweb output include > + authordate and comitterdate in "commit", "commitdiff" and "log" > + views, and taggerdate in "tag" view. Enabled by default. > ++ > +Value is list of three values: default timezone (if client didn't > +select other timezone and saved it in a cookie), name of cookie > +where to store selected timezone, and CSS class used to mark up > +dates for manipulation. If you want to turn it off, set "default" > +to empty list: `[]`. > ++ Language nits: missing "the" before "ability", "client", and "Value"; missing "a" before "common timezone", "list of three values", "default timezone", "cookie name", and "HTML class name" (why is this last one configurable?); "change" should probably be "choose"; missing "for users" before "to choose"; "didn't select other timezone" -> "hasn't selected some other timezone"; missing "for" before "if the client hasn't selected"; "turn it off" would be clearer as "turn this feature off". > +In most case you would want to change only default timezone: > ++ > +--------------------------------------------------------------------------- > +$feature{'javascript-timezone'}{'default'}[0] = "utc"; > +--------------------------------------------------------------------------- Nice. "In most case you would want to change only" -> "Typical gitweb config files will only change" can take the desires of an admin that is implementing someone else's will out of the equation. > ++ > +Timezone value can be "local" (for local timezone that browser uses), "utc" > +(what gitweb uses when JavaScript or this feature is disabled), or numerical > +timezone in the form of "+/-HHMM" for example "+0200". This way is > +guaranteed to be backward compatibile. > ++ > +Project specific override is not supported. Language nits: when we are talking about supported values in general, it sounds better for some reason with "value" -> values"; "numerical timezone" -> "numerical timezones"; "for example" -> "such as". What is "This way", and what other way should people be avoiding to prevent forward compatibility gotchas? > + > + > +EXAMPLES > +-------- Hoorah! [...] > +ENVIRONMENT > +----------- > +The location of per-instance and system-wide configuration files can be set > +using the following environment variables: Clearer to say "overridden" to emphasize that these replace rather than supplementing the locations described under FILES. [...] > +GITWEB_CONFIG:: > + Sets location of per-instance configuration file. [...] > +FILES > +----- > +gitweb_config.perl:: > + This is default value for per-instance configuration file. The > + format of this file is described above. > +/etc/gitweb.conf:: > + This is default value for fallback system-wide configuration > + file. This file is used only if per-instance configuration > + variable is not found. > +/etc/gitweb-common.conf:: > + This is default value for common system-wide configuration > + file. "default value" sounds strange here --- I guess I would have expected something more like ENVIRONMENT ----------- ... GITWEB_CONFIG:: Path to use to find the per-instance configuration file, instead of gitweb_config.perl. If relative, this is relative to $GITWEBDIR. FILES ----- /etc/gitweb-common.conf:: Options to be shared by all gitweb instances. The format is described above. $GITWEBDIR/gitweb_config.perl:: Additional settings for a particular gitweb instance (in the same format). /etc/gitweb.conf:: Fallback configuration file with settings for gitweb instances that do not contain a gitweb_config.perl file. [...] > gitweb/README | 133 +------- [...] > +++ b/gitweb/README > @@ -41,139 +41,8 @@ Ultimate description on how to reconfigure the default features setting > in your `GITWEB_CONFIG` or per-project in `project.git/config` can be found > as comments inside 'gitweb.cgi'. > > -See also the "Gitweb config file" (with an example of config file), and [...] > +See also gitweb.conf(5) manpage. > + Thanks very much for this. ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH/RFCv4 2/4] gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation) 2011-09-20 4:41 ` Jonathan Nieder @ 2011-09-22 13:41 ` Jakub Narebski 0 siblings, 0 replies; 12+ messages in thread From: Jakub Narebski @ 2011-09-22 13:41 UTC (permalink / raw) To: Jonathan Nieder; +Cc: git, Drew Northup On Tue, 20 Sep 2011, Jonathan Nieder wrote: > Jakub Narebski wrote: > > > [jn: Improved, extended, removed duplicate info from README] > > Hoorah! I have very little to add to what's already been done --- > mostly I can just lend my ear as a native English speaker. Thanks, that is a lot of help; English is not my primary language. > > +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` qualifier in `our $variable = <value>;` is a safety > > +check: if newer gitweb does no longer use given variable, by using `our` we > > +won't get syntax errors. > > Language nit: for "indeed", something like "internally" might be more > natural. > > The syntax and the typical idiom were already described in the > DESCRIPTION section, so the emphasis should be somehow different here > to avoid boring the reader. One way might be to plunge directly into > what the second paragraph above says: > > The syntax of the configuration files is that of Perl, since these files are > handled by sourcing them as fragments of Perl code (the language that > gitweb itself is written in). Variables are typically set using the > `our` qualifier (as in "`our $variable = <value>;`") to avoid syntax > errors if a new version of gitweb no longer uses a variable and therefore > stops declaring it. Thanks, I used your proposal. It reduces duplication, and reads better. > > + > > +You can include other configuration file using read_config_file() > > +subroutine. For example, you can read defaults in fallback > > +system-wide GITWEB_CONFIG_SYSTEM from GITWEB_CONFIG by adding > > + > > + read_config_file($GITWEB_CONFIG_SYSTEM); > > + > > +at very beginning of per-instance GITWEB_CONFIG file. In this case > > +settings in said per-instance file will override settings from > > +system-wide configuration file. Note that read_config_file checks > > +itself that the file it reads exists. [...] > The reader wonders: After checking that the file exists, what does > read_config_file do (does it silently skip it or error out)? And why > would I use this trick instead of just writing a gitweb-common.conf > file? (Was read_config_file introduced before gitweb-common.conf, > making this useful when creating a configuration that should be usable > with older versions of gitweb?) I have replaced it now with the following: You can include other configuration file using read_config_file() subroutine. For example, one might want to put gitweb configuration related to access control for viewing repositories via Gitolite (one of git repository management tools) in a separate file, e.g. in '/etc/gitweb-gitolite.conf'. To include it, put -------------------------------------------------- read_config_file("/etc/gitweb-gitolite.conf"); -------------------------------------------------- somewhere in gitweb configuration file used, e.g. in per-installation gitweb configuration file. Note that read_config_file() checks itself that the file it reads exists, and does nothing if it is not found. It also handles errors in included file. > > +$project_maxdepth:: > > + Filesystem traversing depth limit for recursively scanning for git > > + repositories, used if `$projects_list` (below) is unset. The default > > + value of this variable is determined by build-time configuration > > + variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to 2007. > > "Filesystem traversing depth limit" is quite a long stack of nouns :), > and unfortunately I don't know what it means. Is this the depth of > nested subdirectories below $project_root that gitweb will look at > when discovering repositories? If I have no subdirectories in the > projectroot except the repositories themselves, should I set this to 1 > or 0? What happens with forks? Is this just a convenience feature or > can it be used for security or to create performance gaurantees? > > By the way, what happens if projectroot contains a symlink to some > directory elsewhere in the filesystem containing repositories --- will > gitweb traverse it? I have changed order of describing variables, putting $projects_list before $project_maxdepth - this way we don't have to refer to following text. I have replaced the description of $project_maxdepth with the following $project_maxdepth:: If `$projects_list` variable is unset, gitweb will recursively scan filesystem for git repositories. The `$project_maxdepth` is used to limit traversing depth, relative to `$projectroot` (starting point); it means that directories which are further from `$projectroot` than `$project_maxdepth` will be skipped. + It is purely performance optimization, originally intended for MacOS X, where recursive directory traversal is slow. Gitweb follows symbolic links, but it detects cycles, ignoring any duplicate files and directories. + The default value of this variable is determined by the build-time configuration variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to 2007. I hope that it makes meaning and use of this variable more clear. > What if I want this to be infinite (i.e., to disable the feature) --- > would I be crazy? It is currently not possible to disable this feature. The value of 2007 should be enough in most cases (read: all sane cases). > > +$projects_list:: > > + Plain text file listing projects or name of directory > > + to be scanned for projects. [...] > When this is a relative path, what is it taken relative to? As with all relative paths to files, it is relative to where CGI script is. I probably should write about this somewhere... > > + > > +$export_ok:: > > + Show repository only if this file exists (in repository). Only > > + effective if this variable evaluates to true. Can be set during > > + building gitweb via `GITWEB_EXPORT_OK`. [No default / Not set] > > This is always a relative path, right? What is it relative to --- > $GIT_DIR, I guess? > > Usage nits: the phrase starting with "during" reads more naturally if > "during" is replaced with "when" and "via" replaced with "by setting". > If there were no default, that would mean that gitweb errors out when > gitweb.conf does not set this variable; instead, the default seems to > be "undef" (or 'false') if I understand correctly. Description of $export_ok got replaced by the following: $export_ok:: Show repository only if this file exists (in repository). Only effective if this variable evaluates to true. Can be set when building gitweb by setting `GITWEB_EXPORT_OK`. This path is relative to `GIT_DIR`. git-daemon[1] uses 'git-daemon-export-ok', unless started with `--export-all`. [No default / Not set (this feature is turned off)] > > + > > +$export_auth_hook:: > > + Show repository only if this subroutine returns true, when given as > > + the only parameter the full path to the project. Example: > > ++ > > +---------------------------------------------------------------------------- > > +our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; }; > > +---------------------------------------------------------------------------- > > ++ > > +though the above might be done by using `$export_ok` instead > > ++ > > +---------------------------------------------------------------------------- > > +our $export_ok = "git-daemon-export-ok"; > > +---------------------------------------------------------------------------- > > Style nit: commands in this kind of documentation should be directed to > the reader, not gitweb, so it would be nicer to explain this in terms of > what the $export_auth_hook is. Thanks. I should probably rewrite description of $export_ok in the same way, isn't it? > That is, something like the following: > > $export_auth_hook:: > Function used to determine which repositories should be shown. > This subroutine should take one parameter, the full path to > a project, and if it returns true, that project will be included > in the projects list and can be accessed through gitweb as long > as it fulfills the other requirements described by $export_ok, > $projects_list, and $projects_maxdepth. Example: Thanks, I have used your description. > Is "our $export_auth_hook = undef;" a valid configuration? What is the > default? I have added the following line at the end of description of this variable: If not set (default), it means that this feature is disabled. > > + > > +$strict_export:: > > + Only allow viewing of repositories also shown on the overview page. > > + This for example makes `$gitweb_export_ok` file decide if repository is > > + available and not only if it is shown. If `$gitweb_list` points to > > + file with list of project, only those repositories listed would be > > + available for gitweb. Can be set during building gitweb via > > + `GITWEB_STRICT_EXPORT`. [No default / Not set] > > Is the default behavior as though this were true or false? Last sentence now reads: [No default / Not set (you can access repositories hidden from projects list page)] > > +Finding files > > +~~~~~~~~~~~~~ > > +Those configuration variables tell gitweb where to find files. Values of > > +those variables are paths on filesystem. Of those only `$GIT` is required > > +to be (correctly) set for gitweb to be able to work; all the rest are > > +required only for extra configuration or extra features. [...] > When you say the remainder are only required in special cases, does > that mean that they are ignored unless some other enabling variable is > set or that they can be set to "undef" to disable the relevant > feature? I have removed this sequence, and extended description of each variable instead. > > +$mimetypes_file:: > > + File to use for (filename extension based) guessing of MIME types before > > + trying '/etc/mime.types'. Path, if relative, is taken currently as > > + relative to the current git repository. [Unset by default] > The use of "currently" sounds like an apology. Does that mean that > gitweb ought to be rejecting relative paths for this variable? I think it was originally intended as note that this resolution of relative path is subject to change in future versions of gitweb. But I think it is not true (backward compatibility), and it is more important that this resolution of relative path is untypical. I have reformulated this description to read: $mimetypes_file:: File to use for (filename extension based) guessing of MIME types before trying '/etc/mime.types'. *NOTE* that this path, if relative, is taken as relative to the current git repository, not to CGI script. If unset, only '/etc/mime.types' is used (if present on filesystem). If no mimetypes file is found, mimetype guessing bassed on extension of file is disabled. [Unset by default] > > + > > +$highlight_bin:: > > + Path to the highlight executable to use (must be the one from > > + http://www.andre-simon.de due to assumptions about parameters and output). > > + Useful if 'highlight' is not installed on your webserver's PATH. > > + [Default: 'highlight'] > > ++ > > +*NOTE*: if you want to add support for new syntax (supported by > > +"highlight" but not used by gitweb), you need to modify `%highlight_ext` > > +or `%highlight_basename`, depending on whether you detect type of file > > +based on extension (for example "*.sh") or on its basename (for example > > +"Makefile"). Keys of those hashes are extension or basename, > > +respectively, and value for given key is name of syntax to be passed via > > +`--syntax <syntax>` to highlighter. [...] > Is "*.sh" actually an example of an extension? I.e., do I write the > following? > > our %highlight_ext; > $highlight_ext{"*.sh"} = "sh"; You are right, it should be "sh", not "*.sh". Fixed, and added example (about "phtml", which usually means PHP, but might mean embedded Perl (ePerl)). > > +Links and their targets > > +~~~~~~~~~~~~~~~~~~~~~~~ > > +Configuration variables described below configure some of gitweb links: > > +their target and their look (text or image), and where to find page > > +prerequisites (stylesheet, favicon, images, scripts). Usually they are left > > +at their default values, with the possible exception of `@stylesheets` > > +variable. > > Language nits: missing "The" before "Configuration variables described > below"; missing "some" before "supporting files". ^^^^^^^^^^^^^^^^^^---??? > > + > > +@stylesheets:: > > + List of URIs of stylesheets (relative to base URI of a page). You > > + might specify more than one stylesheet, for example use gitweb.css > > + as base, with site specific modifications in separate stylesheet > > + to make it easier to upgrade gitweb. You can add a `site` stylesheet > > + for example by putting > > ++ > > +---------------------------------------------------------------------------- > > +push @stylesheets, "gitweb-site.css"; > > +---------------------------------------------------------------------------- > > ++ > > +in the gitweb config file. Those values that are relative paths, are > > +relative to base URI of gitweb. > > [...] What is a base URI --- is it set by another variable? Base URI is a concept defined in HTML / XHTML specification (or in URI definition), so I'd rather not explain it here. > > +This list should contain URI of gitweb's stylesheet. The URI of gitweb > > +stylesheet is set during build time via `GITWEB_CSS` variable. It's default > > +value is 'static/gitweb.css' (or 'static/gitweb.min.css' if the `CSSMIN` > > +variable is defined, i.e. if CSS minifier is used during build). > > ++ > > +*Note*: there is also legacy `$stylesheet` configuration variable, which was > > +used by older gitweb. [...] > If I am new on the job and find the $stylesheet variable set, what > should I interpret it to mean? How can it be translated to the newer > @stylesheets style? What happens if both variables are set --- does > one override the other, or are they combined somehow? Added If `$stylesheet` variable is defined, only CSS stylesheet given by this variable is used by gitweb. I hope that old config files that define this variable are rare. > > +$home_link:: > > + Target of the home link on top of all pages (the first part of view > > + "breadcrumbs"). By default set to absolute URI of a page ($my_uri). > Which page does "a page" refer to here (doesn't $my_uri change from > request to request)? I have extended last sequence of this description to read: By default it is set to the absolute URI of a current page (to the value of `$my_uri` variable, or to "/" if `$my_uri` is undefined or is an empty string). $my_uri changes from request to request, and $home_link too. By default config is re-read on each request; if not, one should use $per_request_config subroutine to set this variable if it changes from request to request. > > +$default_projects_order:: > > + Default value of ordering of projects on projects list page. Valid > > + values are "none" (unsorted), "project" (by project name, i.e. path > > + to repository relative to `$projectroot`), "descr" (project > > + description), "owner", and "age" (by date of most current commit). > > ++ > > +Default value is "project". Unknown value means unsorted. > > What does "Default" mean here (i.e., what overrides it)? Added [...], which means the ordering used if you don't explicitly sort projects list (if there is no "o" CGI query parameter in the URL). > > + > > + > > +Changing gitweb behavior > > +~~~~~~~~~~~~~~~~~~~~~~~~ > > +Those configuration variables control _internal_ gitweb behavior. > > [...] Does internal behavior mean "functionality as opposed to > appearance and input location" or something like that? Yes, it does. > > + > > +$default_blob_plain_mimetype:: > > + Default mimetype for blob_plain (raw) view, if mimetype checking > > + doesn't result in some other type; by default "text/plain". [...] > Where can I look to read more about mimetype autodetection? Added the following sentence: Gitweb guesses mimetype of a file to display based on extension of its filename, using `$mimetypes_file` (if set and file exists) and '/etc/mime.types' files (see *mime.types*(5) manpage; only filename extension rules are supported by gitweb). > > +@diff_opts:: > > + Rename detection options for git-diff and git-diff-tree. By default > > + (\'-M'); set it to (\'-C') or (\'-C', \'-C') to also detect copies, > > + or set it to () i.e. empty list if you don't want to have renames > > + detection. [...] > Probably worth mentioning that GNU patch still has problems with some > rename patches, especially when they involve file copies ['-C'] or > criss-cross renames ['-B'] (see [1] and [2], for example). > > [1] http://savannah.gnu.org/bugs/?31058 > [2] http://thread.gmane.org/gmane.linux.ports.sh.devel/8697/focus=8773 I have added the following paragraph: + *Note* that rename and especially copy detection can be quite CPU-intensive. Note also that non git tools can have problems with patches generated with options mentioned above, especially when they involve file copies (\'-C') or criss-cross renames (\'-B'). > > +@git_base_url_list:: > > + List of git base URLs used for URL to where fetch project from, shown > > + in project summary page. Full URL is "`$git_base_url/$project`". You > > + can setup multiple base URLs (for example one for `git://` protocol > > + access, and one for `http://` "dumb" protocol access). Note that per > > + repository configuration can be set in '$GIT_DIR/cloneurl' file, or as > > + values of multi-value `gitweb.url` configuration variable in project > > + config. > > ++ > > +You can setup one single value (single entry/item in this list) during > > +building by using `GITWEB_BASE_URL` built-time configuration variable. > > +[No default] > > Language nits: "git base URLs used for URL to where fetch project from" > means something like "Git URLs relative to which projects can be > fetched"; [...] [...] > Is the per repository cloneurl added to this list, or does it override > it? I have rewritten it to hopefully more clear version, and added information about precedence of cloneurl and the like: @git_base_url_list:: List of git base URLs. These URLs are used to generate URLs describing from where to fetch a project, which are shown on project summary page. The full fetch URL is "`$git_base_url/$project`", for each element of this list. You can set up multiple base URLs (for example one for `git://` protocol, and one for `http://` protocol). + Note that per repository configuration can be set in '$GIT_DIR/cloneurl' file, or as values of multi-value `gitweb.url` configuration variable in project config. Per-repository configuration takes precedence over value composed from `@git_base_url_list` elements and project name. + You can setup one single value (single entry/item in this list) at build time by setting the `GITWEB_BASE_URL` built-time configuration variable. [Default: (), i.e. empty list] > > +$maxload:: > > + Used to set the maximum load that we will still respond to gitweb queries. > > + If server load exceed this value then return "503 Service Unavailable" > > + error. Server load is taken to be 0 if gitweb cannot determine its value. > > + Set it to undefined value to turn it off. [Default: 300] > > Probably worth spelling out that this is a "load average" (as shown by uptime(1)). I have added the following sentence to describe it: Currently it works only on Linux, where it uses '/proc/loadavg'; the load there is the number of active tasks on the system -- processes that are actually running -- averaged over the last minute. > > +$per_request_config:: > > + If set to code reference, it would be run once per each request. You can > > + set parts of configuration that change per session, e.g. by adding > > + the following code to gitweb configuration file > > ++ > > +-------------------------------------------------------------------------------- > > +our $per_request_config = sub { > > + $ENV{GL_USER} = $cgi->remote_user || "gitweb"; > > +}; > > +-------------------------------------------------------------------------------- > > Language nits: missing "this is" before "set to a code reference"; > "would" should be "will" (those crazy English conditionals again); the > appropriate preposition before "each request" is "for", not "per"; > missing "this way" after "change per session"; would be clearer with a > full stop before the example, and with the example made into a full > sentence ("For example, one might use the following code in a gitweb > configuration file:"). > > > ++ > > +Otherwise it is treated as boolean value: if true gitweb would process > > +config file once per request, if false it would process config file only > > +once. [Default: true] > > ++ > > +*NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default > > +values before every request, so if you want to change them, be sure to set > > +this variable to true or a code reference effecting the desired changes. > > At this point, I've forgotten what the "Otherwise" is contrasting with; > probably best to repeat it ("If $per_request_config is not a code > reference, it is interpreted as a boolean value."); "would" should be > "will" again (2x); missing "the" or "each" before "config file" (2x); > missing "and" before "if it is false"; "it" could be "gitweb" to > avoid confusion in this pronoun-heavy sentence; missing "each time it > is executed" after "process the config file only once". > > Probably worth mentioning that this variable starts to shine when one > gitweb instance is used to serve multiple requests, with CGI > replacements like mod_perl, fastcgi, plackup, and so on. I have rewritten and extended it as following: If `$per_request_config` is not a code reference, it is interpreted as boolean value. If it is true gitweb will process config files once per request, and if it is false gitweb will process config files only once, each time it is executed. [Default: true] + *NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default values before every request, so if you want to change them, be sure to set this variable to true or a code reference effecting the desired changes. + This variable matters only when using persistent web environments that serve multiple requests using single gitweb instance, like mod_perl, FastCGI or Plackup. > > +$version:: > > + Gitweb version, set automatically when creating gitweb.cgi from > > + gitweb.perl. You might want to modify it if you are running modified > > + gitweb, for example > > ++ > > +--------------------------------------------------- > > +our $version .= " with caching"; > > +--------------------------------------------------- > > Might be worth mentioning this is only used in HTML comments and the > "generator" metadata field, nothing more special than that. Added: This variable is purely informational, used e.g. in the "generator" meta header in HTML header. > > + > > +$my_url:: > > +$my_uri:: > > + Full URL and absolute URL of gitweb script; > > + in earlier versions of gitweb you might have need to set those > > + variables, now there should be no need to do it. See > > + `$per_request_config` if you need to set them still. [...] > What is the difference between a full URL and an absolute URL? Full URL is e.g. 'http://git.example.com/gitweb.cgi', while absolute URL is e.g. '/gitweb.cgi'. > > +sub:: > > + Subroutine that will be called with default options as parameters to > > + examine per-repository configuration, but only if feature is > > + overridable (\'override' is set to true). If not present then > > + per-repository override for given feature is not supported. > > ++ > > +You wouldn't need to ever change it in gitweb config file. > > Language nits: "default options as parameters" means "the array > referred to by the 'default' field as parameter list", I guess. > Missing "the" before "feature is overridable" and "gitweb > configuration files". "given feature" -> "this feature". "not > supported" -> "not enabled", maybe. > > Actually, I'm not sure I understand this one. Are users supposed to > set this field? Where can they look to find out what features have it > set by default? Who calls this function, and what does that person or > code path do with the return value? If it is not part of the gitweb > configuration that an administrator might modify (the subject of this > manpage), why not just say that ("subroutine used internally; present > if and only if this feature can be made overridable with the > "override" field; you should not change it") and leave it at that? Changed this to: sub:: Internal detail of implementation. What is important is that if this field is not present then per-repository override for given feature is not supported. + You wouldn't need to ever change it in gitweb config file. > > + > > + > > +Features in `%feature` > > +~~~~~~~~~~~~~~~~~~~~~~ > > +Below there are described gitweb features that are configurable via > > +`%feature` hash. For a complete list please consult gitweb sources. > > Language nit: "Below there are described gitweb features ..." -> "The > gitweb features ... are listed below". The second sentence could > probably be more apologetic, something like "Currently the only > authoritative and complete list is in the comments in the gitweb.cgi > source code." Reformulated it to read: The gitweb features that are configurable via `%feature` hash are listed below. This should be a complete list, but ultimately the authoritative and complete list is in gitweb.cgi source code, with features described in the comments. > > +pickaxe:: > > + Enable the so called pickaxe search, which will list the commits > > + that modified a given string in a file. This can be practical and > > + quite faster alternative to "blame" action, but still potentially > > + CPU-intensive. Enabled by default. > > ++ > > +The pickaxe search is described in linkgit:git-log[1] (the > > +description of `-S<string>` option, which refers to pickaxe entry in > > +linkgit:gitdiffcore[7] for more details). > > ++ > > +This feature can be configured on a per-repository basis via > > +repository's `gitweb.pickaxe` configuration variable (boolean). > > I think "modified" means "introduced or removed" (as an approximation to > "changes the number of occurences of"). It is even more correct with respect to mechanism behind '-S' option. > (By the way, is there any way for the the very paranoid to limit the > length of regexes used or CPU time used per request, to get some > reasonable cap on this sort of thing? I guess that's more in the > realm of web server configuration than something gitweb should be > responsible for --- but if there's some common practice or well known > reference on the topic, it could be worth mentioning at the top of > this GITWEB FEATURES section some day.) I don't know if it is possible to limit CPU time used per request. I think most of time is spent in git commands; gitweb currently doesn't offer any way to renice or limit time of running git commands. The only load-related mechanism is $maxload. > > +show-sizes:: > > + Enable showing size of blobs (ordinary files) in a "tree" view, in a > > + separate column, similar to what `ls -l` does; see description of > > + `-l` option in linkgit:git-ls-tree[1] manpage. This cost a bit of > > + I/O. Enabled by default. > > ++ > > +This feature can be configured on a per-repository basis via > > +repository's `gitweb.showsizes` configuration variable (boolean). > > Nit: "cost" -> "costs". Interesting (I guess packv4 will help with > the CPU [decompression] cost of this when it comes). Nb. the fast that directory entries ('tree' objects) do not have their size displayed was result of request from people working on packv4, where 'tree' objects would be stored decomposed, and calculating object size for a 'tree' object will be quite costly. Add to that the fact that 'tree' object size is not very interesting... > > +avatar:: > > + Avatar support. When this feature is enabled, views such as > > + "shortlog" or "commit" will display an avatar associated with > > + the email of the committer(s) and/or author(s). > > ++ > > +Currently available providers are *"gravatar"* and *"picon"*. > > +If an unknown provider is specified, the feature is disabled. > > +*Note* that some provides might require extra Perl packages to be > > +installed; see 'gitweb/INSTALL' for more details. [...] > If I set 'default' to ["gravator", "picon", "unknown"], will that > really disable the feature? Only one provider at a time can be selected; I have added this information to description. > > +forks:: > > + Make gitweb consider projects in subdirectories of project root > > + (basename) to be forks of existing projects. Given project > > + `$projname.git`, projects matching `$projname/*.git` will not be > > + shown in the main projects list, instead a \'+' mark will be added > > + to `$projname` there and a "forks" view will be enabled for the > > + project, listing all the forks. If project list is taken from a > > + file, forks have to be listed after the main project. > > ++ > > +Project specific override is not supported. [...] > If I understand correctly, "Given project `$projname.git`, projects > matching `$projname/*.git`" can be written as "If the project > `$projname.git` exists, projects in the `$projname/` directory". Is > it just projects in that directory, or are subdirectories included, as > in the following example? > > project.git > project/foo/bar/baz/qux.git Yes, they are. The new improved and extended version is now: forks:: If this feature is enabled, gitweb considers projects in subdirectories of project root (basename) to be forks of existing projects. For each project `$projname.git`, projects in the `$projname/` directory and its subdirectories will not be shown in the main projects list. Instead, a \'+' mark is shown next to `$projname`, which links to a "forks" view that lists all the forks (all projects in `$projname/` subdirectory). Additionally a "forks" view for a project is linked from project summary page. + If the project list is taken from a file (`$projects_list` points to a file), forks are only recognized if they are listed after the main project in that file. + Project specific override is not supported. > > + > > +actions:: > > + Insert custom links to the action bar of all project pages. This > > + enables you to link to third-party scripts integrating into gitweb. > > ++ > > +The "default" value consists of a list of triplets in the form > > +`("<label>", "<link>", "<position>")` where "position" is the label > > +after which to insert the link, "link" is a format string where `%n` > > +expands to the project name, `%f` to the project path within the > > +filesystem, `%h` to the current hash (\'h' gitweb parameter) and > > +`%b` to the current hash base (\'hb' gitweb parameter); `%%` expands > > +to \'%'. > > Interesting. "enables" should be "allows" here. Right. > Is %f an absolute path (i.e., starting with '/')? It is "$projectroot/$project" (which I have added to this description). > > +In most case you would want to change only default timezone: > > ++ > > +--------------------------------------------------------------------------- > > +$feature{'javascript-timezone'}{'default'}[0] = "utc"; > > +--------------------------------------------------------------------------- [...] > > +Timezone value can be "local" (for local timezone that browser uses), "utc" > > +(what gitweb uses when JavaScript or this feature is disabled), or numerical > > +timezone in the form of "+/-HHMM" for example "+0200". This way is > > +guaranteed to be backward compatibile. > > ++ > > +Project specific override is not supported. > > Language nits: when we are talking about supported values in general, > it sounds better for some reason with "value" -> values"; "numerical > timezone" -> "numerical timezones"; "for example" -> "such as". > > What is "This way", and what other way should people be avoiding to > prevent forward compatibility gotchas? "This way" refers to the example configuration. I have reformulated this description by removing last sentence, and adding + The example configuration presented here is guaranteed to be backwards and forward compatible. just after example. > [...] > > +GITWEB_CONFIG:: > > + Sets location of per-instance configuration file. > [...] > > +FILES > > +----- > > +gitweb_config.perl:: > > + This is default value for per-instance configuration file. The > > + format of this file is described above. > > +/etc/gitweb.conf:: > > + This is default value for fallback system-wide configuration > > + file. This file is used only if per-instance configuration > > + variable is not found. > > +/etc/gitweb-common.conf:: > > + This is default value for common system-wide configuration > > + file. > > "default value" sounds strange here --- I guess I would have expected > something more like > > ENVIRONMENT > ----------- > ... > GITWEB_CONFIG:: > Path to use to find the per-instance configuration file, > instead of gitweb_config.perl. If relative, this is relative > to $GITWEBDIR. > > FILES > ----- > /etc/gitweb-common.conf:: > Options to be shared by all gitweb instances. The format is > described above. > $GITWEBDIR/gitweb_config.perl:: > Additional settings for a particular gitweb instance (in > the same format). > /etc/gitweb.conf:: > Fallback configuration file with settings for gitweb instances > that do not contain a gitweb_config.perl file. I'll think about this proposal. For now I have just changed "default value for ..." to "default name of ...". Thank you very much for your feedback. -- Jakub Narebski Poland ^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH/RFCv4 3/4] gitweb: Add manpage for gitweb 2011-09-18 13:34 [PATCH/RFCv4 0/4] Moving gitweb documentation to manpages Jakub Narebski 2011-09-18 13:34 ` [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages Jakub Narebski 2011-09-18 13:34 ` [PATCH/RFCv4 2/4] gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation) Jakub Narebski @ 2011-09-18 13:34 ` Jakub Narebski 2011-09-18 13:34 ` [PATCH/RFCv4 4/4] gitweb: Add gitweb manpages to 'gitweb' package in git.spec Jakub Narebski 3 siblings, 0 replies; 12+ messages in thread From: Jakub Narebski @ 2011-09-18 13:34 UTC (permalink / raw) To: git, Drew Northup Cc: Jonathan Nieder, John 'Warthog9' Hawley, admin, Jakub Narebski Most of what is in gitweb.txt it has been pulled directly from the README and INSTALL files of gitweb. Current version is somewhat based on structure of SVN::Web manpage (one of web interfaces for Subversion). gitweb.conf(5) i.e. gitweb configuration manpage now refers to appropriate sections in gitweb(1). gitweb/README now refers to gitweb/INSTALL and gitweb(1) manpage. gitweb/INSTALL now refers to gitweb.conf(5) and gitweb(1). Inspired-by: Drew Northup <drew.northup@maine.edu> Signed-off-by: Jakub Narebski <jnareb@gmail.com> --- Changes from v3 version include: * Force URLs in SYNOPSIS into hyperlinks in HTML output * Fixed formatting of continued description list Documentation/Makefile | 2 +- Documentation/gitweb.conf.txt | 8 + Documentation/gitweb.txt | 703 +++++++++++++++++++++++++++++++++++++++++ gitweb/INSTALL | 96 +----- gitweb/README | 278 ++--------------- 5 files changed, 741 insertions(+), 346 deletions(-) create mode 100644 Documentation/gitweb.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index 6d71943..aebab11 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,7 +1,7 @@ MAN1_TXT= \ $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ $(wildcard git-*.txt)) \ - gitk.txt git.txt + gitk.txt gitweb.txt git.txt MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \ gitrepository-layout.txt gitweb.conf.txt MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \ diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index 2769302..1b276dd 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -35,6 +35,10 @@ CGI script with the default name 'gitweb_config.perl' -- allowing one to have multiple gitweb instances with different configurations by the use of symlinks. +Note that some configuration can be controlled on per-repository rather than +gitweb-wide basis: see "Per-repository gitweb configuration" subsection on +linkgit:gitweb[1] manpage. + DISCUSSION ---------- @@ -106,6 +110,8 @@ Location of repositories Configuration variables described below control finding git repositories by gitweb, and control display and access to repositories. +See also "Repositories" and later subsections in linkgit:gitweb[1] manpage. + $projectroot:: Absolute filesystem path which will be prepended to project path; the path to repository is `$projectroot/$project`. Set to @@ -172,6 +178,8 @@ though the above might be done by using `$export_ok` instead ---------------------------------------------------------------------------- our $export_ok = "git-daemon-export-ok"; ---------------------------------------------------------------------------- +See also more involved example in "Controlling access to git repositories" +subsection on linkgit:gitweb[1] manpage. $strict_export:: Only allow viewing of repositories also shown on the overview page. diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt new file mode 100644 index 0000000..4de6de3 --- /dev/null +++ b/Documentation/gitweb.txt @@ -0,0 +1,703 @@ +gitweb(1) +========= + +NAME +---- +gitweb - Git web interface (web frontend to Git repositories) + +SYNOPSIS +-------- +To get started with gitweb, run linkgit:git-instaweb[1] from a git repository. +This would configure and start your web server, and run web browser pointing to +gitweb page. + +See http://git.kernel.org/?p=git/git.git;a=tree;f=gitweb[] or +http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code, +browsed using gitweb itself. + + +DESCRIPTION +----------- +Gitweb provides a web interface to git repositories. It's features include: + +* Viewing multiple Git repositories with common root. +* Browsing every revision of the repository. +* Viewing the contents of files in the repository at any revision. +* Viewing the revision log of branches, history of files and directories, + see what was changed when, by who. +* Viewing the blame/annotation details of any file (if enabled). +* Generating RSS and Atom feeds of commits, for any branch. + The feeds are auto-discoverable in modern web browsers. +* Viewing everything that was changed in a revision, and step through + revisions one at a time, viewing the history of the repository. +* Finding commits which commit messages matches given search term. + +CONFIGURATION +------------- +Various aspects of gitweb's behavior can be controlled through the configuration +file 'gitweb_config.perl' or '/etc/gitweb.conf'. See the linkgit:gitweb.conf[5] +for details. + +Repositories +~~~~~~~~~~~~ +Gitweb can show information from one or more Git repositories. These +repositories have to be all on local filesystem, and have to share common +repository root, i.e. be all under a single parent repository (but see also +"Advanced web server setup" section, "Webserver configuration with multiple +projects' root" subsection). + +----------------------------------------------------------------------- +our $projectroot = '/path/to/parent/directory'; +----------------------------------------------------------------------- + +The default value for `$projectroot` is '/pub/git'. You can change it during +building gitweb via `GITWEB_PROJECTROOT` build configuration variable. + +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 databases to be +more exact; gitweb is not interested in a working area, and is best suited +to showing "bare" repositories). + +The name of repository in gitweb is path to it's `$GIT_DIR` (it's object +database) relative to `$projectroot`. Therefore the repository $repo can be +found at "$projectroot/$repo". + + +Projects list file format +~~~~~~~~~~~~~~~~~~~~~~~~~ +Instead of having gitweb find repositories by scanning filesystem +starting from $projectroot, you can provide a pre-generated list of +visible projects by setting `$projects_list` to point to a plain text +file with a list of projects (with some additional info). + +This file uses the following format: + +* One record (for project / repository) per line; does not support line +continuation (newline escaping). + +* Leading and trailing whitespace are ignored. + +* Whitespace separated fields; any run of whitespace can be used as field +separator (rules for Perl's "`split(" ", $line)`"). + +* Fields use modified URI encoding, defined in RFC 3986, section 2.1 +(Percent-Encoding), or rather "Query string encoding" (see +link:http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference +being that SP (" ") can be encoded as "{plus}" (and therefore "{plus}" has to be +also percent-encoded). ++ +Reserved characters are: "%" (used for encoding), "{plus}" (can be used to +encode SPACE), all whitespace characters as defined in Perl, including SP, +TAB and LF, (used to separate fields in a record). + +* Currently recognized fields are: +<repository path>:: + path to repository GIT_DIR, relative to `$projectroot` +<repository owner>:: + displayed as repository owner, preferably full name, or email, + or both + +You can generate the projects list index file using the project_index action +(the 'TXT' link on projects list page) directly from gitweb; see also +"Generating projects list using gitweb" section below. + +Example contents: +----------------------------------------------------------------------- +foo.git Joe+R+Hacker+<joe@example.com> +foo/bar.git O+W+Ner+<owner@example.org> +----------------------------------------------------------------------- + + +By default this file controls only which projects are *visible* on projects +list page (note that entries that do not point to correctly recognized git +repositories won't be displayed by gitweb). Even if a project is not +visible on projects list page, you can view it nevertheless by hand-crafting +a gitweb URL. By setting `$strict_export` configuration variable (see +linkgit:gitweb.conf[5]) to true value you can allow viewing only of +repositories also shown on the overview page (i.e. only projects explicitely +listed in projects list file will be accessible). + + +Generating projects list using gitweb +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We assume that GITWEB_CONFIG has its default Makefile value, namely +'gitweb_config.perl'. Put the following in 'gitweb_make_index.perl' file: +---------------------------------------------------------------------------- +read_config_file("gitweb_config.perl"); +$projects_list = $projectroot; +---------------------------------------------------------------------------- + +Then create the following script to get list of project in the format +suitable for GITWEB_LIST build configuration variable (or +`$projects_list` variable in gitweb config): + +---------------------------------------------------------------------------- +#!/bin/sh + +export GITWEB_CONFIG="gitweb_make_index.perl" +export GATEWAY_INTERFACE="CGI/1.1" +export HTTP_ACCEPT="*/*" +export REQUEST_METHOD="GET" +export QUERY_STRING="a=project_index" + +perl -- /var/www/cgi-bin/gitweb.cgi +---------------------------------------------------------------------------- + +Run this script and save its output to a file. This file could then be used +as projects list file, which means that you can set `$projects_list` to its +filename. + + +Controlling access to git repositories +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +By default all git repositories under `$projectroot` are visible and +available to gitweb. You can however configure how gitweb controls access +to repositories. + +* As described in "Projects list file format" section, you can control which +projects are *visible* by selectively including repositories in projects +list file, and setting `$projects_list` gitweb configuration variable to +point to it. With `$strict_export` set, projects list file can be used to +control which repositories are *available* as well. + +* You can configure gitweb to only list and allow viewing of the explicitly +exported repositories, via `$export_ok` variable in gitweb config file; see +linkgit:gitweb.conf[5] manpage. If it evaluates to true, gitweb shows +repositories only if this file named by `$export_ok` exists in its object +database (if directory has the magic file named `$export_ok`). ++ +For example linkgit:git-daemon[1] by default (unless `--export-all` option +is used) allows pulling only for those repositories that have +'git-daemon-export-ok' file. Adding ++ +-------------------------------------------------------------------------- +our $export_ok = "git-daemon-export-ok"; +-------------------------------------------------------------------------- ++ +makes gitweb show and allow access only to those repositories that can be +fetched from via `git://` protocol. + +* Finally, it is possible to specify an arbitrary perl subroutine that will +be called for each repository to determine if it can be exported. The +subroutine receives an absolute path to the project (repository) as its only +parameter (i.e. "$projectroot/$project"). ++ +For example, if you use mod_perl to run the script, and have dumb +http protocol authentication configured for your repositories, you +can use the following hook to allow access only if the user is +authorized to read the files: ++ +-------------------------------------------------------------------------- +$export_auth_hook = sub { + use Apache2::SubRequest (); + use Apache2::Const -compile => qw(HTTP_OK); + my $path = "$_[0]/HEAD"; + my $r = Apache2::RequestUtil->request; + my $sub = $r->lookup_file($path); + return $sub->filename eq $path + && $sub->status == Apache2::Const::HTTP_OK; +}; +-------------------------------------------------------------------------- + + +Per-repository gitweb configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can configure individual repositories shown in gitweb by creating file +in the 'GIT_DIR' of git repository, or by setting some repo configuration +variable (in 'GIT_DIR/config', see linkgit:git-config[1]). + +You can use the following files in repository: + +README.html:: + A html file (HTML fragment) which is included on the gitweb project + "summary" page inside `<div>` block element. You can use it for longer + description of a project, to provide links (for example to project's + homepage), etc. This is recognized only if XSS prevention is off + (`$prevent_xss` is false, see linkgit:gitweb.conf[5]); a way to include + a README safely when XSS prevention is on may be worked out in the + future. + +description (or `gitweb.description`):: + Short (shortened to `$projects_list_description_width` in the projects + list page, which is 25 characters by default; see + linkgit:gitweb.conf[5]) single line description of a project (of a + repository). Plain text file; HTML will be escaped. By default set to ++ +------------------------------------------------------------------------------- +Unnamed repository; edit this file to name it for gitweb. +------------------------------------------------------------------------------- ++ +from the template during repository creation, usually installed in +'/usr/share/git-core/templates/'. You can use the `gitweb.description` repo +configuration variable, but the file takes precedence. + +category (or `gitweb.category`):: + Singe line category of a project, used to group projects if + `$projects_list_group_categories` is enabled. By default (file and + configuration variable absent), uncategorized projects are put in the + `$project_list_default_category` category. You can use the + `gitweb.category` repo configuration variable, but the file takes + precedence. ++ +The configuration variables `$projects_list_group_categories` and +`$project_list_default_category` are described in linkgit:gitweb.conf[5] + +cloneurl (or multiple-valued `gitweb.url`):: + File with repository URL (used for clone and fetch), one per line. + Displayed in the project summary page. You can use multiple-valued + `gitweb.url` repository configuration variable for that, but the file + takes precedence. ++ +This is per-repository enhancement / version of global prefix-based +`@git_base_url_list` gitweb configuration variable (see +linkgit:gitweb.conf[5]). + +gitweb.owner:: + You can use the `gitweb.owner` repository configuration variable to set + repository's owner. It is displayed in the project list and summary + page. ++ +If it's not set, filesystem directory's owner is used (via GECOS field, +i.e. real name field from *getpwuid*(3)) if `$projects_list` is unset +(gitweb scans `$projectroot` for repositories); if `$projects_list` +points to file with list of repositories, then project owner defaults to +value from this file for given repository. + +various `gitweb.*` config variables (in config):: + Read description of `%feature` hash for detailed list, and descriptions. + See also "Configuring gitweb features" section in linkgit:gitweb.conf[5] + + +ACTIONS, AND URLS +----------------- +Gitweb can use path_info (component) based URLs, or it can pass all necessary +information via query parameters. The typical gitweb URLs are broken down in to +five components: + +----------------------------------------------------------------------- +.../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments> +----------------------------------------------------------------------- + +repo:: + The repository the action will be performed on. ++ +All actions except for those that list all available projects, +in whatever form, require this parameter. + +action:: + The action that will be run. Defaults to 'projects_list' if repo + is not set, and to 'summary' otherwise. + +revision:: + Revision shown. Defaults to HEAD. + +path:: + The path within the <repository> that the action is performed on, + for those actions that require it. + +arguments:: + Any arguments that control the behaviour of the action. + +Some actions require or allow to specify two revisions, and sometimes even two +pathnames. In most general form such path_info (component) based gitweb URL +looks like this: + +----------------------------------------------------------------------- +.../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments> +----------------------------------------------------------------------- + + +Each action is implemented as a subroutine, and must be present in %actions +hash. Some actions are disabled by default, and must be turned on via feature +mechanism. For example to enable 'blame' view add the following to gitweb +configuration file: + +----------------------------------------------------------------------- +$feature{'blame'}{'default'} = [1]; +----------------------------------------------------------------------- + + +Actions: +~~~~~~~~ +The standard actions are: + +project_list:: + Lists the available Git repositories. This is the default command if no + repository is specified in the URL. + +summary:: + Displays summary about given repository. This is the default command if + no action is specified in URL, and only repository is specified. + +heads:: +remotes:: + Lists all local or all remote-tracking branches in given repository. ++ +The latter is not available by default, unless configured. + +tags:: + List all tags (lightweight and annotated) in given repository. + +blob:: +tree:: + Shows the files and directories in a given repository path, at given + revision. This is default command if no action is specified in the URL, + and path is given. + +blob_plain:: + Returns the raw data for the file in given repository, at given path and + revision. Links to this action are marked 'raw'. + +blobdiff:: + Shows the difference between two revisions of the same file. + +blame:: +blame_incremental:: + Shows the blame (also called annotation) information for a file. On a + per line basis it shows the revision in which that line was last changed + and the user that committed the change. The incremental version (which + if configured is used automatically when JavaScript is enabled) uses + Ajax to incrementally add blame info to the contents of given file. ++ +This action is disabled by default for performance reasons. + +commit:: +commitdiff:: + Shows information about a specific commit in a repository. The 'commit' + view shows information about commit in more detail, the 'commitdiff' + action shows changeset for given commit. + +patch:: + Returns the commit in plain text mail format, suitable for applying with + linkgit:git-am[1]. + +tag:: + Display specific annotated tag (tag object). + +log:: +shortlog:: + Shows log information (commit message or just commit subject) for a + given branch (starting from given revision). ++ +The 'shortlog' view is more compact; it shows one commit per line. + +history:: + Shows history of the file or directory in a given repository path, + starting from given revision (defaults to HEAD, i.e. default branch). ++ +This view is similar to 'shortlog' view. + +rss:: +atom:: + Generates an RSS (or Atom) feed of changes to repository. + + +WEBSERVER CONFIGURATION +----------------------- +This section explains how to configure some common webservers to run gitweb. In +all cases, `/path/to/gitweb` in the examples is the directory you ran installed +gitweb in, and contains `gitweb_config.perl`. + +If you've configured a web server that isn't listed here for gitweb, please send +in the instructions so they can be included in a future release. + +Apache as CGI +~~~~~~~~~~~~~ +Apache must be configured to support CGI scripts in the directory in +which gitweb is installed. Let's assume that it is '/var/www/cgi-bin' +directory. + +----------------------------------------------------------------------- +ScriptAlias /cgi-bin/ "/var/www/cgi-bin/" + +<Directory "/var/www/cgi-bin"> + Options Indexes FollowSymlinks ExecCGI + AllowOverride None + Order allow,deny + Allow from all +</Directory> +----------------------------------------------------------------------- + +With that configuration the full path to browse repositories would be: + + http://server/cgi-bin/gitweb.cgi + +Apache with mod_perl, via ModPerl::Registry +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can use mod_perl with gitweb. You must install Apache::Registry +(for mod_perl 1.x) or ModPerl::Registry (for mod_perl 2.x) to enable +this support. + +Assuming that gitweb is installed to '/var/www/perl', the following +Apache configuration (for mod_perl 2.x) is suitable. + +----------------------------------------------------------------------- +Alias /perl "/var/www/perl" + +<Directory "/var/www/perl"> + SetHandler perl-script + PerlResponseHandler ModPerl::Registry + PerlOptions +ParseHeaders + Options Indexes FollowSymlinks +ExecCGI + AllowOverride None + Order allow,deny + Allow from all +</Directory> +----------------------------------------------------------------------- + +With that configuration the full path to browse repositories would be: + + http://server/perl/gitweb.cgi + +Apache with FastCGI +~~~~~~~~~~~~~~~~~~~ +Gitweb works with Apache and FastCGI. First you need to rename, copy +or symlink gitweb.cgi to gitweb.fcgi. Let's assume that gitweb is +installed in '/usr/share/gitweb' directory. The following Apache +configuration is suitable (UNTESTED!) + +----------------------------------------------------------------------- +FastCgiServer /usr/share/gitweb/gitweb.cgi +ScriptAlias /gitweb /usr/share/gitweb/gitweb.cgi + +Alias /gitweb/static /usr/share/gitweb/static +<Directory /usr/share/gitweb/static> + SetHandler default-handler +</Directory> +----------------------------------------------------------------------- + +With that configuration the full path to browse repositories would be: + + http://server/gitweb + + +ADVANCED WEB SERVER SETUP +------------------------- +All of those examples use request rewriting, and need `mod_rewrite` +(or equivalent; examples below are written for Apache). + +Single URL for gitweb and for fetching +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you want to have one URL for both gitweb and your `http://` +repositories, you can configure Apache like this: + +----------------------------------------------------------------------- +<VirtualHost *:80> + ServerName git.example.org + DocumentRoot /pub/git + SetEnv GITWEB_CONFIG /etc/gitweb.conf + + # turning on mod rewrite + RewriteEngine on + + # make the front page an internal rewrite to the gitweb script + RewriteRule ^/$ /cgi-bin/gitweb.cgi + + # make access for "dumb clients" work + RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \ + /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] +</VirtualHost> +----------------------------------------------------------------------- + +The above configuration expects your public repositories to live under +'/pub/git' and will serve them as `http://git.domain.org/dir-under-pub-git`, +both as cloneable GIT URL and as browseable gitweb interface. If you then +start your linkgit:git-daemon[1] with `--base-path=/pub/git --export-all` +then you can even use the `git://` URL with exactly the same path. + +Setting the environment variable `GITWEB_CONFIG` will tell gitweb to use the +named file (i.e. in this example '/etc/gitweb.conf') as a configuration for +gitweb. You don't really need it in above example; it is required only if +your configuration file is in different place than built-in (during +compiling gitweb) 'gitweb_config.perl' or '/etc/gitweb.conf'. See +linkgit:gitweb.conf[5] for details, especially information about precedence +rules. + +If you use the rewrite rules from the example you *might* also need +something like the following in your gitweb configuration file +('/etc/gitweb.conf' following example): +---------------------------------------------------------------------------- +@stylesheets = ("/some/absolute/path/gitweb.css"); +$my_uri = "/"; +$home_link = "/"; +$per_request_config = 1; +---------------------------------------------------------------------------- +Nowadays though gitweb should create HTML base tag when needed (to set base +URI for relative links), so it should work automatically. + + +Webserver configuration with multiple projects' root +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you want to use gitweb with several project roots you can edit your +Apache virtual host and gitweb configuration files in the following way. + +The virtual host configuration (in Apache configuration file) should look +like this: +-------------------------------------------------------------------------- +<VirtualHost *:80> + ServerName git.example.org + DocumentRoot /pub/git + SetEnv GITWEB_CONFIG /etc/gitweb.conf + + # turning on mod rewrite + RewriteEngine on + + # make the front page an internal rewrite to the gitweb script + RewriteRule ^/$ /cgi-bin/gitweb.cgi [QSA,L,PT] + + # look for a public_git folder in unix users' home + # http://git.example.org/~<user>/ + RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] + + # http://git.example.org/+<user>/ + #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] + + # http://git.example.org/user/<user>/ + #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] + + # defined list of project roots + RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT] + RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \ + [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT] + + # make access for "dumb clients" work + RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \ + /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] +</VirtualHost> +-------------------------------------------------------------------------- + +Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT` +environment variable from a web server, so you need to put the following +line in gitweb configuration file ('/etc/gitweb.conf' in above example): +-------------------------------------------------------------------------- +$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git"; +-------------------------------------------------------------------------- +*Note* that this requires to be set for each request, so either +`$per_request_config` must be false, or the above must be put in code +referenced by `$per_request_config`; + +These configurations enable two things. First, each unix user (`<user>`) of +the server will be able to browse through gitweb git repositories found in +'~/public_git/' with the following url: + + http://git.example.org/~<user>/ + +If you do not want this feature on your server just remove the second +rewrite rule. + +If you already use `mod_userdir` in your virtual host or you don't want to +use the \'~' as first character, just comment or remove the second rewrite +rule, and uncomment one of the following according to what you want. + +Second, repositories found in '/pub/scm/' and '/var/git/' will be accesible +through `http://git.example.org/scm/` and `http://git.example.org/var/`. +You can add as many project roots as you want by adding rewrite rules like +the third and the fourth. + + +PATH_INFO usage +~~~~~~~~~~~~~~~ +If you enable PATH_INFO usage in gitweb by putting +---------------------------------------------------------------------------- +$feature{'pathinfo'}{'default'} = [1]; +---------------------------------------------------------------------------- +in your gitweb configuration file, it is possible to set up your server so +that it consumes and produces URLs in the form + + http://git.example.com/project.git/shortlog/sometag + +i.e. without 'gitweb.cgi' part, by using a configuration such as the +following. This configuration assumes that '/var/www/gitweb' is the +DocumentRoot of your webserver, contains the gitweb.cgi script and +complementary static files (stylesheet, favicon, JavaScript): + +---------------------------------------------------------------------------- +<VirtualHost *:80> + ServerAlias git.example.com + + DocumentRoot /var/www/gitweb + + <Directory /var/www/gitweb> + Options ExecCGI + AddHandler cgi-script cgi + + DirectoryIndex gitweb.cgi + + RewriteEngine On + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule ^.* /gitweb.cgi/$0 [L,PT] + </Directory> +</VirtualHost> +---------------------------------------------------------------------------- +The rewrite rule guarantees that existing static files will be properly +served, whereas any other URL will be passed to gitweb as PATH_INFO +parameter. + +*Notice* that in this case you don't need special settings for +`@stylesheets`, `$my_uri` and `$home_link`, but you lose "dumb client" +access to your project .git dirs (described in "Single URL for gitweb and +for fetching" section). A possible workaround for the latter is the +following: in your project root dir (e.g. '/pub/git') have the projects +named *without* a .git extension (e.g. '/pub/git/project' instead of +'/pub/git/project.git') and configure Apache as follows: +---------------------------------------------------------------------------- +<VirtualHost *:80> + ServerAlias git.example.com + + DocumentRoot /var/www/gitweb + + AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3 + <Directory /var/www/gitweb> + Options ExecCGI + AddHandler cgi-script cgi + + DirectoryIndex gitweb.cgi + + RewriteEngine On + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule ^.* /gitweb.cgi/$0 [L,PT] + </Directory> +</VirtualHost> +---------------------------------------------------------------------------- + +The additional AliasMatch makes it so that + + http://git.example.com/project.git + +will give raw access to the project's git dir (so that the project can be +cloned), while + + http://git.example.com/project + +will provide human-friendly gitweb access. + +This solution is not 100% bulletproof, in the sense that if some project has +a named ref (branch, tag) starting with 'git/', then paths such as + + http://git.example.com/project/command/abranch..git/abranch + +will fail with a 404 error. + + +BUGS +---- +Please report any bugs or feature requests to git@vger.kernel.org, +putting "gitweb" in the subject of email. + +SEE ALSO +-------- +linkgit:gitweb.conf[5], linkgit:git-instaweb[1] + +'gitweb/README', 'gitweb/INSTALL' + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/gitweb/INSTALL b/gitweb/INSTALL index f5efe74..d134ffe 100644 --- a/gitweb/INSTALL +++ b/gitweb/INSTALL @@ -229,7 +229,7 @@ Gitweb config file ------------------ See also "Runtime gitweb configuration" section in README file -for gitweb (in gitweb/README). +for gitweb (in gitweb/README), and gitweb.conf(5) manpage. - You can configure gitweb further using the per-instance gitweb configuration file; by default this is a file named gitweb_config.perl in the same place as @@ -287,97 +287,19 @@ adding the following lines to your $GITWEB_CONFIG: Gitweb repositories ------------------- -- 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 - databases to be more exact). - - You can provide a pre-generated list of [visible] repositories, - together with information about their owners (the project ownership - defaults to the owner of the repository directory otherwise), by setting - the GITWEB_LIST build configuration variable (or the $projects_list - variable in the gitweb config file) to point to a plain file. - - Each line of the projects list file should consist of the url-encoded path - to the project repository database (relative to projectroot), followed - by the url-encoded project owner on the same line (separated by a space). - Spaces in both project path and project owner have to be encoded as either - '%20' or '+'. - - Other characters that have to be url-encoded, i.e. replaced by '%' - followed by two-digit character number in octal, are: other whitespace - characters (because they are field separator in a record), plus sign '+' - (because it can be used as replacement for spaces), and percent sign '%' - (which is used for encoding / escaping). - - You can generate the projects list index file using the project_index - action (the 'TXT' link on projects list page) directly from gitweb. - -- By default, even if a project is not visible on projects list page, you - can view it nevertheless by hand-crafting a gitweb URL. You can set the - GITWEB_STRICT_EXPORT build configuration variable (or the $strict_export - variable in the gitweb config file) to only allow viewing of - repositories also shown on the overview page. - -- Alternatively, you can configure gitweb to only list and allow - viewing of the explicitly exported repositories, via the - GITWEB_EXPORT_OK build configuration variable (or the $export_ok - variable in gitweb config file). If it evaluates to true, gitweb - shows repositories only if this file exists in its object database - (if directory has the magic file named $export_ok). - -- Finally, it is possible to specify an arbitrary perl subroutine that - will be called for each project to determine if it can be exported. - The subroutine receives an absolute path to the project as its only - parameter. - - For example, if you use mod_perl to run the script, and have dumb - http protocol authentication configured for your repositories, you - can use the following hook to allow access only if the user is - authorized to read the files: - - $export_auth_hook = sub { - use Apache2::SubRequest (); - use Apache2::Const -compile => qw(HTTP_OK); - my $path = "$_[0]/HEAD"; - my $r = Apache2::RequestUtil->request; - my $sub = $r->lookup_file($path); - return $sub->filename eq $path - && $sub->status == Apache2::Const::HTTP_OK; - }; - - -Generating projects list using gitweb -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -We assume that GITWEB_CONFIG has its default Makefile value, namely -gitweb_config.perl. Put the following in gitweb_make_index.perl file: - - $GITWEB_CONFIG = "gitweb_config.perl"; - do $GITWEB_CONFIG if -e $GITWEB_CONFIG; - - $projects_list = $projectroot; - -Then create the following script to get list of project in the format -suitable for GITWEB_LIST build configuration variable (or -$projects_list variable in gitweb config): - - #!/bin/sh - - export GITWEB_CONFIG="gitweb_make_index.perl" - export GATEWAY_INTERFACE="CGI/1.1" - export HTTP_ACCEPT="*/*" - export REQUEST_METHOD="GET" - export QUERY_STRING="a=project_index" - - perl -- /var/www/cgi-bin/gitweb.cgi +By default gitweb shows all git repositories under single common repository +root on a local filesystem; see description of GITWEB_PROJECTROOT build-time +configuration variable above (and also of GITWEB_LIST). + +More advanced usage, like limiting access or visibility of repositories and +managing multiple roots are described on gitweb manpage. Example web server configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See also "Webserver configuration" section in README file for gitweb -(in gitweb/README). +See also "Webserver configuration" and "Advanced web server setup" sections +in gitweb(1) manpage. - Apache2, gitweb installed as CGI script, diff --git a/gitweb/README b/gitweb/README index cf528d3..6da4778 100644 --- a/gitweb/README +++ b/gitweb/README @@ -7,9 +7,18 @@ The one working on: From the git version 1.4.0 gitweb is bundled with git. +Build time gitweb configuration +------------------------------- +There are many configuration variables which affect building gitweb (among +others creating gitweb.cgi out of gitweb.perl by replacing placeholders such +as `++GIT_BINDIR++` by their build-time values). + +Building and installing gitweb is described in gitweb's INSTALL file +(in 'gitweb/INSTALL'). + + Runtime gitweb configuration ---------------------------- - Gitweb obtains configuration data from the following sources in the following order: @@ -44,266 +53,19 @@ as comments inside 'gitweb.cgi'. See also gitweb.conf(5) manpage. -Projects list file format -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Instead of having gitweb find repositories by scanning filesystem starting -from $projectroot (or $projects_list, if it points to directory), you can -provide list of projects by setting $projects_list to a text file with list -of projects (and some additional info). This file uses the following -format: - -One record (for project / repository) per line, whitespace separated fields; -does not support (at least for now) lines continuation (newline escaping). -Leading and trailing whitespace are ignored, any run of whitespace can be -used as field separator (rules for Perl's "split(' ', $line)"). Keyed by -the first field, which is project name, i.e. path to repository GIT_DIR -relative to $projectroot. Fields use modified URI encoding, defined in -RFC 3986, section 2.1 (Percent-Encoding), or rather "Query string encoding" -(see http://en.wikipedia.org/wiki/Query_string#URL_encoding), the difference -being that SP (' ') can be encoded as '+' (and therefore '+' has to be also -percent-encoded). Reserved characters are: '%' (used for encoding), '+' -(can be used to encode SPACE), all whitespace characters as defined in Perl, -including SP, TAB and LF, (used to separate fields in a record). - -Currently list of fields is - * <repository path> - path to repository GIT_DIR, relative to $projectroot - * <repository owner> - displayed as repository owner, preferably full name, - or email, or both - -You can additionally use $projects_list file to limit which repositories -are visible, and together with $strict_export to limit access to -repositories (see "Gitweb repositories" section in gitweb/INSTALL). - - -Per-repository gitweb configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can also configure individual repositories shown in gitweb by creating -file in the GIT_DIR of git repository, or by setting some repo configuration -variable (in GIT_DIR/config). - -You can use the following files in repository: - * README.html - A .html file (HTML fragment) which is included on the gitweb project - summary page inside <div> block element. You can use it for longer - description of a project, to provide links (for example to project's - homepage), etc. This is recognized only if XSS prevention is off - ($prevent_xss is false); a way to include a readme safely when XSS - prevention is on may be worked out in the future. - * description (or gitweb.description) - Short (shortened by default to 25 characters in the projects list page) - single line description of a project (of a repository). Plain text file; - HTML will be escaped. By default set to - Unnamed repository; edit this file to name it for gitweb. - from the template during repository creation. You can use the - gitweb.description repo configuration variable, but the file takes - precedence. - * category (or gitweb.category) - Singe line category of a project, used to group projects if - $projects_list_group_categories is enabled. By default (file and - configuration variable absent), uncategorized projects are put in - the $project_list_default_category category. You can use the - gitweb.category repo configuration variable, but the file takes - precedence. - * cloneurl (or multiple-valued gitweb.url) - File with repository URL (used for clone and fetch), one per line. - Displayed in the project summary page. You can use multiple-valued - gitweb.url repository configuration variable for that, but the file - takes precedence. - * gitweb.owner - You can use the gitweb.owner repository configuration variable to set - repository's owner. It is displayed in the project list and summary - page. If it's not set, filesystem directory's owner is used - (via GECOS field / real name field from getpwiud(3)). - * various gitweb.* config variables (in config) - Read description of %feature hash for detailed list, and some - descriptions. - - -Webserver configuration ------------------------ - -If you want to have one URL for both gitweb and your http:// -repositories, you can configure apache like this: - -<VirtualHost *:80> - ServerName git.example.org - DocumentRoot /pub/git - SetEnv GITWEB_CONFIG /etc/gitweb.conf - - # turning on mod rewrite - RewriteEngine on - - # make the front page an internal rewrite to the gitweb script - RewriteRule ^/$ /cgi-bin/gitweb.cgi - - # make access for "dumb clients" work - RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] -</VirtualHost> - -The above configuration expects your public repositories to live under -/pub/git and will serve them as http://git.domain.org/dir-under-pub-git, -both as cloneable GIT URL and as browseable gitweb interface. -If you then start your git-daemon with --base-path=/pub/git --export-all -then you can even use the git:// URL with exactly the same path. - -Setting the environment variable GITWEB_CONFIG will tell gitweb to use -the named file (i.e. in this example /etc/gitweb.conf) as a -configuration for gitweb. Perl variables defined in here will -override the defaults given at the head of the gitweb.perl (or -gitweb.cgi). Look at the comments in that file for information on -which variables and what they mean. - -If you use the rewrite rules from the example you'll likely also need -something like the following in your gitweb.conf (or gitweb_config.perl) file: - - @stylesheets = ("/some/absolute/path/gitweb.css"); - $my_uri = "/"; - $home_link = "/"; - - -Webserver configuration with multiple projects' root ----------------------------------------------------- - -If you want to use gitweb with several project roots you can edit your apache -virtual host and gitweb.conf configuration files like this : - -virtual host configuration : - -<VirtualHost *:80> - ServerName git.example.org - DocumentRoot /pub/git - SetEnv GITWEB_CONFIG /etc/gitweb.conf - - # turning on mod rewrite - RewriteEngine on - - # make the front page an internal rewrite to the gitweb script - RewriteRule ^/$ /cgi-bin/gitweb.cgi [QSA,L,PT] - - # look for a public_git folder in unix users' home - # http://git.example.org/~<user>/ - RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] - - # http://git.example.org/+<user>/ - #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] - - # http://git.example.org/user/<user>/ - #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT] - - # defined list of project roots - RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT] - RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT] - - # make access for "dumb clients" work - RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI} [L,PT] -</VirtualHost> - -gitweb.conf configuration : - -$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git"; - -These configurations enable two things. First, each unix user (<user>) of the -server will be able to browse through gitweb git repositories found in -~/public_git/ with the following url : http://git.example.org/~<user>/ - -If you do not want this feature on your server just remove the second rewrite rule. - -If you already use mod_userdir in your virtual host or you don't want to use -the '~' as first character just comment or remove the second rewrite rule and -uncomment one of the following according to what you want. - -Second, repositories found in /pub/scm/ and /var/git/ will be accesible -through http://git.example.org/scm/ and http://git.example.org/var/. -You can add as many project roots as you want by adding rewrite rules like the -third and the fourth. - - -PATH_INFO usage ------------------------ -If you enable PATH_INFO usage in gitweb by putting - - $feature{'pathinfo'}{'default'} = [1]; - -in your gitweb.conf, it is possible to set up your server so that it -consumes and produces URLs in the form - -http://git.example.com/project.git/shortlog/sometag - -by using a configuration such as the following, that assumes that -/var/www/gitweb is the DocumentRoot of your webserver, and that it -contains the gitweb.cgi script and complementary static files -(stylesheet, favicon): - -<VirtualHost *:80> - ServerAlias git.example.com - - DocumentRoot /var/www/gitweb - - <Directory /var/www/gitweb> - Options ExecCGI - AddHandler cgi-script cgi - - DirectoryIndex gitweb.cgi - - RewriteEngine On - RewriteCond %{REQUEST_FILENAME} !-f - RewriteCond %{REQUEST_FILENAME} !-d - RewriteRule ^.* /gitweb.cgi/$0 [L,PT] - </Directory> -</VirtualHost> - -The rewrite rule guarantees that existing static files will be properly -served, whereas any other URL will be passed to gitweb as PATH_INFO -parameter. - -Notice that in this case you don't need special settings for -@stylesheets, $my_uri and $home_link, but you lose "dumb client" access -to your project .git dirs. A possible workaround for the latter is the -following: in your project root dir (e.g. /pub/git) have the projects -named without a .git extension (e.g. /pub/git/project instead of -/pub/git/project.git) and configure Apache as follows: - -<VirtualHost *:80> - ServerAlias git.example.com - - DocumentRoot /var/www/gitweb - - AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3 - <Directory /var/www/gitweb> - Options ExecCGI - AddHandler cgi-script cgi - - DirectoryIndex gitweb.cgi - - RewriteEngine On - RewriteCond %{REQUEST_FILENAME} !-f - RewriteCond %{REQUEST_FILENAME} !-d - RewriteRule ^.* /gitweb.cgi/$0 [L,PT] - </Directory> -</VirtualHost> - -The additional AliasMatch makes it so that - -http://git.example.com/project.git - -will give raw access to the project's git dir (so that the project can -be cloned), while - -http://git.example.com/project - -will provide human-friendly gitweb access. - -This solution is not 100% bulletproof, in the sense that if some project -has a named ref (branch, tag) starting with 'git/', then paths such as - -http://git.example.com/project/command/abranch..git/abranch - -will fail with a 404 error. +Web server configuration +------------------------ +Gitweb can be run as CGI script, as legacy mod_perl application (using +ModPerl::Registry), and as FastCGI script. You can find some simple examples +in "Example web server configuration" section in INSTALL file for gitweb (in +gitweb/INSTALL). +See "Webserver configuration" and "Advanced web server setup" sections in +gitweb(1) manpage. +AUTHORS +------- Originally written by: Kay Sievers <kay.sievers@vrfy.org> -- 1.7.6 ^ permalink raw reply related [flat|nested] 12+ messages in thread
* [PATCH/RFCv4 4/4] gitweb: Add gitweb manpages to 'gitweb' package in git.spec 2011-09-18 13:34 [PATCH/RFCv4 0/4] Moving gitweb documentation to manpages Jakub Narebski ` (2 preceding siblings ...) 2011-09-18 13:34 ` [PATCH/RFCv4 3/4] gitweb: Add manpage for gitweb Jakub Narebski @ 2011-09-18 13:34 ` Jakub Narebski 3 siblings, 0 replies; 12+ messages in thread From: Jakub Narebski @ 2011-09-18 13:34 UTC (permalink / raw) To: git, Drew Northup Cc: Jonathan Nieder, John 'Warthog9' Hawley, admin, Jakub Narebski This patch follows similar lines in %files section for 'gitk' and 'git-gui' subpackages. Signed-off-by: Jakub Narebski <jnareb@gmail.com> --- New in this version of series... though IIRC this change was present in some version of those patches (probably not as separate patch, though). git.spec.in | 7 +++++++ 1 files changed, 7 insertions(+), 0 deletions(-) diff --git a/git.spec.in b/git.spec.in index 91c8462..dfc5093 100644 --- a/git.spec.in +++ b/git.spec.in @@ -199,7 +199,11 @@ rm -rf $RPM_BUILD_ROOT %files -n gitweb %defattr(-,root,root) +%doc Documentation/*gitweb*.txt %{_datadir}/gitweb +%{!?_without_docs: %{_mandir}/man1/*gitweb*.1*} +%{!?_without_docs: %{_mandir}/man5/*gitweb*.5*} +%{!?_without_docs: %doc Documentation/*gitweb*.html } %files -n perl-Git -f perl-files %defattr(-,root,root) @@ -208,6 +212,9 @@ rm -rf $RPM_BUILD_ROOT # No files for you! %changelog +* Sun Sep 18 2011 Jakub Narebski <jnareb@gmail.com> +- Add gitweb manpages to 'gitweb' subpackage + * Wed Jun 30 2010 Junio C Hamano <gitster@pobox.com> - Add 'gitweb' subpackage. -- 1.7.6 ^ permalink raw reply related [flat|nested] 12+ messages in thread
end of thread, other threads:[~2011-09-22 13:42 UTC | newest] Thread overview: 12+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2011-09-18 13:34 [PATCH/RFCv4 0/4] Moving gitweb documentation to manpages Jakub Narebski 2011-09-18 13:34 ` [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages Jakub Narebski 2011-09-19 23:37 ` Jonathan Nieder 2011-09-20 0:10 ` Jakub Narebski 2011-09-20 20:11 ` Jakub Narebski 2011-09-20 20:19 ` Jonathan Nieder 2011-09-20 20:33 ` Jakub Narebski 2011-09-18 13:34 ` [PATCH/RFCv4 2/4] gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation) Jakub Narebski 2011-09-20 4:41 ` Jonathan Nieder 2011-09-22 13:41 ` Jakub Narebski 2011-09-18 13:34 ` [PATCH/RFCv4 3/4] gitweb: Add manpage for gitweb Jakub Narebski 2011-09-18 13:34 ` [PATCH/RFCv4 4/4] gitweb: Add gitweb manpages to 'gitweb' package in git.spec Jakub Narebski
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).