Git

gitweb 最后更新于 2.47.0

名称

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

概要

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

描述

Gitweb 为 Git 存储库提供了一个 Web 界面。其功能包括

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

请参阅 https://repo.or.cz/w/git.git/tree/HEAD:/gitweb/ 以获取 gitweb 源代码，使用 gitweb 本身进行浏览。

配置

可以通过配置文件 gitweb_config.perl 或 /etc/gitweb.conf 控制 gitweb 行为的各个方面。有关详细信息，请参阅 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)”规则）。
字段使用 RFC 3986 第 2.1 节（百分比编码）中定义的修改后的 URI 编码，或者更确切地说“查询字符串编码”（请参阅 https://en.wikipedia.org/wiki/Query_string#URL_encoding），区别在于 SP（“ ”）可以编码为“+”（因此“+”也必须进行百分比编码）。

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

<存储库路径>

存储库 GIT_DIR 相对于 $projectroot 的路径

<存储库所有者>

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

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

示例内容

foo.git       Joe+R+Hacker+<[email protected]>
foo/bar.git   O+W+Ner+<[email protected]>

默认情况下，此文件仅控制哪些项目在项目列表页面上可见（请注意，不指向正确识别的 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，则只有当 $export_ok 指定的文件存在于其对象数据库中时（如果目录具有名为 $export_ok 的幻数文件），gitweb 才会显示存储库。

例如，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仓库配置变量来设置仓库的所有者。它显示在项目列表和摘要页面中。

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

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

阅读%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: 显示文件的归责（也称为注释）信息。它基于逐行显示最后更改该行的修订版本以及提交更改的用户。增量版本（如果已配置，则在启用 JavaScript 时自动使用）使用 Ajax 将归责信息增量添加到给定文件的内容中。

出于性能原因，此操作默认情况下处于禁用状态。
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

使用 mod_perl 的 Apache，通过 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

使用 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 配置文件中添加以下内容，从而启用 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 错误。

错误

请将任何错误或功能请求报告给[email protected]，并在电子邮件主题中加上“gitweb”。

另请参阅

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

gitweb/README，gitweb/INSTALL

是 git[1] 套件的一部分

设置和配置

获取和创建项目

基本快照

分支和合并

共享和更新项目

检查和比较

修补

调试

电子邮件

外部系统

服务器管理员

指南

管理

底层命令

名称

概要

描述

配置

存储库

项目列表文件格式

使用 gitweb 生成项目列表

控制对 Git 存储库的访问

每个存储库的 gitweb 配置

操作和 URL

操作

Web 服务器配置

Apache 作为 CGI

使用 mod_perl 的 Apache，通过 ModPerl::Registry

使用 FastCGI 的 Apache

高级 Web 服务器设置

gitweb 和获取的单个 URL

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

PATH_INFO 用法

错误

另请参阅

GIT

gitweb