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

名稱

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

概要

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

描述

Gitweb 提供 Git 儲存庫的網頁介面。其功能包括

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

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

  • 檢視儲存庫中任何修訂版本的文件內容。

  • 檢視分支的修訂記錄、文件和目錄的歷史記錄、查看變更的內容、時間和人員。

  • 檢視任何文件的 blame/註解詳細資料 (如果已啟用)。

  • 為任何分支產生 commit 的 RSS 和 Atom 訂閱來源。這些訂閱來源可以在現代網頁瀏覽器中自動偵測到。

  • 檢視修訂版本中變更的所有內容,並一次逐步檢視修訂版本,檢視儲存庫的歷史記錄。

  • 尋找 commit 訊息與給定的搜尋詞彙相符的 commit。

有關 gitweb 原始碼,請參閱 https://repo.or.cz/w/git.git/tree/HEAD:/gitweb/,使用 gitweb 本身瀏覽。

組態

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 對工作區域不感興趣,並且最適合顯示「裸」儲存庫。

gitweb 中儲存庫的名稱是其 $GIT_DIR (其物件資料庫) 相對於 $projectroot 的路徑。因此,可以在「$projectroot/$repo」找到儲存庫 $repo。

專案清單檔案格式

你可以提供預先產生的可見專案清單,而不是讓 gitweb 從 $projectroot 開始掃描檔案系統來尋找儲存庫,方法是設定 $projects_list 以指向具有專案清單 (以及一些額外資訊) 的純文字檔案。

此檔案使用下列格式

  • 每行一個記錄 (用於專案/儲存庫);不支援行接續 (換行符號逸出)。

  • 忽略開頭和結尾的空白字元。

  • 以空白字元分隔的欄位;任何連續的空白字元都可以用作欄位分隔符號 (適用於 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 僅列出並允許檢視明確匯出的儲存庫,方法是透過 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 專案「摘要」頁面中的 <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.* 組態變數(在組態中)

請閱讀 %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)摘要。

網站伺服器組態

本節說明如何設定一些常見的網站伺服器來執行 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

透過 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

進階網站伺服器設定

所有這些範例都使用請求重寫,並且需要 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 介面。如果您然後使用 --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>)將能夠透過以下網址瀏覽位於 ~/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 是您網頁伺服器的 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 和提取的單一 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/ 開頭的 ref(分支、標籤),則類似以下的的路徑:

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

將會失敗並出現 404 錯誤。

錯誤回報

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

另請參閱

gitweb/README, gitweb/INSTALL

GIT

屬於 git[1] 套件的一部分

scroll-to-top