簡體中文 ▾ 主題 ▾ 最新版本 ▾ 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_categorygitweb.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/README, gitweb/INSTALL

GIT

Git[1] 套件的一部分

scroll-to-top