مخازن (Repositories)

ابزار Gitweb می‌تواند اطلاعات یک یا چند مخزن گیت را نمایش دهد. تمام این مخازن باید روی فایل‌سیستم محلی قرار داشته باشند و ریشه مخزن مشترکی داشته باشند؛ یعنی همگی زیر یک مخزن والد منفرد قرار گیرند (البته زیربخش «پیکربندی وب‌سرور با چند ریشه پروژه» در بخش «راه‌اندازی پیشرفته وب‌سرور» را نیز ببینید).

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

مقدار پیش‌فرض برای $projectroot برابر با /pub/git است. می‌توانید هنگام ساخت gitweb آن را از طریق متغیر پیکربندی ساخت GITWEB_PROJECTROOT تغییر دهید.

به طور پیش‌فرض تمام مخازن گیت واقع در $projectroot برای gitweb قابل مشاهده و در دسترس هستند. فهرست پروژه‌ها به طور پیش‌فرض با پیمایش دایرکتوری $projectroot برای یافتن مخازن گیت تولید می‌شود (به بیان دقیق‌تر برای پایگاه‌های داده اشیاء؛ gitweb نیازی به ناحیه کاری ندارد و برای نمایش مخازن «bare» مناسب‌تر است).

نام مخزن در gitweb همان مسیر به $GIT_DIR آن (پایگاه داده اشیاء آن) به صورت نسبی نسبت به $projectroot است. بنابراین مخزن $repo را می‌توان در "$projectroot/$repo" پیدا کرد.

قالب فایل فهرست پروژه‌ها (Projects list file format)

به جای اینکه gitweb با پیمایش فایل‌سیستم از $projectroot مخازن را پیدا کند، می‌توانید با تنظیم متغیر $projects_list به نحوی که به یک فایل متنی ساده حاوی فهرستی از پروژه‌ها (همراه با برخی اطلاعات اضافی) اشاره کند، فهرستی از پیش تولیدشده از پروژه‌های قابل مشاهده را ارائه دهید.

این فایل از قالب زیر استفاده می‌کند:

می‌توانید فایل نمایه فهرست پروژه‌ها را با استفاده از کنش project_index (پیوند TXT در صفحه فهرست پروژه‌ها) مستقیماً از gitweb تولید کنید؛ همچنین بخش «تولید فهرست پروژه‌ها با استفاده از gitweb» در زیر را ببینید.

نمونه محتویات:

foo.git       Joe+R+Hacker+<joe@example.com>
foo/bar.git   O+W+Ner+<owner@example.org>

به طور پیش‌فرض این فایل تنها مشخص می‌کند که کدام پروژه‌ها در صفحه فهرست پروژه‌ها قابل مشاهده هستند (توجه داشته باشید مواردی که به مخازن به درستی شناسایی‌شده گیت اشاره نکنند توسط gitweb نمایش داده نخواهند شد). حتی اگر پروژه‌ای در صفحه فهرست پروژه‌ها قابل مشاهده نباشد، همچنان می‌توانید با ساخت دستی یک نشانی اینترنتی gitweb آن را مشاهده کنید. با تنظیم متغیر پیکربندی $strict_export (به gitweb.conf(5) مراجعه کنید) روی یک مقدار درستی (true)، می‌توانید اجازه دهید تنها مخازنی مشاهده شوند که در صفحه مرور کلی نمایش داده شده‌اند (یعنی فقط پروژه‌هایی که صریحاً در فایل فهرست پروژه‌ها ذکر شده‌اند در دسترس خواهند بود).

تولید فهرست پروژه‌ها با استفاده از gitweb (Generating projects list using gitweb)

فرض می‌کنیم که GITWEB_CONFIG مقدار پیش‌فرض Makefile خود یعنی gitweb_config.perl را دارد. خطوط زیر را در فایل gitweb_make_index.perl قرار دهید:

read_config_file("gitweb_config.perl");
$projects_list = $projectroot;

سپس اسکریپت زیر را ایجاد کنید تا فهرست پروژه‌ها را در قالبی مناسب برای متغیر پیکربندی ساخت GITWEB_LIST (یا متغیر $projects_list در پیکربندی gitweb) دریافت نمایید:

#!/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 را روی نام فایل آن تنظیم کنید.

کنترل دسترسی به مخازن گیت (Controlling access to Git repositories)

به طور پیش‌فرض تمام مخازن گیت واقع در $projectroot برای gitweb قابل مشاهده و در دسترس هستند. با این حال می‌توانید نحوه کنترل دسترسی به مخازن توسط gitweb را پیکربندی کنید.

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

$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 به تفکیک مخزن (Per-repository gitweb configuration)

می‌توانید مخازن منفرد نمایش‌داده‌شده در gitweb را با ایجاد فایل در GIT_DIR مخزن گیت، یا با تنظیم برخی متغیرهای پیکربندی مخزن (در GIT_DIR/config، به git-config(1) مراجعه کنید) پیکربندی نمایید.

می‌توانید از فایل‌های زیر در مخزن استفاده کنید:

README.html

description (یا gitweb.description)

Unnamed repository; edit this file to name it for gitweb.

category (یا gitweb.category)

cloneurl (یا چندمقداری gitweb.url)

gitweb.owner

متغیرهای پیکربندی مختلف gitweb.* (در پیکربندی)

کنش‌ها (Actions):

کنش‌های استاندارد عبارتند از:

project_list

summary

heads, remotes

tags

blob, tree

blob_plain

blobdiff

blame, blame_incremental

commit, commitdiff

patch

tag

log, shortlog

history

rss, atom

آپاچی به عنوان CGI (Apache as CGI)

آپاچی باید به گونه‌ای پیکربندی شود که از اسکریپت‌های CGI در دایرکتوری محل نصب gitweb پشتیبانی کند. فرض کنیم این دایرکتوری /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>

با این پیکربندی، مسیر کامل برای مرور مخازن به صورت زیر خواهد بود:

آپاچی با mod_perl، از طریق ModPerl::Registry (Apache with mod_perl, via ModPerl::Registry)

می‌توانید از mod_perl همراه با gitweb استفاده کنید. برای فعال‌سازی این پشتیبانی باید بسته Apache::Registry (برای mod_perl 1.x) یا ModPerl::Registry (برای mod_perl 2.x) را نصب کنید.

با فرض اینکه gitweb در /var/www/perl نصب شده باشد، پیکربندی آپاچی زیر (برای 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>

با این پیکربندی، مسیر کامل برای مرور مخازن به صورت زیر خواهد بود:

آپاچی با FastCGI (Apache with FastCGI)

ابزار Gitweb با آپاچی و FastCGI کار می‌کند. ابتدا باید فایل gitweb.cgi را به gitweb.fcgi تغییر نام داده، کپی کرده یا به صورت پیوند نمادین درآورید. فرض کنیم gitweb در دایرکتوری /usr/share/gitweb نصب شده است. پیکربندی آپاچی زیر مناسب است (تست‌نشده!)

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>

با این پیکربندی، مسیر کامل برای مرور مخازن به صورت زیر خواهد بود:

نشانی اینترنتی یکسان برای gitweb و برای واکشی مخزن (Single URL for gitweb and for fetching)

اگر می‌خواهید یک نشانی اینترنتی یکسان برای هم gitweb و هم مخازن http:// خود داشته باشید، می‌توانید آپاچی را به این صورت پیکربندی کنید:

<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 ارائه می‌دهد، هم به عنوان یک نشانی اینترنتی قابل کلون در گیت و هم به عنوان رابط قابل مرور در gitweb. اگر سپس git-daemon(1) خود را با --base-path=/pub/git --export-all راه‌اندازی کنید، حتی می‌توانید از نشانی git:// با دقیقاً همان مسیر استفاده کنید.

تنظیم متغیر محیطی 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 (برای تنظیم URI پایه پیوندهای نسبی) را به درستی ایجاد کند، بنابراین باید به طور خودکار کار کند.

پیکربندی وب‌سرور با چند ریشه پروژه (Webserver configuration with multiple projects' root)

اگر می‌خواهید از gitweb با چندین ریشه پروژه استفاده کنید، می‌توانید میزبان مجازی آپاچی و فایل‌های پیکربندی gitweb خود را به روش زیر ویرایش نمایید.

پیکربندی میزبان مجازی (در فایل پیکربندی آپاچی) باید به شکل زیر باشد:

<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 نادرست باشد، یا کد فوق باید در کدی قرار گیرد که توسط $per_request_config ارجاع داده می‌شود؛

این پیکربندی‌ها دو قابلیت را فعال می‌کنند. نخست اینکه هر کاربر یونیکس (<user>) در سرور می‌تواند مخازن گیت موجود در ~/public_git/ را از طریق gitweb با نشانی زیر مرور کند:

http://git.example.org/~<user>/

اگر این ویژگی را روی سرور خود نمی‌خواهید، کافی است قانون دوم بازنویسی را حذف کنید.

اگر پیش‌تر از ‘mod_userdir` در میزبان مجازی خود استفاده می‌کنید یا نمی‌خواهید از '~’ به عنوان اولین نویسه استفاده کنید، کافی است قانون بازنویسی دوم را کامنت یا حذف کرده و بسته به آنچه می‌خواهید یکی از خطوط پس از آن را از حالت کامنت خارج نمایید.

دوم اینکه، مخازن موجود در /pub/scm/ و /var/git/ از طریق http://git.example.org/scm/ و http://git.example.org/var/ در دسترس خواهند بود. با افزودن قوانین بازنویسی شبیه به قوانین سوم و چهارم، می‌توانید هر تعداد ریشه پروژه را که می‌خواهید اضافه کنید.

استفاده از PATH_INFO (PATH_INFO usage)

اگر استفاده از PATH_INFO را در gitweb با قرار دادن

$feature{'pathinfo'}{'default'} = [1];

در فایل پیکربندی gitweb خود فعال کنید، می‌توان سرور را به گونه‌ای راه‌اندازی کرد که نشانی‌های اینترنتی را به شکل زیر دریافت و تولید کند:

یعنی بدون بخش gitweb.cgi، با استفاده از پیکربندی‌ای مانند موارد زیر. این پیکربندی فرض می‌کند که /var/www/gitweb همان ریشه سند (DocumentRoot) وب‌سرور شما است، و شامل اسکریپت gitweb.cgi و فایل‌های استاتیک مکمل (برگه استایل، فاوآیکون، جاوااسکریپت) است:

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

قانون بازنویسی تضمین می‌کند که فایل‌های استاتیک موجود به درستی ارائه شوند، در حالی که هر نشانی دیگری به عنوان پارامتر PATH_INFO به gitweb ارسال خواهد شد.

توجه کنید که در این حالت شما به تنظیمات خاصی برای @stylesheets، $my_uri و $home_link نیاز ندارید، اما دسترسی «کلاینت‌های سنتی (dumb clients)» به دایرکتوری‌های git. پروژه خود را از دست می‌دهید (که در بخش «نشانی اینترنتی یکسان برای gitweb و برای واکشی مخزن» شرح داده شد). یک راهکار احتمالی برای این مورد به شرح زیر است: در دایرکتوری ریشه پروژه خود (مثلاً /pub/git) نام پروژه‌ها را بدون پسوند git. قرار دهید (مثلاً /pub/git/project به جای /pub/git/project.git) و آپاچی را به این صورت پیکربندی کنید:

<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 شرایطی را فراهم می‌کند که

دسترسی خام به دایرکتوری گیت پروژه را فراهم نماید (تا امکان کلون کردن پروژه وجود داشته باشد)، در حالی که

دسترسی کاربرپسند به gitweb را فراهم خواهد ساخت.

این راهکار کاملاً و ۱۰۰٪ بی‌نقص نیست، به این معنا که اگر پروژه‌ای دارای یک مرجع (شاخه، برچسب) باشد که با git/ آغاز شود، مسیرهایی مانند

با خطای ۴۰۴ مواجه خواهند شد.