'\" t .\" Title: irkerhook .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 07/26/2026 .\" Manual: Commands .\" Source: irker .\" Language: English .\" .TH "IRKERHOOK" "1" "07/26/2026" "irker" "Commands" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "نام (NAME)" irkerhook \- اسکریپت قلاب مخزن برای صدور اعلان‌های irker .SH "خلاصه دستور (SYNOPSIS)" .HP \w'\fBirkerhook\&.py\fR\ 'u \fBirkerhook\&.py\fR [\-n] [\-V] [[\fI\-\-variable=value\fR...]] [[\fIcommit\-id\fR...]] .SH "توضیحات (DESCRIPTION)" .PP اسکریپت irkerhook\&.py یک اسکریپت Python است که برای فراخوانی از قلاب post\-commit یک مخزن کنترل نسخه طراحی شده است\&. وظیفهٔ آن جمع‌آوری اطلاعات دربارهٔ کامیتی است که قلاب را فعال کرده است (و احتمالاً ترجیحاتی که توسط مالک مخزن تنظیم شده است) و ارسال آن اطلاعات به نمونه‌ای از irkerd جهت بازفرستادن به کانال‌های مختلف اعلان\&. .PP فراخوانی و رفتار مناسب irkerhook\&.py بسته به اینکه کدام VCS (سامانه کنترل نسخه) آن را فراخوانی می‌کند، متفاوت است\&. چهار مکان مختلف وجود دارد که اسکریپت ممکن است اطلاعات را از آن‌ها استخراج کند: .sp .RS 4 .ie n \{\ \h'-04' 1.\h'+01'\c .\} .el \{\ .sp -1 .IP " 1." 4.2 .\} فراخوانی ابزارهای کمکی VCS\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 2.\h'+01'\c .\} .el \{\ .sp -1 .IP " 2." 4.2 .\} در سامانه‌های کنترل نسخه‌ای مانند git که از متغیرهای پیکربندی قابل تنظیم توسط کاربر پشتیبانی می‌کنند، متغیرهایی با پیشوند "irker\&."\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 3.\h'+01'\c .\} .el \{\ .sp -1 .IP " 3." 4.2 .\} در سایر سامانه‌های کنترل نسخه، فایل پیکربندی "irker\&.conf" در دایرکتوری داخلی مخزن\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 4.\h'+01'\c .\} .el \{\ .sp -1 .IP " 4." 4.2 .\} آرگومان‌های خط فرمان به شکل \-\-variable=value\&. .RE .PP متغیرهای زیر برای تمام سامانه‌های کنترل نسخهٔ پشتیبانی‌شده عمومی هستند: .PP project .RS 4 نام پروژه\&. باید یک شناسهٔ نسبتاً کوتاه باشد؛ معمولاً در ابتدای اعلان نمایش داده خواهد شد\&. .RE .PP repo .RS 4 نام دایرکتوری سطح بالای مخزن\&. در صورت عدم تعیین، پیش‌فرض آن یک رونوشت با حروف کوچک از نام پروژه است\&. .RE .PP channels .RS 4 یک URL کانال IRC یا فهرستی از آن‌ها جداشده با کاما، که کانال‌هایی را که اعلان‌ها باید به آن‌ها ارسال شوند مشخص می‌کند\&. در صورت عدم تعیین، پیش‌فرض کانال #commits در freenode است\&. .RE .PP server .RS 4 میزبانی که انتظار می‌رود دیمن بازفرستندهٔ اعلان irker روی آن قرار داشته باشد\&. پیش‌فرض "localhost" است\&. .RE .PP email .RS 4 در صورت تنظیم، به جای TCP یا UDP از ایمیل برای برقراری ارتباط استفاده می‌شود\&. این مقدار به عنوان آدرس ایمیل مقصد استفاده خواهد شد\&. .RE .PP tcp .RS 4 اگر "true" باشد، از TCP برای ارتباط استفاده می‌کند؛ اگر "false" باشد، از UDP استفاده می‌کند\&. پیش‌فرض "false" است\&. .RE .PP urlprefix .RS 4 پیشوند URL مجموعه تغییرات (Changeset) برای مخزن شما\&. هنگامی که شناسه کامیت به آن الصاق می‌شود، باید به یک CGI اشاره کند که کامیت را از طریق cgit، gitweb یا موارد مشابه نمایش می‌دهد\&. در صورت داشتن یک پیکربندی معمول gitweb/cgit، مقادیر پیش‌فرض احتمالاً کار خواهند کرد\&. .sp اگر مقدار این متغیر "None" باشد، تولید فیلد URL در اعلان‌های کامیت غیرفعال خواهد شد\&. مقادیر جادویی دیگر "cgit"، "gitweb" و "viewcvs" هستند که به الگوهای URL مربوطه گسترش می‌یابند و معمولاً با این سامانه‌ها کار می‌کنند\&. .sp کوکی‌های جادویی "%(host)s" و "%(repo)s" ممکن است در این URL ظاهر شوند\&. اولی به FQDN میزبانی که irkerhook\&.py روی آن در حال اجرا است باز می‌شود؛ دومی به مقدار متغیر "repo" گسترش می‌یابد\&. .RE .PP tinyifier .RS 4 الگوی URL که به سرویسی برای کوتاه‌سازی URLها اشاره دارد تا فضای کمتری را در خط اعلان اشغال کنند\&. اگر مقدار این متغیر "None" باشد، هیچ فشرده‌سازی انجام نخواهد شد\&. .RE .PP color .RS 4 اگر "mIRC" باشد، فیلدهای اعلان را با کدهای رنگی mIRC برجسته می‌کند\&. اگر "ANSI" باشد، فیلدهای اعلان را با دنباله‌های فرار رنگی ANSI برجسته می‌کند\&. پیش‌فرض "none" (بدون رنگ) است\&. کدهای ANSI در Chatzilla، irssi، ircle و BitchX پشتیبانی می‌شوند؛ کدهای mIRC تنها در mIRC، XChat، KVirc، Konversation یا weechat شناسایی می‌شوند\&. .sp نکته: اگر این گزینه را فعال کنید و اعلان‌ها دیگر در کانال شما نمایش داده نشوند، باید فیلتر رنگ IRC را در آن کانال غیرفعال کنید\&. برای انجام این کار به دسترسی‌های گرداننده (op) نیاز دارید؛ دستور "/mode \-c" را اجرا کنید و را با نام کانال خود جایگزین نمایید\&. ممکن است ابتدا لازم باشد دستور "/msg chanserv set MLOCK +nt\-slk" را اجرا کنید\&. .RE .PP maxchannels .RS 4 به عنوان یک عدد صحیح تفسیر می‌شود\&. اگر صفر نباشد، تعداد کانال‌هایی را که قلاب از متغیر "channels" تفسیر می‌کند، محدود می‌سازد\&. .sp این متغیر را نمی‌توان از طریق متغیرهای پیکربندی VCS یا irker\&.conf تنظیم کرد؛ فقط می‌توان آن را با یک آرگومان خط فرمان تعیین کرد\&. بدین ترتیب، در یک سرویس میزبانی کد (forge) که در آن مالکان مخزن اجازه ندارند اسکریپت‌های post\-commit خود را تغییر دهند، مدیر سایت می‌تواند آن را تنظیم کند تا از هرزنامه‌پراکنی انبوه (shotgun spamming) توسط مالکان مخرب پروژه جلوگیری شود\&. با این حال، تنظیم آن روی مقداری کمتر از ۲ احتمالاً کار عاقلانه‌ای نخواهد بود\&. .RE .PP cialike .RS 4 اگر خالی نبوده و برابر با "None" (پیش‌فرض) نباشد، رفتار قدیمی سامانهٔ CIA را در حذف فهرست‌های طولانی فایل‌ها به نفع خلاصه‌ای به شکل (N files in M directories) شبیه‌سازی می‌کند\&. مقدار آن باید عددی باشد که آستانهٔ طول فهرست فایل‌ها را بر حسب نویسه مشخص کند\&. .RE .PP template .RS 4 الگوی مورد استفاده برای تولید پیام‌های اعلان را تعیین می‌کند\&. فقط در سامانه‌های کنترل نسخه‌ای که دارای متغیرهای پیکربندی هستند در دسترس است؛ در حال حاضر این به معنای git یا hg است\&. تمامی فیلدهای پایه کامیت و استخراج‌کننده، از جمله سوئیچ‌های رنگی، به عنوان جایگزین‌های %() در دسترس هستند\&. .RE .PP اسکریپت irkerhook\&.py هم تحت python 2 و هم تحت python 3 اجرا خواهد شد، اما هنوز از مخازن mercurial تحت python 3 پشتیبانی نمی‌کند\&..SS "git" .PP در git، روش معمول برای فراخوانی این قلاب (از درون قلاب update) به این صورت است که نام مرجع (refname) و به دنبال آن فهرستی از کامیت‌ها به آن ارسال می‌شود\&. از آنجا که \fBgit rev\-list\fR معمولاً کامیت‌ها را از جدیدترین به قدیمی‌ترین فهرست می‌کند، بهتر است از \-\-reverse استفاده کنید تا اعلان‌ها به ترتیب زمانی صادر شوند\&. در یک اسکریپت عادی update، نحوه فراخوانی باید به این شکل باشد: .sp .if n \{\ .RS 4 .\} .nf refname=$1 old=$2 new=$3 irkerhook\&.py \-\-refname=${refname} $(git rev\-list \-\-reverse ${old}\&.\&.${new}) .fi .if n \{\ .RE .\} .PP با این تفاوت که به یک مسیر مطلق برای irkerhook\&.py نیاز خواهید داشت\&. .PP به منظور آزمایش و سازگاری با نسخه‌های پیشین، اگر irkerhook\&.py را بدون هیچ آرگومانی فراخوانی کنید (مانند آنچه در قلاب post\-commit انجام می‌شود)، به گونه‌ای عمل خواهد کرد که گویی به این شکل فراخوانی شده است: .sp .if n \{\ .RS 4 .\} .nf irkerhook\&.py \-\-refname=refs/heads/master HEAD .fi .if n \{\ .RE .\} .PP با این حال، زمانی که روی یک شاخه غیرپیش‌فرض از یک مخزن bare دستور push را اجرا می‌کنید، این حالت نتیجه درستی ارائه نخواهد داد\&. .PP روش معمول برای نصب این قلاب در واقع قرار دادن آن در قلاب post\-receive است، چرا که تمام جزئیات لازم را دریافت می‌کند و در صورت بروز خطا، عملیات push را متوقف نخواهد کرد\&. از اسکریپت زیر استفاده کنید: .sp .if n \{\ .RS 4 .\} .nf #!/bin/sh echo "sending IRC notification" while read old new refname; do irkerhook \-\-refname=${refname} $(git rev\-list \-\-reverse ${old}\&.\&.${new}) done .fi .if n \{\ .RE .\} .PP تنظیمات ترجیحی را می‌توان در فایل config مخزن و در بخشی تحت عنوان [irker] مشخص کرد\&. در اینجا نمونه‌ای از ظاهر آن آمده است: .sp .if n \{\ .RS 4 .\} .nf [irker] project = gpsd color = ANSI channels = irc://chat\&.freenode\&.net/gpsd,irc://chat\&.freenode\&.net/commits .fi .if n \{\ .RE .\} .PP نباید متغیر "repository" را مقداردهی کنید (مقدار معادل آن محاسبه خواهد شد)\&. هیچ تلاشی برای تفسیر فایل irker\&.conf صورت نمی‌گیرد\&. .PP مقدار پیش‌فرض متغیر "project"، نام پایه (basename) دایرکتوری مخزن است\&. مقدار پیش‌فرض متغیر "urlprefix" برابر "cgit" است\&. .PP یک متغیر اختصاصی git به نام "revformat" وجود دارد که قالب شناسه کامیت را در اعلان کنترل می‌کند\&. این متغیر می‌تواند مقادیر زیر را داشته باشد: .PP raw .RS 4 شناسه کامل هگزادسیمال (hex) کامیت .RE .PP short .RS 4 ۱۲ نویسه نخست از شناسه هگزادسیمال .RE .PP describe .RS 4 توصیف نسبت به آخرین برچسب (tag)، و در صورت عدم امکان، استفاده از short .RE .PP مقدار پیش‌فرض \*(Aqdescribe\*(Aq است\&. .SS "Subversion" .PP در Subversion، irkerhook\&.py یک گزینه \-\-repository همراه با مقدار (مسیر مطلق مخزن Subversion) و یک آرگومان commit (شماره نگارش عددی کامیت) را می‌پذیرد\&. مقادیر پیش‌فرض به ترتیب دایرکتوری کاری فعلی و HEAD هستند\&. .PP با این حال توجه داشته باشید که شما \fIنمی‌توانید\fR آرگومان repository را در قلاب post\-commit در Subversion به مقدار پیش‌فرض رها کنید؛ این به دلیل محدودیتی در Subversion است، چرا که دریافت دایرکتوری جاری در داخل این قلاب‌ها قابل اطمینان نیست\&. در عوض، مقادیر باید همان دو آرگومانی باشند که Subversion به عنوان آرگومان به آن قلاب ارسال می‌کند\&. بنابراین، یک فراخوانی معمول در اسکریپت post\-commit به این شکل خواهد بود: .sp .if n \{\ .RS 4 .\} .nf REPO=$1 REV=$2 irkerhook\&.py \-\-repository=$REPO $REV .fi .if n \{\ .RE .\} .PP سایر تنظیمات به صورت \-\-variable=value نیز می‌توانند در خط فرمان مشخص شوند و هرگونه تنظیمی در فایل irker\&.conf را بازنویسی خواهند کرد\&. .PP مقدار پیش‌فرض متغیر project، نام پایه (basename) مخزن است\&. مقدار پیش‌فرض متغیر "urlprefix" برابر "viewcvs" است\&. .PP اگر یک فایل irker\&.conf در دایرکتوری ریشه مخزن وجود داشته باشد (نه دایرکتوری checkout، بلکه جایی که ساختارهای داخلی مانند فایل "format" قرار دارند)، قلاب تنظیمات متغیرها را از آن تفسیر خواهد کرد\&. در اینجا نمونه‌ای از ظاهر احتمالی چنین فایلی آورده شده است: .sp .if n \{\ .RS 4 .\} .nf # irkerhook variable settings for the irker project project = irker channels = irc://chat\&.freenode/irker,irc://chat\&.freenode/commits tcp = false .fi .if n \{\ .RE .\} .PP متغیرهای "repository" یا "commit" را در این فایل تنظیم نکنید؛ چرا که نتایج نامطلوبی در پی خواهد داشت\&. .PP هیچ متغیر اختصاصی برای Subversion وجود ندارد\&..SS "Mercurial" .PP در Mercurial، irkerhook\&.py می‌تواند به دو روش فراخوانی شود: یا به عنوان یک هوک Python (روش ترجیحی) یا به صورت یک اسکریپت\&. .PP برای فراخوانی آن به عنوان یک هوک Python، عبارت زیر را به بخش اعلان هوک «commit» یا «incoming» در مخزن Mercurial خود اضافه کنید: .sp .if n \{\ .RS 4 .\} .nf [hooks] incoming\&.irker = python:/path/to/irkerhook\&.py:hg_hook .fi .if n \{\ .RE .\} .PP هنگامی که به صورت یک اسکریپت فراخوانی می‌شود، این هوک گزینهٔ \-\-repository را همراه با مقدار (مسیر مطلق مخزن Mercurial) می‌پذیرد و می‌تواند یک آرگومان commit (شناسهٔ هش Mercurial کامیت یا ارجاعی به آن) را دریافت کند\&. مقدار پیش‌فرض برای آرگومان مخزن، دایرکتوری جاری است\&. آرگومان پیش‌فرض commit مقدار \*(Aq\-1\*(Aq است که کامیت tip فعلی را مشخص می‌کند\&. .PP همانند git، در هر دو حالت تمام متغیرها می‌توانند در فایل hgrc مخزن و در بخش [irker] تنظیم شوند\&. آرگومان‌های خط فرمان به صورت variable=value برای فراخوانی اسکریپت پذیرفته می‌شوند اما الزامی نیستند\&. هیچ تلاشی برای تفسیر فایل irker\&.conf صورت نمی‌گیرد\&. .PP مقدار پیش‌فرض متغیر «project» نام پایهٔ (basename) دایرکتوری مخزن است\&. مقدار پیش‌فرض متغیر «urlprefix» در صورت وجود، مقدار پیکربندی «web\&.baseurl» خواهد بود\&. .SS "فیلتر کردن (Filtering)" .PP امکان فیلتر کردن کامیت‌ها پیش از ارسال آن‌ها به irkerd وجود دارد\&. .PP باید گزینهٔ \fBfiltercmd\fR را مشخص کنید، که دستوری است که توسط irkerhook\&.py اجرا خواهد شد\&. این دستور باید یک آرگومان بپذیرد که نمایشی از فراداده‌های کامیت و استخراج‌کننده (شامل متغیر channels) در قالب JSON است\&. این دستور باید یک نمایش JSON از فراداده‌های (احتمالاً تغییریافته) را در خروجی استاندارد تولید کند\&. .PP در زیر یک فیلتر نمونه آمده است: .sp .if n \{\ .RS 4 .\} .nf #!/usr/bin/env python3 # This is a trivial example of a metadata filter\&. # All it does is change the name of the commit\*(Aqs author\&. # import sys, json metadata = json\&.loads(sys\&.argv[1]) metadata[\*(Aqauthor\*(Aq] = "The Great and Powerful Oz" print(json\&.dumps(metadata)) # end .fi .if n \{\ .RE .\} .PP خطای استاندارد (standard error) برای پیام‌های پیشرفت و خطا در دسترس هوک قرار دارد\&. .SH "گزینه‌ها (OPTIONS)" .PP irkerhook\&.py گزینه‌های زیر را می‌پذیرد: .PP \-n .RS 4 از ارسال به دیمن جلوگیری می‌کند\&. در عوض، درخواست JSON تولیدشده را در خروجی استاندارد می‌ریزد\&. برای اشکال‌زدایی مفید است\&. .RE .PP \-V .RS 4 نسخهٔ برنامه را در خروجی استاندارد چاپ کرده و خارج می‌شود\&. .RE .SH "همچنین ببینید (SEE ALSO)" .PP \fBirkerd\fR(8) .SH "نویسندگان (AUTHORS)" .PP Eric S\&. Raymond \&. برای به‌روزرسانی‌ها و سایر منابع به صفحهٔ پروژه در \m[blue]\fBhttp://www\&.catb\&.org/~esr/irker\fR\m[] مراجعه کنید\&.