English ▾ 主題 ▾ 最新版本 ▾ gitweb 最後更新於 2.50.0

名稱

gitweb - Git 網頁介面 (Git 儲存庫的網頁前端)

概要

若要開始使用 gitweb,請從 Git 儲存庫執行 git-instaweb[1]。這將會設定並啟動您的網頁伺服器,並執行指向 gitweb 的網頁瀏覽器。

描述

Gitweb 為 Git 儲存庫提供了一個網頁介面。其功能包括:

  • 檢視具有共同根目錄的多個 Git 儲存庫。

  • 瀏覽儲存庫的每一個修訂版本。

  • 在任何修訂版本下檢視儲存庫中檔案的內容。

  • 檢視分支的修訂紀錄、檔案與目錄的歷史紀錄,查看變更內容、時間以及變更者。

  • 檢視任何檔案的追究(blame/annotation)詳細資訊(若已啟用)。

  • 為任何分支產生提交紀錄的 RSS 與 Atom 訂閱源。現代網頁瀏覽器可自動偵測這些訂閱源。

  • 檢視修訂版本中的所有變更,並逐一檢視修訂版本,以查看儲存庫的歷史紀錄。

  • 尋找提交訊息符合特定搜尋詞彙的提交紀錄。

請參閱 https://repo.or.cz/w/git.git/tree/HEAD:/gitweb/ 以取得 gitweb 原始程式碼,該連結本身即使用 gitweb 進行瀏覽。

組態設定 (CONFIGURATION)

gitweb 行為的各個方面皆可透過設定檔 gitweb_config.perl/etc/gitweb.conf 進行控制。詳細資訊請參閱 gitweb.conf[5]

儲存庫

Gitweb 可以顯示一個或多個 Git 儲存庫的資訊。這些儲存庫必須全部位於本機檔案系統上,並且必須共用一個共同的儲存庫根目錄,亦即皆位於單一父儲存庫之下(但亦請參閱「進階網頁伺服器設定」章節中的「具有多個專案根目錄的網頁伺服器設定」子章節)。

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

$projectroot 的預設值為 /pub/git。您可以在建置 gitweb 時透過 GITWEB_PROJECTROOT 建置設定變數來變更此值。

預設情況下,$projectroot 下的所有 Git 儲存庫皆對 gitweb 可見且可用。專案清單預設是透過掃描 $projectroot 目錄中的 Git 儲存庫(更準確地說是物件資料庫;gitweb 對工作區不感興趣,且最適合用於顯示「裸 (bare)」儲存庫)所產生的。

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,用於分隔紀錄中的欄位)。

  • 目前識別的欄位有:

    <儲存庫路徑>

    儲存庫 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>

預設情況下,此檔案僅控制哪些專案在專案清單頁面上是**可見的**(請注意,未指向正確識別之 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] 線上手冊。若其評估結果為 true,則 gitweb 僅在物件資料庫中存在名為 $export_ok 的檔案時(若目錄中具有名為 $export_ok 的魔法檔案),才會顯示該儲存庫。

    例如,git-daemon[1] 預設(除非使用 --export-all 選項)僅允許對具有 git-daemon-export-ok 檔案的儲存庫進行 pull。加入:

    our $export_ok = "git-daemon-export-ok";

    將使 gitweb 僅顯示並允許存取那些可以透過 git:// 通訊協定擷取 (fetch) 的儲存庫。

  • 最後,可以指定一個任意的 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 專案「摘要」頁面的 <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(用於 clone 與 fetch)的檔案,每行一個。顯示於專案摘要頁面。您可以使用多值的 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

<儲存庫> 內,操作所針對的路徑(針對需要路徑的操作)。

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)訂閱源。

網頁伺服器設定

本章節說明如何設定一些常見的網頁伺服器以執行 gitweb。在所有情況下,範例中的 /path/to/gitweb 均為您安裝 gitweb 的目錄,且該目錄包含 gitweb_config.perl

若您已為 gitweb 設定了此處未列出的網頁伺服器,請將操作說明寄給我們,以便將其包含在未來的版本中。

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

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

進階網頁伺服器設定

所有這些範例皆使用請求重寫 (request rewriting),且需要 mod_rewrite(或同等功能;以下範例為 Apache 編寫)。

gitweb 與 fetch 的單一 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),因此應該能自動運作。

具有多個專案根目錄的網頁伺服器設定

若您想在 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>

在此處,實際的專案根目錄是透過網頁伺服器的 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 是您網頁伺服器的 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 目錄的「啞客戶端 (dumb client)」存取權(描述於「gitweb 與 fetch 的單一 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 錯誤。

錯誤 (BUGS)

請將任何錯誤報告或功能請求寄至 git@vger.kernel.org,並在郵件主旨中註明 "gitweb"。

參見

gitweb/README, gitweb/INSTALL

GIT

git[1] 套件的一部分