Git

gitweb 最后更新于 2.50.0

名称

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

概要

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

描述

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

查看具有共同根目录的多个 Git 仓库。
浏览仓库的每个修订版本。
查看仓库中任意修订版本的文件内容。
查看分支的修订日志、文件和目录的历史记录，查看何时、何人更改了什么。
查看任何文件的 blame/annotation 详情（如果已启用）。
为任何分支生成提交的 RSS 和 Atom 订阅源。这些订阅源在现代 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”找到。

项目列表文件格式

您可以将 $projects_list 设置为指向一个包含项目列表（以及一些附加信息）的纯文本文件，而不是让 gitweb 通过从 $projectroot 开始扫描文件系统来查找仓库。

该文件使用以下格式：

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

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

<仓库路径>

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

<仓库所有者>

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

您可以直接从 gitweb 使用 project_index action（项目列表页面上的 TXT 链接）生成项目列表索引文件；另请参阅下面的“使用 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，项目列表文件也可以用来控制哪些仓库是 可用的。
您可以配置 gitweb 仅列出并允许查看显式导出的仓库，通过 gitweb 配置文件中的 $export_ok 变量；请参阅 gitweb.conf[5] 手册页。如果它评估为 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 协议身份验证，则可以使用以下 hook 来仅在用户被授权读取文件时才允许访问
```
$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 项目“summary”页面内的 <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 hash 的描述以获取详细列表和描述。另请参阅 gitweb.conf[5] 中“Configuring gitweb features”部分。

动作和 URL

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

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

repo: 将执行操作的仓库。

除列出所有可用项目的操作外，无论何种形式，都需要此参数。
action: 将要运行的动作。如果未设置 repo，则默认为 projects_list；否则默认为 summary。
revision: 显示的修订版本。默认为 HEAD。
path: 在 <仓库> 内执行操作的路径，适用于需要此路径的动作。
arguments: 控制动作行为的任何参数。

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

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

每个动作都作为一个子例程实现，并且必须存在于 %actions hash 中。某些动作默认禁用，必须通过 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 对象）。
log
shortlog: 显示给定分支的日志信息（提交消息或仅提交主题）（从给定修订版本开始）。

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

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

WEBSERVER 配置

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

如果您为 gitweb 配置了此处未列出的 web 服务器，请发送说明以便将其包含在未来的版本中。

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 下，并将它们作为 http://git.domain.org/dir-under-pub-git 提供服务，既作为可克隆的 Git URL，也作为可浏览的 gitweb 界面。如果您随后使用 --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 标签（用于设置相对链接的基础 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>）都将能够通过 gitweb 浏览在 ~/public_git/ 中找到的 Git 仓库，使用以下 URL：

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

如果您不希望在您的服务器上使用此功能，只需删除第二条重写规则即可。

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

其次，在 /pub/scm/ 和 /var/git/ 中找到的仓库将可通过 http://git.example.org/scm/ 和 http://git.example.org/var/ 访问。您可以通过添加像第三条和第四条这样的重写规则来添加任意数量的项目根目录。

PATH_INFO 用法

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

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

可以设置您的服务器，使其使用并生成以下形式的 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 访问。

这个解决方案并非百分之百万无一失，因为如果某个项目有一个以 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

动作

WEBSERVER 配置

Apache 作为 CGI

Apache 与 mod_perl，通过 ModPerl::Registry

Apache 与 FastCGI

高级 Web 服务器设置

gitweb 和获取的单一 URL

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

PATH_INFO 用法

BUG

另请参阅

GIT

gitweb