IRKERHOOK(1) Commands IRKERHOOK(1)

irkerhook - اسکریپت قلاب مخزن برای صدور اعلان‌های irker

irkerhook.py [-n] [-V] [[--variable=value...]] [[commit-id...]]

اسکریپت irkerhook.py یک اسکریپت Python است که برای فراخوانی از قلاب post-commit یک مخزن کنترل نسخه طراحی شده است. وظیفهٔ آن جمع‌آوری اطلاعات دربارهٔ کامیتی است که قلاب را فعال کرده است (و احتمالاً ترجیحاتی که توسط مالک مخزن تنظیم شده است) و ارسال آن اطلاعات به نمونه‌ای از irkerd جهت بازفرستادن به کانال‌های مختلف اعلان.

فراخوانی و رفتار مناسب irkerhook.py بسته به اینکه کدام VCS (سامانه کنترل نسخه) آن را فراخوانی می‌کند، متفاوت است. چهار مکان مختلف وجود دارد که اسکریپت ممکن است اطلاعات را از آن‌ها استخراج کند:

1.فراخوانی ابزارهای کمکی VCS.
2.در سامانه‌های کنترل نسخه‌ای مانند git که از متغیرهای پیکربندی قابل تنظیم توسط کاربر پشتیبانی می‌کنند، متغیرهایی با پیشوند "irker.".
3.در سایر سامانه‌های کنترل نسخه، فایل پیکربندی "irker.conf" در دایرکتوری داخلی مخزن.
4.آرگومان‌های خط فرمان به شکل --variable=value.

متغیرهای زیر برای تمام سامانه‌های کنترل نسخهٔ پشتیبانی‌شده عمومی هستند:

project

نام پروژه. باید یک شناسهٔ نسبتاً کوتاه باشد؛ معمولاً در ابتدای اعلان نمایش داده خواهد شد.

repo

نام دایرکتوری سطح بالای مخزن. در صورت عدم تعیین، پیش‌فرض آن یک رونوشت با حروف کوچک از نام پروژه است.

channels

یک URL کانال IRC یا فهرستی از آن‌ها جداشده با کاما، که کانال‌هایی را که اعلان‌ها باید به آن‌ها ارسال شوند مشخص می‌کند. در صورت عدم تعیین، پیش‌فرض کانال #commits در freenode است.

server

میزبانی که انتظار می‌رود دیمن بازفرستندهٔ اعلان irker روی آن قرار داشته باشد. پیش‌فرض "localhost" است.

email

در صورت تنظیم، به جای TCP یا UDP از ایمیل برای برقراری ارتباط استفاده می‌شود. این مقدار به عنوان آدرس ایمیل مقصد استفاده خواهد شد.

tcp

اگر "true" باشد، از TCP برای ارتباط استفاده می‌کند؛ اگر "false" باشد، از UDP استفاده می‌کند. پیش‌فرض "false" است.

urlprefix

پیشوند URL مجموعه تغییرات (Changeset) برای مخزن شما. هنگامی که شناسه کامیت به آن الصاق می‌شود، باید به یک CGI اشاره کند که کامیت را از طریق cgit، gitweb یا موارد مشابه نمایش می‌دهد. در صورت داشتن یک پیکربندی معمول gitweb/cgit، مقادیر پیش‌فرض احتمالاً کار خواهند کرد.

اگر مقدار این متغیر "None" باشد، تولید فیلد URL در اعلان‌های کامیت غیرفعال خواهد شد. مقادیر جادویی دیگر "cgit"، "gitweb" و "viewcvs" هستند که به الگوهای URL مربوطه گسترش می‌یابند و معمولاً با این سامانه‌ها کار می‌کنند.

کوکی‌های جادویی "%(host)s" و "%(repo)s" ممکن است در این URL ظاهر شوند. اولی به FQDN میزبانی که irkerhook.py روی آن در حال اجرا است باز می‌شود؛ دومی به مقدار متغیر "repo" گسترش می‌یابد.

tinyifier

الگوی URL که به سرویسی برای کوتاه‌سازی URLها اشاره دارد تا فضای کمتری را در خط اعلان اشغال کنند. اگر مقدار این متغیر "None" باشد، هیچ فشرده‌سازی انجام نخواهد شد.

color

اگر "mIRC" باشد، فیلدهای اعلان را با کدهای رنگی mIRC برجسته می‌کند. اگر "ANSI" باشد، فیلدهای اعلان را با دنباله‌های فرار رنگی ANSI برجسته می‌کند. پیش‌فرض "none" (بدون رنگ) است. کدهای ANSI در Chatzilla، irssi، ircle و BitchX پشتیبانی می‌شوند؛ کدهای mIRC تنها در mIRC، XChat، KVirc، Konversation یا weechat شناسایی می‌شوند.

نکته: اگر این گزینه را فعال کنید و اعلان‌ها دیگر در کانال شما نمایش داده نشوند، باید فیلتر رنگ IRC را در آن کانال غیرفعال کنید. برای انجام این کار به دسترسی‌های گرداننده (op) نیاز دارید؛ دستور "/mode <channel> -c" را اجرا کنید و <channel> را با نام کانال خود جایگزین نمایید. ممکن است ابتدا لازم باشد دستور "/msg chanserv set <channel> MLOCK +nt-slk" را اجرا کنید.

maxchannels

به عنوان یک عدد صحیح تفسیر می‌شود. اگر صفر نباشد، تعداد کانال‌هایی را که قلاب از متغیر "channels" تفسیر می‌کند، محدود می‌سازد.

این متغیر را نمی‌توان از طریق متغیرهای پیکربندی VCS یا irker.conf تنظیم کرد؛ فقط می‌توان آن را با یک آرگومان خط فرمان تعیین کرد. بدین ترتیب، در یک سرویس میزبانی کد (forge) که در آن مالکان مخزن اجازه ندارند اسکریپت‌های post-commit خود را تغییر دهند، مدیر سایت می‌تواند آن را تنظیم کند تا از هرزنامه‌پراکنی انبوه (shotgun spamming) توسط مالکان مخرب پروژه جلوگیری شود. با این حال، تنظیم آن روی مقداری کمتر از ۲ احتمالاً کار عاقلانه‌ای نخواهد بود.

cialike

اگر خالی نبوده و برابر با "None" (پیش‌فرض) نباشد، رفتار قدیمی سامانهٔ CIA را در حذف فهرست‌های طولانی فایل‌ها به نفع خلاصه‌ای به شکل (N files in M directories) شبیه‌سازی می‌کند. مقدار آن باید عددی باشد که آستانهٔ طول فهرست فایل‌ها را بر حسب نویسه مشخص کند.

template

الگوی مورد استفاده برای تولید پیام‌های اعلان را تعیین می‌کند. فقط در سامانه‌های کنترل نسخه‌ای که دارای متغیرهای پیکربندی هستند در دسترس است؛ در حال حاضر این به معنای git یا hg است. تمامی فیلدهای پایه کامیت و استخراج‌کننده، از جمله سوئیچ‌های رنگی، به عنوان جایگزین‌های %() در دسترس هستند.

اسکریپت irkerhook.py هم تحت python 2 و هم تحت python 3 اجرا خواهد شد، اما هنوز از مخازن mercurial تحت python 3 پشتیبانی نمی‌کند..SS "git"

در git، روش معمول برای فراخوانی این قلاب (از درون قلاب update) به این صورت است که نام مرجع (refname) و به دنبال آن فهرستی از کامیت‌ها به آن ارسال می‌شود. از آنجا که git rev-list معمولاً کامیت‌ها را از جدیدترین به قدیمی‌ترین فهرست می‌کند، بهتر است از --reverse استفاده کنید تا اعلان‌ها به ترتیب زمانی صادر شوند. در یک اسکریپت عادی update، نحوه فراخوانی باید به این شکل باشد:

refname=$1
old=$2
new=$3
irkerhook.py --refname=${refname} $(git rev-list --reverse ${old}..${new})

با این تفاوت که به یک مسیر مطلق برای irkerhook.py نیاز خواهید داشت.

به منظور آزمایش و سازگاری با نسخه‌های پیشین، اگر irkerhook.py را بدون هیچ آرگومانی فراخوانی کنید (مانند آنچه در قلاب post-commit انجام می‌شود)، به گونه‌ای عمل خواهد کرد که گویی به این شکل فراخوانی شده است:

irkerhook.py --refname=refs/heads/master HEAD

با این حال، زمانی که روی یک شاخه غیرپیش‌فرض از یک مخزن bare دستور push را اجرا می‌کنید، این حالت نتیجه درستی ارائه نخواهد داد.

روش معمول برای نصب این قلاب در واقع قرار دادن آن در قلاب post-receive است، چرا که تمام جزئیات لازم را دریافت می‌کند و در صورت بروز خطا، عملیات push را متوقف نخواهد کرد. از اسکریپت زیر استفاده کنید:

#!/bin/sh
echo "sending IRC notification"
while read old new refname; do
    irkerhook --refname=${refname} $(git rev-list --reverse ${old}..${new})
done

تنظیمات ترجیحی را می‌توان در فایل config مخزن و در بخشی تحت عنوان [irker] مشخص کرد. در اینجا نمونه‌ای از ظاهر آن آمده است:

[irker]
    project = gpsd
    color = ANSI
    channels = irc://chat.freenode.net/gpsd,irc://chat.freenode.net/commits

نباید متغیر "repository" را مقداردهی کنید (مقدار معادل آن محاسبه خواهد شد). هیچ تلاشی برای تفسیر فایل irker.conf صورت نمی‌گیرد.

مقدار پیش‌فرض متغیر "project"، نام پایه (basename) دایرکتوری مخزن است. مقدار پیش‌فرض متغیر "urlprefix" برابر "cgit" است.

یک متغیر اختصاصی git به نام "revformat" وجود دارد که قالب شناسه کامیت را در اعلان کنترل می‌کند. این متغیر می‌تواند مقادیر زیر را داشته باشد:

raw

شناسه کامل هگزادسیمال (hex) کامیت

short

۱۲ نویسه نخست از شناسه هگزادسیمال

describe

توصیف نسبت به آخرین برچسب (tag)، و در صورت عدم امکان، استفاده از short

مقدار پیش‌فرض 'describe' است.

در Subversion، irkerhook.py یک گزینه --repository همراه با مقدار (مسیر مطلق مخزن Subversion) و یک آرگومان commit (شماره نگارش عددی کامیت) را می‌پذیرد. مقادیر پیش‌فرض به ترتیب دایرکتوری کاری فعلی و HEAD هستند.

با این حال توجه داشته باشید که شما نمی‌توانید آرگومان repository را در قلاب post-commit در Subversion به مقدار پیش‌فرض رها کنید؛ این به دلیل محدودیتی در Subversion است، چرا که دریافت دایرکتوری جاری در داخل این قلاب‌ها قابل اطمینان نیست. در عوض، مقادیر باید همان دو آرگومانی باشند که Subversion به عنوان آرگومان به آن قلاب ارسال می‌کند. بنابراین، یک فراخوانی معمول در اسکریپت post-commit به این شکل خواهد بود:

REPO=$1
REV=$2
irkerhook.py --repository=$REPO $REV

سایر تنظیمات به صورت --variable=value نیز می‌توانند در خط فرمان مشخص شوند و هرگونه تنظیمی در فایل irker.conf را بازنویسی خواهند کرد.

مقدار پیش‌فرض متغیر project، نام پایه (basename) مخزن است. مقدار پیش‌فرض متغیر "urlprefix" برابر "viewcvs" است.

اگر یک فایل irker.conf در دایرکتوری ریشه مخزن وجود داشته باشد (نه دایرکتوری checkout، بلکه جایی که ساختارهای داخلی مانند فایل "format" قرار دارند)، قلاب تنظیمات متغیرها را از آن تفسیر خواهد کرد. در اینجا نمونه‌ای از ظاهر احتمالی چنین فایلی آورده شده است:

# irkerhook variable settings for the irker project
project = irker
channels  = irc://chat.freenode/irker,irc://chat.freenode/commits
tcp = false

متغیرهای "repository" یا "commit" را در این فایل تنظیم نکنید؛ چرا که نتایج نامطلوبی در پی خواهد داشت.

هیچ متغیر اختصاصی برای Subversion وجود ندارد..SS "Mercurial"

در Mercurial، irkerhook.py می‌تواند به دو روش فراخوانی شود: یا به عنوان یک هوک Python (روش ترجیحی) یا به صورت یک اسکریپت.

برای فراخوانی آن به عنوان یک هوک Python، عبارت زیر را به بخش اعلان هوک «commit» یا «incoming» در مخزن Mercurial خود اضافه کنید:

[hooks]
	incoming.irker = python:/path/to/irkerhook.py:hg_hook

هنگامی که به صورت یک اسکریپت فراخوانی می‌شود، این هوک گزینهٔ --repository را همراه با مقدار (مسیر مطلق مخزن Mercurial) می‌پذیرد و می‌تواند یک آرگومان commit (شناسهٔ هش Mercurial کامیت یا ارجاعی به آن) را دریافت کند. مقدار پیش‌فرض برای آرگومان مخزن، دایرکتوری جاری است. آرگومان پیش‌فرض commit مقدار '-1' است که کامیت tip فعلی را مشخص می‌کند.

همانند git، در هر دو حالت تمام متغیرها می‌توانند در فایل hgrc مخزن و در بخش [irker] تنظیم شوند. آرگومان‌های خط فرمان به صورت variable=value برای فراخوانی اسکریپت پذیرفته می‌شوند اما الزامی نیستند. هیچ تلاشی برای تفسیر فایل irker.conf صورت نمی‌گیرد.

مقدار پیش‌فرض متغیر «project» نام پایهٔ (basename) دایرکتوری مخزن است. مقدار پیش‌فرض متغیر «urlprefix» در صورت وجود، مقدار پیکربندی «web.baseurl» خواهد بود.

امکان فیلتر کردن کامیت‌ها پیش از ارسال آن‌ها به irkerd وجود دارد.

باید گزینهٔ filtercmd را مشخص کنید، که دستوری است که توسط irkerhook.py اجرا خواهد شد. این دستور باید یک آرگومان بپذیرد که نمایشی از فراداده‌های کامیت و استخراج‌کننده (شامل متغیر channels) در قالب JSON است. این دستور باید یک نمایش JSON از فراداده‌های (احتمالاً تغییریافته) را در خروجی استاندارد تولید کند.

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

#!/usr/bin/env python3
# This is a trivial example of a metadata filter.
# All it does is change the name of the commit's author.
# 
import sys, json
metadata = json.loads(sys.argv[1])
metadata['author'] = "The Great and Powerful Oz"
print(json.dumps(metadata))
# end

خطای استاندارد (standard error) برای پیام‌های پیشرفت و خطا در دسترس هوک قرار دارد.

irkerhook.py گزینه‌های زیر را می‌پذیرد:

-n

از ارسال به دیمن جلوگیری می‌کند. در عوض، درخواست JSON تولیدشده را در خروجی استاندارد می‌ریزد. برای اشکال‌زدایی مفید است.

-V

نسخهٔ برنامه را در خروجی استاندارد چاپ کرده و خارج می‌شود.

irkerd(8)

Eric S. Raymond <esr@snark.thyrsus.com>. برای به‌روزرسانی‌ها و سایر منابع به صفحهٔ پروژه در http://www.catb.org/~esr/irker مراجعه کنید.

07/26/2026 irker