簡體中文 ▾ 主題 ▾ 最新版本 ▾ gitweb 上次更新於 2.50.0

名稱

gitweb - Git 網頁介面(Git 倉庫的 Web 前端)

概要

要開始使用 gitweb,請在 Git 倉庫中執行 git-instaweb[1]。這將配置並啟動您的 Web 伺服器,並執行一個指向 gitweb 的 Web 瀏覽器。

描述

Gitweb 提供 Git 倉庫的 Web 介面。其功能包括:

  • 檢視具有公共根目錄的多個 Git 倉庫。

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

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

  • 檢視分支的修訂日誌、檔案和目錄的歷史記錄,瞭解何人、何時、何事發生了更改。

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

  • 為任何分支生成提交的 RSS 和 Atom feed。Feed 在現代 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" 找到。

專案列表檔案格式

與其讓 gitweb 透過從 $projectroot 開始掃描檔案系統來查詢倉庫,不如透過將 $projects_list 設定為指向一個包含專案列表(及一些額外資訊)的純文字檔案,來提供一個預生成的可見專案列表。

該檔案使用以下格式:

  • 每行一個記錄(用於專案/倉庫);不支援行續接(換行轉義)。

  • 忽略前導和尾隨空格。

  • 空格分隔的欄位;任何連續的空格都可以用作欄位分隔符(規則類似於 Perl 的 "split(" ", $line)")。

  • 欄位使用修改後的 URI 編碼,該編碼定義在 RFC 3986,第 2.1 節(百分比編碼)中,或者更確切地說,“查詢字串編碼”(請參見 https://en.wikipedia.org/wiki/Query_string#URL_encoding),區別在於 SP (" ") 可以編碼為 "+"(因此 "+" 也必須進行百分比編碼)。

    保留字元是:"%"(用於編碼),"+"(可用於編碼空格),Perl 定義的所有空格字元,包括 SP、TAB 和 LF(用於在記錄中分隔欄位)。

  • 當前識別的欄位有:

    <repository path>

    倉庫 GIT_DIR 的路徑,相對於 $projectroot

    <repository owner>

    顯示為倉庫所有者,最好是全名,或電子郵件,或兩者兼有。

您可以使用專案列表頁面上的 project_index 操作(TXT 連結)直接從 gitweb 生成專案列表索引檔案;另請參見下面的“使用 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 設定為 true 時,專案列表檔案也可以用來控制哪些倉庫**可用**。

  • 您可以透過 gitweb 配置檔案中的 $export_ok 變數配置 gitweb,使其僅列出並允許檢視已顯式匯出的倉庫;請參見 gitweb.conf[5] manpage。如果它求值為 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 協議身份驗證,則可以使用以下鉤子僅在使用者有權讀取檔案時允許訪問:

    $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 倉庫配置變數來設定倉庫的所有者。它會顯示在專案列表和摘要頁面上。

如果未設定,則使用檔案系統目錄的所有者(透過 GECOS 欄位,即 **getpwuid**(3) 中的真實姓名欄位),如果 $projects_list 未設定(gitweb 掃描 $projectroot 中的倉庫);如果 $projects_list 指向包含倉庫列表的檔案,則專案所有者預設為該檔案中給定倉庫的值。

各種 gitweb.* 配置變數(在 config 中)

閱讀 %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 雜湊中。一些操作預設是停用的,必須透過 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 object)。

log
shortlog

顯示給定分支(從給定修訂版本開始)的日誌資訊(提交訊息或僅提交主題)。

shortlog 檢視更緊湊;它每行顯示一個提交。

history

顯示給定倉庫路徑下,檔案或目錄的歷史記錄,從給定修訂版本開始(預設為 HEAD,即預設分支)。

此檢視類似於 shortlog 檢視。

rss
atom

生成倉庫更改的 RSS(或 Atom)feed。

Web 伺服器配置

本節介紹如何配置一些常用 Web 伺服器來執行 gitweb。在所有情況下,示例中的 /path/to/gitweb 是您安裝 gitweb 的目錄,並且包含 gitweb_config.perl

如果您配置了一個此處未列出的 Web 伺服器來執行 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

您可以使用 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 下,並將它們作為可克隆的 Git URL 和可瀏覽的 gitweb 介面提供,形式為 http://git.domain.org/dir-under-pub-git。如果您然後使用 --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 標籤(以設定相對連結的 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 在 gitweb Git 倉庫中瀏覽 ~/public_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];

在您的 gitweb 配置檔案中,可以設定您的伺服器,使其能夠處理和生成以下形式的 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 錯誤而失敗。

BUG

請向 git@vger.kernel.org 報告任何錯誤或功能請求,並在郵件主題中註明“gitweb”。

另請參閱

gitweb/README, gitweb/INSTALL

GIT

Git[1] 套件的一部分