SYNOPSIS

To get started with gitweb, run git-instaweb(1) from a Git repository. This will configure and start your web server, and run a web browser pointing to gitweb.

DESCRIPTION

Gitweb provides a web interface to Git repositories. Its 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, seeing what was changed, when, and by whom.

  • 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 stepping through revisions one at a time, viewing the history of the repository.

  • Finding commits whose commit messages match a given search term.

See https://repo.or.cz/w/git.git/tree/HEAD:/gitweb/ for gitweb source code, browsed using gitweb itself.

CONFIGURATION

Various aspects of gitweb’s behavior can be controlled through the configuration file gitweb_config.perl or /etc/gitweb.conf. See the 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 a common repository root, i.e. be all under a single parent repository (but see also the "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 the 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 the repository in gitweb is the path to its $GIT_DIR (its 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 the 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 https://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 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+<[email protected]>
foo/bar.git   O+W+Ner+<[email protected]>

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