نام (NAME)

cgitrc - پیکربندی زمان اجرای cgit

خلاصه دستور (SYNOPSIS)

پرونده cgitrc شامل تمام تنظیمات زمان اجرای cgit، از جمله فهرست مخازن git است که به‌صورت فهرستی از جفت‌های NAME=VALUE جداشده با خط جدید قالب‌بندی شده‌اند. خطوط خالی و خطوطی که با # آغاز می‌شوند نادیده گرفته می‌شوند.

محل قرارگیری (LOCATION)

محل پیش‌فرض cgitrc که در زمان کامپایل تعیین شده است، /etc/cgitrc است. در زمان اجرا، cgit متغیر محیطی CGIT_CONFIG را بررسی کرده و در صورت تعریف شدن، از مقدار آن استفاده خواهد کرد.

تنظیمات سراسری (GLOBAL SETTINGS)

about-filter

agefile

auth-filter

branch-sort

cache-about-ttl

cache-dynamic-ttl

cache-repo-ttl

cache-root

cache-root-ttl

cache-scanrc-ttl

case-sensitive-sort

cache-size

cache-snapshot-ttl

cache-static-ttl

clone-prefix

clone-url

commit-filter

commit-sort

css

email-filter

embedded

enable-blame

enable-commit-graph

enable-filter-overrides

enable-follow-links

enable-git-config

enable-http-clone

enable-html-serving

enable-index-links

enable-index-owner

enable-log-filecount

enable-log-linecount

enable-remote-branches

enable-subject-links

enable-tree-linenumbers

favicon

footer

head-include

header

include

js

local-time

logo

logo-link

max-atom-items

max-blob-size

max-commit-count

max-message-length

max-repo-count

max-repodesc-length

max-stats

mimetype.<ext>

mimetype-file

module-link

noplainemail

noheader

owner-filter

project-list

readme

remove-suffix

renamelimit

repository-sort

robots

root-desc

root-readme

root-title

scan-hidden-path

scan-path

section

section-sort

section-from-path

side-by-side-diffs

snapshots

source-filter

summary-branches

summary-log

summary-tags

strict-export

virtual-root

تنظیمات مخزن (REPOSITORY SETTINGS)

repo.about-filter

repo.branch-sort

repo.clone-url

repo.commit-filter

repo.commit-sort

repo.defbranch

repo.desc

repo.email-filter

repo.enable-blame

repo.enable-commit-graph

repo.enable-follow-links

repo.enable-html-serving

repo.enable-log-filecount

repo.enable-log-linecount

repo.enable-remote-branches

repo.enable-subject-links

repo.extra-head-content

repo.hide

repo.homepage

repo.ignore

repo.logo

repo.logo-link

repo.module-link

repo.module-link.<path>

repo.max-stats

repo.name

repo.owner

repo.owner-filter

repo.path

repo.readme

repo.section

repo.snapshots

repo.snapshot-prefix

repo.source-filter

repo.url

فایل CGITRC اختصاصی مخزن (REPOSITORY-SPECIFIC CGITRC FILE)

هنگامی که گزینه "scan-path" برای کشف خودکار مخازن git استفاده می‌شود، cgit تلاش می‌کند فایل "cgitrc" را درون هر مخزن یافت‌شده تجزیه کند. چنین فایل پیکربندی اختصاصی مخزن می‌تواند شامل هر یک از گزینه‌های اختصاصی مخزن توضیح‌داده‌شده در بالا باشد، به جز "repo.url" و "repo.path". علاوه بر این، گزینه‌های "filter" تنها زمانی در فایل‌های پیکربندی اختصاصی مخزن پذیرفته می‌شوند که "enable-filter-overrides" روی "1" تنظیم شده باشد.

نکته: پیشوند "repo." از نام گزینه‌ها در فایل‌های پیکربندی اختصاصی مخزن حذف می‌شود، برای مثال "repo.desc" تبدیل به "desc" می‌شود.

رابط برنامه‌نویسی فیلتر (FILTER API)

به‌طور پیش‌فرض، فیلترها فرآیندهای مجزایی هستند که هر بار در صورت نیاز اجرا می‌شوند. فناوری‌های جایگزین را می‌توان با افزودن پیشوند رشته مربوطه به مشخصات فیلتر استفاده کرد؛ مقادیر موجود عبارتند از:

exec:

lua:

filter_open(argument1, argument2, argument3, ...)

filter_write(buffer)

filter_close()

علاوه بر این، cgit توابع داخلی زیر را در اختیار Lua قرار می‌دهد:

html(str)

html_txt(str)

html_attr(str)

html_url_path(str)

html_url_arg(str)

html_include(file)

پارامترها به‌صورت زیر در اختیار فیلترها قرار می‌گیرند.

about filter

auth filter

لطفاً برای یک نمونه اسکریپت واضح که قابل اصلاح است،
به `filters/simple-authentication.lua` مراجعه کنید.

commit filter

email filter

owner filter

source filter

به تمامی فیلترها متغیرهای محیطی زیر داده می‌شود:

اگر تنظیمی برای یک مخزن تعریف نشده باشد و تنظیم سراسری مربوطه نیز تعریف نشده باشد (در صورت وجود)، آنگاه متغیر محیطی متناظر خالی (unset) خواهد بود.

بسط ماکرو (MACRO EXPANSION)

گزینه‌های زیر در cgitrc از یک قابلیت ساده بسط ماکرو پشتیبانی می‌کنند، که در آن نشانه‌هایی که پیشوند "$" دارند با مقدار یک متغیر محیطی با نام مشابه جایگزین می‌شوند:

بسط ماکرو همچنین در محتوای $CGIT_CONFIG، در صورت تعریف شدن، رخ خواهد داد.

یکی از کاربردهای این ویژگی، میزبانی مجازی است که در ساده‌ترین شکل خود با افزودن خط زیر به /etc/cgitrc قابل دستیابی است:

include=/etc/cgitrc.d/$HTTP_HOST

گزینه‌های زیر در حین پردازش درخواست بسط داده می‌شوند و از متغیرهای محیطی تعریف‌شده در "FILTER API" پشتیبانی می‌کنند:

حافظه موقت (CACHE)

تمامی مقادیر ttl حافظه موقت بر حسب دقیقه هستند. مقادیر منفی ttl نشان می‌دهند که یک نوع صفحه هرگز منقضی نخواهد شد، بنابراین اولین باری که به یک نشانی وب دسترسی پیدا می‌شود، نتیجه به‌طور نامحدود کش می‌شود، حتی اگر مخزن git زیربنایی تغییر کند. در مقابل، هنگامی که مقدار ttl صفر باشد، حافظه موقت برای آن نوع صفحه خاص غیرفعال می‌شود و آن نوع صفحه هرگز کش نخواهد شد.

امضاها (SIGNATURES)

نرم‌افزار cgit می‌تواند امضاهای .asc مربوط به قالب‌های مختلف عکس فوری را از طریق یادداشت‌های گیت (git notes) میزبانی کند. برای مثال، دستور زیر ممکن است برای افزودن امضا به یک بایگانی .tar.xz استفاده شود:

git notes --ref=refs/notes/signatures/tar.xz add -C "$(
    gpg --output - --armor --detach-sign cgit-1.1.tar.xz |
    git hash-object -w --stdin
)" v1.1

اگر در عوض تمایل باشد که امضایی از .tar زیربنایی ضمیمه شود، این امضا به عنوان یک حالت خاص، در کنار پیوند .tar.* که امضای اختصاصی خود را ندارد پیوند داده خواهد شد. برای مثال، امضای تاربال آخرین برچسب ممکن است با دستوری مشابه اضافه شود:

tag="$(git describe --abbrev=0)"
git notes --ref=refs/notes/signatures/tar add -C "$(
    git archive --format tar --prefix "cgit-${tag#v}/" "$tag" |
    gpg --output - --armor --detach-sign |
    git hash-object -w --stdin
)" "$tag"

از آنجا که انتظار می‌رود git-archive(1) خروجی پایداری بین نسخه‌ها تولید کند، این امکان فراهم می‌شود تا امضایی بلندمدت از محتویات یک برچسب داده‌شده ایجاد شود.

نمونه فایل CGITRC (EXAMPLE CGITRC FILE)

# فعال‌سازی کش کردن تا ۱۰۰۰ مدخل خروجی
cache-size=1000
# تعیین برخی از نشانی‌های وب کلون پیش‌فرض با استفاده از بسط ماکرو
clone-url=git://foo.org/$CGIT_REPO_URL git@foo.org:$CGIT_REPO_URL
# تعیین نشانی وب css
css=/css/cgit.css
# نمایش مالک در صفحه نمایه
enable-index-owner=1
# اجازه کلون کردن با انتقال http
enable-http-clone=1
# نمایش پیوندهای اضافی برای هر مخزن در صفحه نمایه
enable-index-links=1
# فعال‌سازی صفحه blame و ایجاد پیوند به آن از صفحه درخت
enable-blame=1
# فعال‌سازی نمودار تاریخچه کامیت با هنر اسکی در صفحات لاگ
enable-commit-graph=1
# نمایش تعداد فایل‌های تغییریافته برای هر کامیت در صفحات لاگ
enable-log-filecount=1
# نمایش تعداد خطوط افزوده/حذف‌شده برای هر کامیت در صفحات لاگ
enable-log-linecount=1
# مرتب‌سازی شاخه‌ها بر اساس تاریخ
branch-sort=age
# افزودن فاوآیکون cgit
favicon=/favicon.ico
# استفاده از یک لوگوی سفارشی
logo=/img/mylogo.png
# فعال‌سازی آمار بر اساس هفته، ماه و فصل
max-stats=quarter
# تنظیم عنوان و سربرگ صفحه نمایه مخازن
root-title=example.com git repositories
# تنظیم یک زیرعنوان برای صفحه نمایه مخازن
root-desc=tracking the foobar development
# گنجاندن اطلاعات بیشتر درباره example.com در صفحه نمایه
root-readme=/var/www/htdocs/about.html
# اجازه دانلود فایل‌های tar.gz، tar.bz2 و zip
snapshots=tar.gz tar.bz2 zip
##
## فهرست انواع mime متداول
##
mimetype.gif=image/gif
mimetype.html=text/html
mimetype.jpg=image/jpeg
mimetype.jpeg=image/jpeg
mimetype.pdf=application/pdf
mimetype.png=image/png
mimetype.svg=image/svg+xml
# برجسته‌سازی کد منبع با هایلایتر مبتنی بر pygments در پایتون
source-filter=/var/www/cgit/filters/syntax-highlighting.py
# قالب‌بندی markdown، restructuredtext، صفحات راهنما، فایل‌های متنی و html
# از طریق مبدل‌های مناسب
about-filter=/var/www/cgit/filters/about-formatting.sh
##
## جستجو برای این فایل‌ها در ریشه شاخه پیش‌فرض مخازن
## جهت ایجاد صفحه درباره:
##
readme=:README.md
readme=:readme.md
readme=:README.mkd
readme=:readme.mkd
readme=:README.rst
readme=:readme.rst
readme=:README.html
readme=:readme.html
readme=:README.htm
readme=:readme.htm
readme=:README.txt
readme=:readme.txt
readme=:README
readme=:readme
readme=:INSTALL.md
readme=:install.md
readme=:INSTALL.mkd
readme=:install.mkd
readme=:INSTALL.rst
readme=:install.rst
readme=:INSTALL.html
readme=:install.html
readme=:INSTALL.htm
readme=:install.htm
readme=:INSTALL.txt
readme=:install.txt
readme=:INSTALL
readme=:install
##
## فهرست مخازن.
## پی‌نوشت: هر مخزنی که در زمان خالی بودن section فهرست شود
##          زیر سربرگ هیچ بخشی نمایش داده نخواهد شد
## پی‌نوشت ۲: این فهرست می‌تواند در یک فایل مجزا (مانند '/etc/cgitrepos')
##           نگهداری و به‌صورت زیر ضمیمه شود:
##             include=/etc/cgitrepos
##
repo.url=foo
repo.path=/pub/git/foo.git
repo.desc=the master foo repository
repo.owner=fooman@example.com
repo.readme=info/web/about.html
repo.url=bar
repo.path=/pub/git/bar.git
repo.desc=the bars for your foo
repo.owner=barman@example.com
repo.readme=info/web/about.html
# مخازن بعدی زیر سربرگ 'extras' نمایش داده خواهند شد
section=extras
repo.url=baz
repo.path=/pub/git/baz.git
repo.desc=a set of extensions for bar users
repo.url=wiz
repo.path=/pub/git/wiz.git
repo.desc=the wizard of foo
# افزودن چند مخزن آینه‌ای
section=mirrors
repo.url=git
repo.path=/pub/git/git.git
repo.desc=the dscm
repo.url=linux
repo.path=/pub/git/linux.git
repo.desc=the kernel
# غیرفعال کردن دانلودهای موردی این مخزن
repo.snapshots=0
# غیرفعال کردن شمارش خطوط برای این مخزن
repo.enable-log-linecount=0
# محدود کردن حداکثر دوره آمار برای این مخزن
repo.max-stats=month

اشکالات (BUGS)

در حال حاضر توضیحات (کامنت‌ها) نمی‌توانند در همان خط تنظیمات ظاهر شوند؛ کامنت به عنوان بخشی از مقدار لحاظ خواهد شد. برای مثال این خط:

robots=index  # allow indexing

عنصر html زیر را تولید خواهد کرد:

<meta name='robots' content='index  # allow indexing'/>

نویسنده (AUTHOR)

Lars Hjemli <hjemli@gmail.com> Jason A. Donenfeld <Jason@zx2c4.com>