設定與組態
取得與建立專案
基本快照
分支與合併
分享與更新專案
檢查與比較
修補
除錯
電子郵件
外部系統
伺服器管理
指南
管理
底層命令
-
2.47.0
10/06/24
- 2.44.1 → 2.46.2 沒有變更
-
2.44.0
02/23/24
- 2.43.2 → 2.43.5 沒有變更
-
2.43.1
02/09/24
-
2.43.0
11/20/23
- 2.42.1 → 2.42.3 沒有變更
-
2.42.0
08/21/23
- 2.34.1 → 2.41.2 沒有變更
-
2.34.0
11/15/21
- 2.22.2 → 2.33.8 沒有變更
-
2.22.1
08/11/19
-
2.22.0
06/07/19
- 2.14.6 → 2.21.4 沒有變更
-
2.13.7
05/22/18
- 2.10.5 → 2.12.5 沒有變更
-
2.9.5
07/30/17
- 2.1.4 → 2.8.6 沒有變更
-
2.0.5
12/17/14
概要
要開始使用 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,(用於分隔記錄中的欄位)。
-
目前可辨識的欄位為
你可以直接從 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_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.*
組態變數(在組態中) -
請閱讀
%feature
雜湊的詳細列表和說明。另請參閱 gitweb.conf[5] 中的「設定 gitweb 功能」章節。
動作和 URL
Gitweb 可以使用基於 path_info(組件)的 URL,或者它可以透過查詢參數傳遞所有必要資訊。典型的 gitweb URL 分為五個組件
.../gitweb.cgi/<repo>/<action>/<revision>:/<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
-
顯示檔案的 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"。
GIT
屬於 git[1] 套件的一部分