設定和配置
獲取和建立專案
基本快照
分支與合併
共享和更新專案
檢查和比較
打補丁
除錯
電子郵件
外部系統
伺服器管理
指南
管理
底層命令
- 2.50.1 無更改
-
2.50.0
2025-06-16
- 2.47.1 → 2.49.1 無更改
-
2.47.0
2024-10-06
- 2.44.1 → 2.46.4 無更改
-
2.44.0
2024-02-23
- 2.43.2 → 2.43.7 無變更
-
2.43.1
2024-02-09
-
2.43.0
2023-11-20
- 2.42.1 → 2.42.4 無更改
-
2.42.0
2023-08-21
- 2.34.1 → 2.41.3 無更改
-
2.34.0
2021-11-15
- 2.22.2 → 2.33.8 無更改
-
2.22.1
2019-08-11
-
2.22.0
2019-06-07
- 2.14.6 → 2.21.4 無變更
-
2.13.7
2018-05-22
- 2.10.5 → 2.12.5 無更改
-
2.9.5
2017-07-30
- 2.1.4 → 2.8.6 無變更
-
2.0.5
2014-12-17
概要
要開始使用 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)(用於分隔記錄中的欄位)。
-
當前可識別的欄位包括:
您可以直接從 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_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
hash 的描述以獲取詳細列表和描述。另請參閱 gitweb.conf[5] 中“Configuring gitweb features”部分。
動作和 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 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”。