From: Drew Northup <drew.northup@xxxxxxxxx> This is a work in progress. Much of what is in it has been pulled directly from the README and INSTALL files of gitweb. Some effort has been made to de-duplicate any of this. To build gitweb documentation you can use make -C gitweb doc or cd gitweb; make doc TODO: * Clean up README and INSTALL files * Remove or rephrase redundant portions of original documentation * A lot more... Signed-off-by: Drew Northup <drew.northup@xxxxxxxxx> Signed-off-by: Jakub Narebski <jnareb@xxxxxxxxx> --- Differences from previous version (v2): * Much simpler "doc" target in gitweb/Makefile. Now instead of duplicating internal knowledge how Documentation/Makefile works we simply delegate task to "gitweb-doc" target (a la "full-svn-test" in t/Makefile) in Documentation/Makefile. The "gitweb-doc" target is implemented in 2 lines, compared to previous version which needed 7 lines in gitweb's Makefile. Thanks Junio for this bit of sanity. * Added documentation: $project_maxdepth, %highlight_ext etc., new after rebase $project_list_group_categories etc. * New chapter "Configuring gitweb features" about %feature hash. * Link to non-existent yet linkgit:gitweb[1] (introduced in next commit). * Removed duplicated contents from gitweb/README - By accident moved change to git.spec.in to next commit. But perhaps it is better here, or even better in a separate commit on top of series. Documentation/Makefile | 7 +- Documentation/gitweb.conf.txt | 716 +++++++++++++++++++++++++++++++++++++++++ gitweb/Makefile | 7 +- gitweb/README | 133 +-------- 4 files changed, 728 insertions(+), 135 deletions(-) create mode 100644 Documentation/gitweb.conf.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index 36989b7..68d0ebb 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 gitrevisions.txt gitworkflows.txt @@ -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 @@ -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 diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt new file mode 100644 index 0000000..2bfe2e5 --- /dev/null +++ b/Documentation/gitweb.conf.txt @@ -0,0 +1,716 @@ +gitweb.conf(5) +============== + +NAME +---- +gitweb.conf - Gitweb configuration file + +SYNOPSIS +-------- +[verse] +'/etc/gitweb.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 +---------- +The location of system-wide gitweb configuration file is defined at compile +time using the configuration value `GITWEB_CONFIG_SYSTEM` and defaults to +'/etc/gitweb.conf'. The name of the per-instance configuration file is +defined in gitweb by `GITWEB_CONFIG`, and defaults to 'gitweb_config.perl' +(relative path means located in the same directory gitweb is installed). +System-wide configuration file is a fallback for when per-instance +configuration file does not exist. + +You can override location of both system-wide and per-instance configuration +file by setting respectively environmental variables `GITWEB_CONFIG_SYSTEM` +and `GITWEB_CONFIG` to non-empty value. + +Values defined in configuration files override built-in values found in the +gitweb CGI. + +*NOTE:* If per-instance configuration file ('gitweb_config.perl') exists, +then system-wide configuration file ('/etc/gitweb.conf') is _not used at +all_!!! + +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. + +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. + + *Note* that 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. + + [Default: 'highlight'] + +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. + +*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. + +[Default: true] + +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-rep[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 system-wide configuration file. This file is read + only if per-instance one does not exist. + +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 system-wide configuration file. This file + is used only if per-instance configuration variable is not found. + +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/Makefile b/gitweb/Makefile index 5d20515..dfdefef 100644 --- a/gitweb/Makefile +++ b/gitweb/Makefile @@ -172,6 +172,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 @@ -185,5 +190,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 diff --git a/gitweb/README b/gitweb/README index a4cfcb4..1e6cf27 100644 --- a/gitweb/README +++ b/gitweb/README @@ -20,139 +20,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.5 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html