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 浏览器可以自动发现这些订阅源。
查看修订版本中的所有变更，并逐个遍历修订版本，查看仓库历史记录。
查找提交信息符合给定搜索词的提交。

请访问 https://repo.or.cz/w/git.git/tree/HEAD:/gitweb/ 获取 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 中仓库的名称是相对于 $projectroot 的其 $GIT_DIR（对象数据库）路径。因此，仓库 $repo 可以在 "$projectroot/$repo" 处找到。

项目列表文件格式

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

该文件使用以下格式：

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

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

<仓库路径>

相对于 $projectroot 的仓库 GIT_DIR 路径

<仓库所有者>

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

您可以直接从 gitweb 使用 project_index 操作（项目列表页上的 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 配置文件中的 $export_ok 变量配置 gitweb 仅列出并允许查看明确导出的仓库；参见 gitweb.conf[5] 手册页。如果其计算结果为真，则 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 哈希中。某些操作默认是禁用的，必须通过功能机制开启。例如，要启用 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（也称为注释）信息。它逐行显示该行最后一次更改的修订版本以及提交该更改的用户。增量版本（如果已配置，则在启用 JavaScript 时自动使用）使用 Ajax 将 blame 信息增量添加到给定文件的内容中。

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

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

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

WEBSERVER 配置

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

如果您配置的 Web 服务器未在此处列出，请提交说明，以便将其包含在未来的版本中。

作为 CGI 的 Apache

必须配置 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

带有 ModPerl::Registry 的 mod_perl 的 Apache

您可以将 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

带有 FastCGI 的 Apache

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>）都能够通过以下 url 浏览在 ~/public_git/ 中找到的 gitweb 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 配置文件中放入：

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

来启用 gitweb 中的 PATH_INFO 使用，则可以设置您的服务器，使其使用并生成如下形式的 URL：

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

即没有 gitweb.cgi 部分，通过使用如下配置。此配置假设 /var/www/gitweb 是您 Web 服务器的 DocumentRoot，包含 gitweb.cgi 脚本和配套的静态文件（样式表、图标、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

操作

WEBSERVER 配置

作为 CGI 的 Apache

带有 ModPerl::Registry 的 mod_perl 的 Apache

带有 FastCGI 的 Apache

高级 WEB 服务器设置

gitweb 和获取的单一 URL

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

PATH_INFO 的使用

BUG

另请参阅

GIT

gitweb