gitweb

gitweb

Name

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

概要

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

描述

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

• 使用公共根查看多个Git存储库。

组态

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

库

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

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

$projectrootis 的默认值/pub/git。您可以在构建gitweb时通过GITWEB_PROJECTROOT构建配置变量来更改它。

默认情况下，所有Git仓库$projectroot都是可见的，并可用于gitweb。默认情况下，通过扫描$projectrootGit存储库的目录生成项目列表（对于更精确的对象数据库; gitweb对工作区域不感兴趣，并且最适合显示“裸”存储库）。

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

项目列表文件格式

您可以通过扫描从$ projectroot开始的文件系统来找到存储库，而不是让gitweb通过从$ projectroot开始扫描文件系统来找到存储库，您可以通过设置$projects_list指向带有项目列表的纯文本文件（以及其他信息）来提供预先生成的可见项目列表。

该文件使用以下格式：

• 每行一个记录（用于项目/存储库）; 不支持行延续（换行符转义）。

您可以TXT直接从gitweb 使用project_index操作（项目列表页面上的链接）生成项目列表索引文件; 另请参阅下面的“使用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]）设置为真值，您可以只允许查看也显示在概览页面上的存储库（即只有项目列表文件中明确列出的项目才可访问）。

使用gitweb生成项目列表

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

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

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

#!/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存储库的访问

默认情况下，所有Git仓库$projectroot都是可见的，并可用于gitweb。然而，你可以配置gitweb控制对存储库的访问。

• 如“项目列表文件格式”部分所述，您可以通过在项目列表文件中选择性地包含存储库并将gitweb配置变量设置为指向它来控制哪些项目可见$projects_list。通过$strict_export设置，项目列表文件也可用于控制哪些存储库可用。

使gitweb显示，并只允许访问那些可以通过git://协议获取的存储库。

• 最后，可以指定一个任意perl子例程，这个子例程会被每个资源库调用以确定它是否可以导出。子例程接收项目（存储库）的绝对路径作为其唯一参数（即“$ projectroot / $ project”）。例如，如果您使用mod_perl来运行脚本，并为您的存储库配置了愚蠢的HTTP协议认证，那么只有当用户有权读取这些文件时，才可以使用以下挂接：$ export_auth_hook = sub {use Apache2 :: SubRequest（）; 使用Apache2 :: Const -compile => qw（HTTP_OK）; my $ path =“$ _0 / HEAD”; 我的$ r = Apache2 :: RequestUtil->请求; my $ sub = $ r-> lookup_file（$ path）; 返回$子>文件名eq $路径&& $子>状态== Apache2 ::常量:: HTTP_OK; };

每个版本库的gitweb配置

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

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

README.html

<div>块元素中的gitweb项目“摘要”页面中包含的html文件（HTML片段）。您可以使用它来获取项目的更长描述，提供链接（例如项目的主页）等。只有在XSS预防功能关闭的情况下才能识别这种情况（$prevent_xss错误，请参阅gitweb.conf [5]）; 在未来XSS预防开启时安全地包含自述文件的方法可能会被制定出来。

description (or gitweb.description)

Short（简称为$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.descriptionrepo配置变量，但该文件优先。

category (or gitweb.category)

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

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

cloneurl (or multiple-valued gitweb.url)

带有存储库URL的文件（用于克隆和提取），每行一个。显示在项目摘要页面中。您可以使用多值gitweb.url存储库配置变量，但该文件优先。

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

gitweb.owner

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

如果未设置，则使用文件系统目录的所有者（通过GECOS字段，即来自getpwuid（3）的实名字段），如果$projects_list未设置（gitweb扫描$projectroot存储库）; 如果$projects_list指向使用存储库列表的文件，则项目所有者将默认为此文件对给定存储库的值。

various gitweb.* config variables (in config)

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

行动和网址

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

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

回购

操作将在其上执行的存储库。

除了列出所有可用项目的所有操作（无论采用何种形式），都需要此参数。

action

将要运行的操作。默认为projects_list如果没有设置回购，summary否则。

调整

显示修订。默认为HEAD。

path

执行操作的<repository>中的路径，用于需要它的操作。

arguments

任何控制动作行为的参数。

某些操作需要或允许指定两个修订版本，有时甚至包含两个路径名。在大多数通用形式中，这样的基于路径信息（组件）的gitweb URL看起来像这样：

.../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments>

每个动作都以子例程的形式实现，并且必须存在于％动作哈希中。某些操作默认情况下处于禁用状态，必须通过功能机制启用。例如，要启用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向指定文件的内容逐渐添加责备信息。

出于性能原因，此操作默认处于禁用状态。

提交commitdiff

显示有关存储库中特定提交的信息。该commit视图更详细地显示了有关提交的信息，该commitdiff操作显示了给定提交的变更集。

patch

以纯文本邮件格式返回提交，适用于使用git-am [1]。

tag

显示特定的注释标签（标签对象）。

log shortlog

显示给定分支的日志信息（提交消息或仅提交主题）（从给定修订开始）。

该shortlog视图是更紧凑; 它显示每行一次提交。

history

从给定修订（默认为HEAD，即默认分支）开始，显示给定存储库路径中文件或目录的历史记录。

这种观点与shortlog观点相似。

rss atom

生成对存储库的更改的RSS（或Atom）订阅源。

网络服务器配置

本节介绍如何配置一些常用的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 with mod_perl, via ModPerl::Registry

你可以在gitweb中使用mod_perl。您必须安装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>

上面的配置希望你的公共仓库可以作为可复制的Git URL和可浏览的gitweb界面一起存在/pub/git并且将作为它们服务http://git.domain.org/dir-under-pub-git。如果你启动你的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基本标记（为相对链接设置基本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 folder 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>

这里实际的项目根目录通过GITWEB_PROJECT_ROOTweb服务器的环境变量传递给gitweb ，所以你需要把下面的代码放到gitweb配置文件中（/etc/gitweb.conf在上面的例子中）：

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

请注意，这需要为每个请求设置，因此要么$per_request_config必须是false，要么上面的代码必须放在引用的代码中$per_request_config;

这些配置有两件事。首先，<user>服务器的每个unix用户（）都能够浏览通过~/public_git/以下URL 找到的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 usage

如果你通过放在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脚本和补充静态文件（stylesheet，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和获取”部分所述）。后者的一个可能的解决方法如下：在你的项目的根目录中（例如/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％的，因为如果某个项目有一个名为ref（branch，tag）的开头git/，那么路径如

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

将失败并出现404错误。

Bugs

请将任何错误或功能请求报告给git@vger.kernel.org，将“gitweb”放在电子邮件主题中。