Git

gitweb 上次更新于 2.50.0

名称

gitweb - Git 网页界面（Git 仓库的 Web 前端）

概要

要开始使用 gitweb，请在 Git 仓库中运行 git-instaweb[1]。这将配置并启动您的 Web 服务器，并运行一个指向 gitweb 的 Web 浏览器。

描述

Gitweb 提供 Git 仓库的 Web 界面。其功能包括：

查看具有公共根目录的多个 Git 仓库。
浏览仓库的每个修订版本。
在任何修订版本下查看仓库中的文件内容。
查看分支的修订日志、文件和目录的历史记录，了解何人、何时、何事发生了更改。
查看任何文件的 blame/annotation 详细信息（如果已启用）。
为任何分支生成提交的 RSS 和 Atom feed。Feed 在现代 Web 浏览器中是自动可发现的。
查看修订版本中所有更改的内容，并逐个修订版本浏览，查看仓库的历史记录。
查找提交消息与给定搜索词匹配的提交。

有关 gitweb 源代码，请参见 https://repo.or.cz/w/git.git/tree/HEAD:/gitweb/，它是使用 gitweb 本身浏览的。

配置

gitweb 的行为的各个方面可以通过配置文件 gitweb_config.perl 或 /etc/gitweb.conf 来控制。有关详细信息，请参见 gitweb.conf[5]。

仓库

Gitweb 可以显示一个或多个 Git 仓库的信息。这些仓库必须都在本地文件系统上，并且必须共享一个公共的仓库根目录，即都位于一个父仓库下（但也请参见“高级 Web 服务器设置”部分，“具有多个项目根目录的 Web 服务器配置”子节）。

our $projectroot = '/path/to/parent/directory';

$projectroot 的默认值为 /pub/git。您可以在构建 gitweb 时通过 GITWEB_PROJECTROOT 构建配置变量进行更改。

默认情况下，$projectroot 下的所有 Git 仓库都对 gitweb 可见并可用。项目列表默认是通过扫描 $projectroot 目录中的 Git 仓库（更准确地说，是对象数据库；gitweb 不关心工作区，最适合显示“裸”仓库）来生成的。

gitweb 中仓库的名称是其 $GIT_DIR（其对象数据库）相对于 $projectroot 的路径。因此，仓库 $repo 可以在 "$projectroot/$repo" 找到。

项目列表文件格式

与其让 gitweb 通过从 $projectroot 开始扫描文件系统来查找仓库，不如通过将 $projects_list 设置为指向一个包含项目列表（及一些额外信息）的纯文本文件，来提供一个预生成的可见项目列表。

该文件使用以下格式：

每行一个记录（用于项目/仓库）；不支持行续接（换行转义）。
忽略前导和尾随空格。
空格分隔的字段；任何连续的空格都可以用作字段分隔符（规则类似于 Perl 的 "split(" ", $line)"）。
字段使用修改后的 URI 编码，该编码定义在 RFC 3986，第 2.1 节（百分比编码）中，或者更确切地说，“查询字符串编码”（请参见 https://en.wikipedia.org/wiki/Query_string#URL_encoding），区别在于 SP (" ") 可以编码为 "+"（因此 "+" 也必须进行百分比编码）。

保留字符是："%"（用于编码），"+"（可用于编码空格），Perl 定义的所有空格字符，包括 SP、TAB 和 LF（用于在记录中分隔字段）。
当前识别的字段有：

<repository path>

仓库 GIT_DIR 的路径，相对于 $projectroot

<repository owner>

显示为仓库所有者，最好是全名，或电子邮件，或两者兼有。

您可以使用项目列表页面上的 project_index 操作（TXT 链接）直接从 gitweb 生成项目列表索引文件；另请参见下面的“使用 gitweb 生成项目列表”部分。

示例内容

foo.git       Joe+R+Hacker+<joe@example.com>
foo/bar.git   O+W+Ner+<owner@example.org>

默认情况下，此文件仅控制哪些项目在项目列表页面上**可见**（请注意，指向正确识别的 Git 仓库的条目将不会被 gitweb 显示）。即使项目在项目列表页面上不可见，您仍然可以通过手动构造 gitweb URL 来查看它。通过将 $strict_export 配置变量（参见 gitweb.conf[5]）设置为 true 值，您可以仅允许查看在概述页面上显示的仓库（即，只有在项目列表中明确列出的项目才是可访问的）。

使用 gitweb 生成项目列表

我们假设 GITWEB_CONFIG 具有默认的 Makefile 值，即 gitweb_config.perl。将以下内容放入 gitweb_make_index.perl 文件中：

read_config_file("gitweb_config.perl");
$projects_list = $projectroot;

然后创建以下脚本以获取适合 GITWEB_LIST 构建配置变量（或 gitweb 配置中的 $projects_list 变量）格式的项目列表：

#!/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

运行此脚本并将输出保存到文件中。然后可以使用此文件作为项目列表文件，这意味着您可以将 $projects_list 设置为其文件名。

控制对 Git 仓库的访问

默认情况下，$projectroot 下的所有 Git 仓库都对 gitweb 可见并可用。但是，您可以配置 gitweb 如何控制对仓库的访问。

如“项目列表文件格式”部分所述，您可以通过选择性地将仓库包含在项目列表文件中，并将 $projects_list gitweb 配置变量设置为指向它来控制哪些项目**可见**。当 $strict_export 设置为 true 时，项目列表文件也可以用来控制哪些仓库**可用**。
您可以通过 gitweb 配置文件中的 $export_ok 变量配置 gitweb，使其仅列出并允许查看已显式导出的仓库；请参见 gitweb.conf[5] manpage。如果它求值为 true，则 gitweb 仅在名为 $export_ok 的文件存在于其对象数据库中（如果目录中存在名为 $export_ok 的魔术文件）时显示仓库。

例如，git-daemon[1] 默认情况下（除非使用 --export-all 选项）仅允许为具有 git-daemon-export-ok 文件的仓库进行拉取。添加：
```
our $export_ok = "git-daemon-export-ok";
```
可以使 gitweb 仅显示并允许访问可以通过 git:// 协议获取的仓库。
最后，可以指定一个任意的 perl 子例程，该子例程将为每个仓库调用，以确定它是否可以导出。该子例程将其作为唯一参数接收的项目的绝对路径（即 "projectroot/$project"）。

例如，如果您使用 mod_perl 运行脚本，并为您的仓库配置了哑 HTTP 协议身份验证，则可以使用以下钩子仅在用户有权读取文件时允许访问：
```
$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;
};
```

每个仓库的 gitweb 配置

您可以通过在 Git 仓库的 GIT_DIR 中创建文件，或通过在 GIT_DIR/config 中设置某些仓库配置变量（参见 git-config[1]）来配置 gitweb 中显示的单个仓库。

您可以在仓库中使用以下文件：

README.html

一个 HTML 文件（HTML 片段），它被包含在 gitweb 项目的“摘要”页面中，位于 <div> 块元素内。您可以使用它来提供项目的详细描述，提供链接（例如到项目的首页），等等。仅当 XSS 防护关闭时（$prevent_xss 为 false，参见 gitweb.conf[5]）才会识别此文件；未来可能会考虑在 XSS 防护开启时安全地包含 README 的方法。

description（或 gitweb.description）

项目（仓库）的单行简短描述（在项目列表页面上截断为 $projects_list_description_width，默认为 25 个字符；参见 gitweb.conf[5]）。纯文本文件；HTML 将被转义。默认设置为：

Unnamed repository; edit this file to name it for gitweb.

从仓库创建模板中设置，通常安装在 /usr/share/git-core/templates/。您可以使用 gitweb.description 仓库配置变量，但文件具有优先权。

category（或 gitweb.category）

项目的单行类别，用于在 $projects_list_group_categories 启用时对项目进行分组。默认情况下（文件和配置变量不存在），未分类的项目被放入 $project_list_default_category 类别。您可以使用 gitweb.category 仓库配置变量，但文件具有优先权。

$projects_list_group_categories 和 $project_list_default_category 配置变量在 gitweb.conf[5] 中有描述。

cloneurl（或多值 gitweb.url）

包含仓库 URL（用于克隆和获取）的文件，每行一个。在项目摘要页面上显示。您可以为此使用多值 gitweb.url 仓库配置变量，但文件具有优先权。

这是全局基于前缀的 @git_base_url_list gitweb 配置变量的每个仓库增强/版本（请参见 gitweb.conf[5]）。

gitweb.owner

您可以使用 gitweb.owner 仓库配置变量来设置仓库的所有者。它会显示在项目列表和摘要页面上。

如果未设置，则使用文件系统目录的所有者（通过 GECOS 字段，即 **getpwuid**(3) 中的真实姓名字段），如果 $projects_list 未设置（gitweb 扫描 $projectroot 中的仓库）；如果 $projects_list 指向包含仓库列表的文件，则项目所有者默认为该文件中给定仓库的值。

各种 gitweb.* 配置变量（在 config 中）

阅读 %feature 哈希的描述以获取详细列表和说明。另请参见 gitweb.conf[5] 中“配置 gitweb 功能”部分。

操作和 URL

Gitweb 可以使用 path_info（组件） URL，或者可以通过查询参数传递所有必要的信息。典型的 gitweb URL 分为五个组件：

.../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments>

repo: 将执行操作的仓库。

除列出所有可用项目（以任何形式）的操作外，所有操作都需要此参数。
action: 将要运行的操作。如果未设置 repo，则默认为 projects_list；否则默认为 summary。
revision: 显示的修订版本。默认为 HEAD。
path: 对于需要它的操作，在 <repository> 中的路径，操作将在该路径上执行。
arguments: 控制操作行为的任何参数。

一些操作需要或允许指定两个修订版本，有时甚至两个路径名。在最通用的形式下，这样的 path_info（组件）基于的 gitweb URL 如下所示：

.../gitweb.cgi/<repo>/<action>/<revision-from>:/<path-from>..<revision-to>:/<path-to>?<arguments>

每个操作都实现为一个子例程，并且必须存在于 %actions 哈希中。一些操作默认是禁用的，必须通过 feature 机制启用。例如，要启用 blame 视图，请将以下内容添加到 gitweb 配置文件中：

$feature{'blame'}{'default'} = [1];

操作

标准操作有：

project_list: 列出可用的 Git 仓库。如果没有在 URL 中指定仓库，这就是默认命令。
summary: 显示给定仓库的摘要。如果在 URL 中未指定操作，并且只指定了仓库，这就是默认命令。
heads
remotes: 列出给定仓库中的所有本地或所有远程跟踪分支。

后者默认不可用，除非配置。
tags: 列出给定仓库中的所有标签（轻量级和注解式）。
blob
tree: 显示给定修订版本下，给定仓库路径中的文件和目录。如果在 URL 中未指定操作，且指定了路径，这就是默认命令。
blob_plain: 返回给定仓库、给定路径和修订版本中文件的原始数据。指向此操作的链接标记为 raw。
blobdiff: 显示同一文件两个修订版本之间的差异。
blame
blame_incremental: 显示文件的 blame（也称为 annotation）信息。逐行显示该行最后更改的修订版本和提交更改的用户。增量版本（如果已配置，则在启用 JavaScript 时自动使用）使用 Ajax 逐步将 blame 信息添加到给定文件的内容中。

此操作默认禁用，以提高性能。
commit
commitdiff: 显示仓库中特定提交的信息。commit 视图更详细地显示提交信息，commitdiff 操作显示给定提交的变更集。
patch: 以纯文本邮件格式返回提交，适合使用 git-am[1] 进行应用。
tag: 显示特定的注解式标签（tag object）。
log
shortlog: 显示给定分支（从给定修订版本开始）的日志信息（提交消息或仅提交主题）。

shortlog 视图更紧凑；它每行显示一个提交。
history: 显示给定仓库路径下，文件或目录的历史记录，从给定修订版本开始（默认为 HEAD，即默认分支）。

此视图类似于 shortlog 视图。
rss
atom: 生成仓库更改的 RSS（或 Atom）feed。

Web 服务器配置

本节介绍如何配置一些常用 Web 服务器来运行 gitweb。在所有情况下，示例中的 /path/to/gitweb 是您安装 gitweb 的目录，并且包含 gitweb_config.perl。

如果您配置了一个此处未列出的 Web 服务器来运行 gitweb，请发送说明，以便在未来的版本中包含它们。

Apache 作为 CGI

Apache 必须配置为支持 gitweb 安装目录中的 CGI 脚本。假设它位于 /var/www/cgi-bin 目录。

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>

有了此配置，浏览仓库的完整路径将是：

http://server/cgi-bin/gitweb.cgi

Apache 与 mod_perl，通过 ModPerl::Registry

您可以使用 mod_perl 运行 gitweb。您必须安装 Apache::Registry（对于 mod_perl 1.x）或 ModPerl::Registry（对于 mod_perl 2.x）以启用此支持。

假设 gitweb 安装在 /var/www/perl，以下 Apache 配置（对于 mod_perl 2.x）是合适的。

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>

有了此配置，浏览仓库的完整路径将是：

http://server/perl/gitweb.cgi

Apache 与 FastCGI

Gitweb 与 Apache 和 FastCGI 协同工作。首先，您需要重命名、复制或符号链接 gitweb.cgi 为 gitweb.fcgi。假设 gitweb 安装在 /usr/share/gitweb 目录。以下 Apache 配置是合适的（未经测试！）：

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>

有了此配置，浏览仓库的完整路径将是：

http://server/gitweb

高级 Web 服务器设置

所有这些示例都使用请求重写，需要 mod_rewrite（或同等功能；下面的示例是为 Apache 编写的）。

用于 gitweb 和获取的单一 URL

如果您希望 gitweb 和您的 http:// 仓库使用同一个 URL，您可以这样配置 Apache：

<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>

上面的配置期望您的公共仓库位于 /pub/git 下，并将它们作为可克隆的 Git URL 和可浏览的 gitweb 接口提供，形式为 http://git.domain.org/dir-under-pub-git。如果您然后使用 --base-path=/pub/git --export-all 选项启动您的 git-daemon[1]，您甚至可以使用具有完全相同路径的 git:// URL。

设置环境变量 GITWEB_CONFIG 将告诉 gitweb 使用指定的配置文件（即，本例中的 /etc/gitweb.conf）作为 gitweb 的配置。在上面的示例中，您并不真正需要它；只有当您的配置文件位于与内置的（在编译 gitweb 时）gitweb_config.perl 或 /etc/gitweb.conf 不同的位置时，才需要它。请参见 gitweb.conf[5] 以获取详细信息，特别是关于优先级规则的信息。

如果您使用示例中的重写规则，您**可能**还需要在您的 gitweb 配置文件（/etc/gitweb.conf，按照示例）中添加类似以下内容：

@stylesheets = ("/some/absolute/path/gitweb.css");
$my_uri    = "/";
$home_link = "/";
$per_request_config = 1;

不过，如今 gitweb 应该在需要时创建 HTML base 标签（以设置相对链接的 base URI），所以它应该可以自动工作。

具有多个项目根目录的 Web 服务器配置

如果您想将 gitweb 与多个项目根目录一起使用，可以按以下方式编辑您的 Apache 虚拟主机和 gitweb 配置文件。

虚拟主机配置（在 Apache 配置文件中）应如下所示：

<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 directory 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>

此处实际项目根目录通过 Web 服务器的 GITWEB_PROJECT_ROOT 环境变量传递给 gitweb，因此您需要在 gitweb 配置文件（上面的示例中是 /etc/gitweb.conf）中添加以下行：

$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";

注意，这需要为每个请求设置，所以 $per_request_config 必须为 false，或者上面的内容必须放在由 $per_request_config 引用的代码中；

这些配置启用了两件事。首先，服务器的每个 Unix 用户（<user>）都将能够通过以下 URL 在 gitweb Git 仓库中浏览 ~/public_git/：

http://git.example.org/~<user>/

如果您不希望在服务器上启用此功能，只需删除第二个重写规则。

如果您已经在虚拟主机中使用 mod_userdir，或者您不想使用 '~' 作为第一个字符，只需注释掉或删除第二个重写规则，然后根据您的需要取消注释以下任一规则。

其次，位于 /pub/scm/ 和 /var/git/ 的仓库将可以通过 http://git.example.org/scm/ 和 http://git.example.org/var/ 访问。您可以通过添加类似第三个和第四个的重写规则来添加任意数量的项目根目录。

PATH_INFO 用法

如果您通过在 gitweb 配置文件中放置以下内容来启用 PATH_INFO 用法：

$feature{'pathinfo'}{'default'} = [1];

在您的 gitweb 配置文件中，可以设置您的服务器，使其能够处理和生成以下形式的 URL：

http://git.example.com/project.git/shortlog/sometag

即，不带 gitweb.cgi 部分，通过使用以下配置。此配置假定 /var/www/gitweb 是您 Web 服务器的 DocumentRoot，其中包含 gitweb.cgi 脚本和辅助静态文件（样式表、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>

重写规则确保现有的静态文件将被正确提供，而任何其他 URL 将作为 PATH_INFO 参数传递给 gitweb。

注意，在这种情况下，您不需要为 @stylesheets、$my_uri 和 $home_link 设置特殊参数，但您会失去对项目 .git 目录的“哑客户端”访问（在“用于 gitweb 和获取的单一 URL”部分中描述）。后一种情况的一个可能解决方法是：在您的项目根目录（例如 /pub/git）中，项目名称**不**包含 .git 扩展名（例如 /pub/git/project 而不是 /pub/git/project.git），并像这样配置 Apache：

<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>

额外的 AliasMatch 使得：

http://git.example.com/project.git

将提供对项目 Git 目录的原始访问（以便可以克隆该项目），而：

http://git.example.com/project

将提供人类友好的 gitweb 访问。

此解决方案并非 100% 万无一失，因为如果某个项目有一个以 git/ 开头的命名引用（分支、标签），那么像这样的路径：

http://git.example.com/project/command/abranch..git/abranch

将因 404 错误而失败。

BUG

请向 git@vger.kernel.org 报告任何错误或功能请求，并在邮件主题中注明“gitweb”。

另请参阅

gitweb.conf[5], git-instaweb[1]

gitweb/README, gitweb/INSTALL

Git[1] 套件的一部分

设置和配置

获取和创建项目

基本快照

分支与合并

共享和更新项目

检查和比较

打补丁

调试

电子邮件

外部系统

服务器管理

指南

管理

底层命令

名称

概要

描述

配置

仓库

项目列表文件格式

使用 gitweb 生成项目列表

控制对 Git 仓库的访问

每个仓库的 gitweb 配置

操作和 URL

操作

Web 服务器配置

Apache 作为 CGI

Apache 与 mod_perl，通过 ModPerl::Registry

Apache 与 FastCGI

高级 Web 服务器设置

用于 gitweb 和获取的单一 URL

具有多个项目根目录的 Web 服务器配置

PATH_INFO 用法

BUG

另请参阅

GIT

gitweb