Documentation/config-gitweb.txt

Gerrit Code Review - Gitweb Integration
=======================================

Gerrit Code Review can manage and generate hyperlinks to gitweb,
allowing users to jump from Gerrit content to the same information,
but shown by gitweb.


Internal/Managed gitweb
-----------------------

In the internal configuration, Gerrit inspects the request, enforces
its project level access controls, and directly executes `gitweb.cgi`
if the user is authorized to view the page.

To enable the internal configuration, set
link:config-gerrit.html#gitweb.cgi[gitweb.cgi] with the path of the
installed CGI.  This defaults to `/usr/lib/cgi-bin/gitweb.cgi`,
which is a common installation path for the 'gitweb' package on
Linux distributions.

====
  git config --file $site_path/etc/gerrit.config gitweb.cgi /usr/lib/cgi-bin/gitweb.cgi
  git config --file $site_path/etc/gerrit.config --unset gitweb.url
====

Alternatively, if Gerrit is served behind reverse proxy, it can
generate different URLs for gitweb's links (they need to be
rewritten to `<gerrit>/gitweb?args` on the web server). This allows
for serving gitweb under a different URL than the Gerrit instance.
To enable this feature, set both: `gitweb.cgi` and `gitweb.url`.

====
  git config --file $site_path/etc/gerrit.config gitweb.cgi /usr/lib/cgi-bin/gitweb.cgi
  git config --file $site_path/etc/gerrit.config gitweb.url /pretty/path/to/gitweb
====

After updating `'$site_path'/etc/gerrit.config`, the Gerrit server must
be restarted and clients must reload the host page to see the change.

Configuration
~~~~~~~~~~~~~

Most of the gitweb configuration file is handled automatically
by Gerrit Code Review.  Site specific overrides can be placed in
`'$site_path'/etc/gitweb_config.perl`, as this file is loaded as
part of the generated configuration file.

Logo and CSS
~~~~~~~~~~~~

If the package-manager installed CGI (`/usr/lib/cgi-bin/gitweb.cgi`)
is being used, the stock CSS and logo files will be served from
either `/usr/share/gitweb` or `/var/www`.

Otherwise, Gerrit expects `gitweb.css` and `git-logo.png` to be found
in the same directory as the CGI script itself.  This matches with
the default source code distribution, and most custom installations.

Access Control
~~~~~~~~~~~~~~

Access controls for internally managed gitweb page views are enforced
using the standard project READ +1 permission.


External/Unmanaged gitweb
-------------------------

In the external configuration, gitweb runs under the control of an
external web server, and Gerrit access controls are not enforced.

To enable the external gitweb integration, set
link:config-gerrit.html#gitweb.url[gitweb.url] with the URL of your
gitweb CGI.

The CGI's `$projectroot` should be the same directory as
gerrit.basePath, or a fairly current replica.  If a replica is
being used, ensure it uses a full mirror, so the `refs/changes/*`
namespace is available.

====
  git config --file $site_path/etc/gerrit.config gitweb.url http://example.com/gitweb.cgi
  git config --file $site_path/etc/gerrit.config --unset gitweb.cgi
====

After updating `'$site_path'/etc/gerrit.config`, the Gerrit server must
be restarted and clients must reload the host page to see the change.

Access Control
~~~~~~~~~~~~~~

Gitweb access controls can be implemented using standard web server
access controls.  This isn't typically integrated with Gerrit's own
access controls.  Caution must be taken to ensure the controls are
consistent if access needs to be restricted.

Caching Gitweb
~~~~~~~~~~~~~~

If your repository set is large and you are expecting a lot
of users, you may want to look at the caching forks used by
high-traffic sites like kernel.org or repo.or.cz.

Alternatives to gitweb
~~~~~~~~~~~~~~~~~~~~~~
There are other alternatives to gitweb that can also be used with
Gerrit, such as cgit.

cgit can be used by specifying `gitweb.type` to be 'cgit'.

It is also possible to define custom patterns.

See Also
--------

* link:config-gerrit.html#gitweb[Section gitweb]
* link:http://hjemli.net/git/cgit/[cgit]

GERRIT
------
Part of link:index.html[Gerrit Code Review]