Git

gitweb 上次更新于 2.47.0

名称

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

概要

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

描述

Gitweb 提供了 Git 仓库的 web 界面。其功能包括

查看具有共同根的多个 Git 仓库。
浏览仓库的每个修订版本。
查看仓库中任何修订版本的文件内容。
查看分支的修订日志、文件和目录的历史记录，查看更改的内容、时间和人员。
查看任何文件的 blame/annotation 详细信息（如果已启用）。
为任何分支生成提交的 RSS 和 Atom feed。这些 feed 在现代 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 服务器设置”部分，“具有多个项目根目录的 Webserver 配置”子部分）。

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 (" ") 可以编码为 "+"（因此 "+" 也必须进行百分比编码）。

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

<仓库路径>

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

<仓库所有者>

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

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

示例内容

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

默认情况下，此文件仅控制哪些项目在项目列表页面上是**可见的**（请注意，gitweb 不会显示不指向正确识别的 Git 仓库的条目）。即使项目在项目列表页面上不可见，你仍然可以通过手工制作 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] 手册页。如果它评估为 true，则 gitweb 仅显示仓库，如果此 $export_ok 命名的文件存在于其对象数据库中（如果目录具有名为 $export_ok 的 magic 文件）。

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

例如，如果你使用 mod_perl 运行脚本，并且为你的仓库配置了 dumb 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 项目“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 哈希的详细列表和描述。另请参阅 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）源。

WEB 服务器配置

本节介绍如何配置一些常见的 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

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

如果想要一个 URL 用于 gitweb 和你的 http:// 仓库，你可以这样配置 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 界面。如果你然后启动你的 git-daemon[1]，并使用 --base-path=/pub/git --export-all，那么你甚至可以使用具有完全相同路径的 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 配置文件中添加以下内容来启用 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 访问。

这个解决方案不是 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

通过 ModPerl::Registry 使用 mod_perl 的 Apache

使用 FastCGI 的 Apache

高级 WEB 服务器设置

用于 gitweb 和获取的单个 URL

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

PATH_INFO 的使用

BUG

参见

GIT

gitweb