GITPROTOCOL-CAPABILITIES(5) راهنمای گیت GITPROTOCOL-CAPABILITIES(5)

gitprotocol-capabilities - قابلیت‌های نسخه 0 و 1 پروتکل گیت

<over-the-wire-protocol>


نکته

این سند قابلیت‌های نسخه‌های ۰ و ۱ پروتکل بسته (pack protocol) را شرح می‌دهد. برای نسخه ۲، لطفاً به سند gitprotocol-v2(5) مراجعه کنید.

کارسازها (سرورها) باید (SHOULD) از تمام قابلیت‌های تعریف‌شده در این سند پشتیبانی کنند.

در نخستین خط از پاسخ اولیه کارساز در هر یک از دستورهای receive-pack و upload-pack، پس از اولین مرجع (reference) یک بایت NUL و سپس فهرستی از قابلیت‌های کارساز که با فاصله از هم جدا شده‌اند می‌آید. این قابلیت‌ها به کارساز امکان می‌دهد آنچه را که می‌تواند یا نمی‌تواند پشتیبانی کند به کلاینت اعلام نماید.

سپس کلاینت فهرستی از قابلیت‌های مدنظر خود را که با فاصله از یکدیگر جدا شده‌اند ارسال می‌کند. کلاینت «نباید» (MUST NOT) قابلیت‌هایی را که کارساز پشتیبانی از آن‌ها را اعلام نکرده است درخواست کند.

کارساز «باید» (MUST) در صورت ارسال قابلیت‌هایی که درک نمی‌کند، خطا را تشخیص داده و عملیات را متوقف سازد. کارساز «نباید» (MUST NOT) قابلیت‌هایی را که کلاینت درخواست کرده و کارساز تبلیغ نموده نادیده بگیرد. در نتیجه این قوانین، کارساز «نباید» قابلیت‌هایی را که نمی‌شناسد تبلیغ کند.

قابلیت‌های atomic، report-status، report-status-v2، delete-refs، quiet و push-cert توسط فرایند receive-pack (ارسال به کارساز / push) ارسال و شناسایی می‌شوند.

قابلیت‌های ofs-delta و side-band-64k توسط هر دو پروتکل upload-pack و receive-pack ارسال و شناسایی می‌شوند. قابلیت‌های agent و session-id نیز ممکن است به صورت اختیاری در هر دو پروتکل ارسال گردند.

سایر قابلیت‌ها فقط توسط فرایند upload-pack (دریافت از کارساز / fetch) شناسایی می‌شوند.

قابلیت multi_ack به کارساز اجازه می‌دهد به محض یافتن یک کامیت که بتواند به عنوان مبنای مشترک (common base) بین مجموعه‌های wants و have کلاینت استفاده شود، پاسخ "ACK obj-id continue" را بازگرداند.

با ارسال زودهنگام این پیام، کارساز می‌تواند مانع از پیمایش بیشتر کلاینت در آن شاخه خاص از تاریخچه مخزن شود. کلاینت ممکن است همچنان نیاز داشته باشد شاخه‌های دیگر را پیمایش کرده و خطوط have را برای آن‌ها ارسال کند تا زمانی که کارساز یک برش کامل روی DAG به دست آورد یا کلاینت اعلام "done" کند.

بدون multi_ack، کلاینت خطوط have را با ترتیب --date-order ارسال می‌کند تا زمانی که کارساز یک مبنای مشترک پیدا کند. این بدان معناست که کلاینت خطوط haveای را می‌فرستد که کارساز از قبل می‌داند مشترک هستند، زیرا از نظر زمانی با شاخه دیگری که کارساز هنوز مبنای مشترکی برای آن نیافته، هم‌پوشانی دارند.

برای مثال فرض کنید کلاینت کامیت‌هایی با حروف بزرگ دارد که کارساز فاقد آن‌هاست، و کارساز کامیت‌هایی با حروف کوچک دارد که کلاینت فاقد آن‌هاست، مانند نمودار زیر:

   +---- u ---------------------- x
  /              +----- y
 /              /
a -- b -- c -- d -- E -- F
   \
    +--- Q -- R -- S

اگر کلاینت x و y را بخواهد و با گفتن have F,S شروع کند، کارساز نمی‌داند F و S چیستند. سرانجام کلاینت "have d" را اعلام می‌کند و کارساز "ACK d continue" می‌فرستد تا به کلاینت اطلاع دهد پیمایش آن خط را متوقف کند (بنابراین c-b-a را ارسال نکند)، اما هنوز کار تمام نشده است و نیاز به یک مبنا برای x دارد. کلاینت با S-R-Q ادامه می‌دهد تا به a برسد؛ در این نقطه کارساز یک مبنای مشخص دارد و فرایند خاتمه می‌یابد.

بدون multi_ack، کلاینت به هر حال آن زنجیره c-b-a را در لابلای S-R-Q ارسال می‌کرد.

این افزونه‌ای برای multi_ack است که به کلاینت اجازه می‌دهد وضعیت درون‌حافظه‌ای کارساز را بهتر درک کند. برای اطلاعات بیشتر به بخش "Packfile Negotiation" در gitprotocol-pack(5) مراجعه کنید.

این قابلیت فقط باید با پروتکل smart HTTP استفاده شود. اگر هر دو قابلیت multi_ack_detailed و no-done وجود داشته باشند، فرستنده مجاز است بلافاصله پس از اولین پیام "ACK obj-id ready" بسته (pack) را ارسال کند.

بدون no-done در پروتکل smart HTTP، نشست کارساز به پایان می‌رسید و کلاینت مجبور بود قبل از ارسال بسته توسط کارساز، یک رفت و برگشت دیگر برای ارسال "done" انجام دهد. no-done این رفت و برگشت نهایی را حذف کرده و تا حدی تأخیر (latency) را کاهش می‌دهد.

یک «بسته کم‌حجم» (thin pack) بسته‌ای شامل دلتاهایی است که به اشیای مبنایی خارج از بسته اشاره می‌کنند (اما مشخص است که در طرف دریافت‌کننده وجود دارند). این کار می‌تواند ترافیک شبکه را به میزان قابل توجهی کاهش دهد، اما نیازمند آن است که طرف دریافت‌کننده بداند چگونه با افزودن اشیای مبنای گم‌شده، این بسته‌ها را «کامل» (thicken) کند.

کارساز upload-pack زمانی thin-pack را تبلیغ می‌کند که بتواند یک بسته کم‌حجم تولید و ارسال کند. کلاینت زمانی قابلیت thin-pack را درخواست می‌کند که بداند چگونه آن را کامل کند، و بدین وسیله به کارساز اعلام می‌کند که توانایی دریافت چنین بسته‌ای را دارد. کلاینت «نباید» (MUST NOT) قابلیت thin-pack را درخواست کند مگر اینکه بتواند یک thin pack را به یک بسته مستقل و خودکفا تبدیل نماید.

از سوی دیگر، به طور پیش‌فرض فرض می‌شود که receive-pack قادر به پردازش بسته‌های کم‌حجم است، اما می‌تواند با اعلام قابلیت no-thin از کلاینت بخواهد از این ویژگی استفاده نکند. در صورتی که کارساز قابلیت no-thin را اعلام کند، کلاینت «نباید» (MUST NOT) بسته کم‌حجم ارسال نماید.

دلایل این عدم تقارن، تاریخی است. برنامه receive-pack تا پس از ابداع thin pack وجود نداشت، بنابراین از لحاظ تاریخی پیاده‌سازی مرجع receive-pack همیشه thin pack را درک می‌کرد. اضافه شدن قابلیت no-thin در ادامه به receive-pack اجازه داد تا این ویژگی را با حفظ سازگاری رو به عقب غیرفعال کند.

این قابلیت به این معنی است که کارساز می‌تواند گزارش‌های پیشرفت چندگانه (multiplexed) و اطلاعات خطا را به صورت درهم‌آمیخته با خود پرونده بسته (packfile) ارسال کند و کلاینت قادر به درک آن است.

این دو گزینه مانعةالجمع (mutually exclusive) هستند. یک کلاینت مدرن همیشه side-band-64k را ترجیح می‌دهد.

هر دو حالت نشان می‌دهند که داده‌های packfile به صورت قطعاتی حداکثر تا ۱۰۰۰ بایت در حالت side_band یا ۶۵۵۲۰ بایت در حالت side_band_64k جاری‌سازی (stream) می‌شوند. هر بسته شامل یک پیشوند ۴ بایتی pkt-line برای طول داده درون بسته، یک بایت کد جریان (stream code) و سپس داده‌های واقعی است.

کد جریان می‌تواند یکی از موارد زیر باشد:

1 - داده‌های بسته (pack data)
2 - پیام‌های پیشرفت (progress messages)
3 - پیام خطای مهلک پیش از توقف جریان (fatal error message)

قابلیت "side-band-64k" به عنوان راهکاری برای کلاینت‌های جدیدتر پدید آمد تا بتوانند بسته‌های بسیار بزرگ‌تر و تقریباً پر را درخواست کنند، در حالی که سازگاری رو به عقب برای کلاینت‌های قدیمی‌تر حفظ شود.

علاوه بر این، در side-band با پیام‌های حداکثر ۱۰۰۰ بایتی، در واقع ۹۹۹ بایت بار داده (payload) و ۱ بایت برای کد جریان اختصاص دارد. در side-band-64k نیز به همین ترتیب، حداکثر ۶۵۵۱۹ بایت داده و ۱ بایت برای کد جریان وجود دارد.

کلاینت «باید» (MUST) فقط یکی از "side-band" یا "side-band-64k" را ارسال کند. در صورتی که کلاینت هر دو را درخواست نماید، کارساز «باید» (MUST) آن را به عنوان خطا تشخیص دهد.

کارساز می‌تواند PACKv2 را با دلتایی ارسال کند که به جای obj-id، بر اساس موقعیت در بسته (offset) به شیء مبنای خود اشاره دارد و کلاینت قادر به درک آن است. به عبارت دیگر، آن‌ها می‌توانند OBJ_OFS_DELTA (معروف به نوع ۶) را در یک packfile ارسال کنند یا بخوانند.

کارساز ممکن است به صورت اختیاری قابلیتی به فرم agent=X ارسال کند تا به کلاینت اطلاع دهد که کارساز نسخه X را اجرا می‌کند. کلاینت نیز می‌تواند به صورت اختیاری با ارسال قابلیت agent=Y رشته عامل (agent) خود را بازگرداند (اما اگر کارساز به قابلیت agent اشاره نکرده باشد، کلاینت «نباید» این کار را انجام دهد). رشته‌های X و Y می‌توانند شامل هر نویسه اسکی قابل چاپ به جز فاصله باشند (یعنی محدوده بایتی 32 < x < 127) و معمولاً به صورت "package/version" (مانند "git/1.8.3.1") هستند. رشته‌های عامل صرفاً جنبه اطلاع‌رسانی برای آمارگیری و اشکال‌زدایی دارند و «نباید» (MUST NOT) برای استنتاج برنامه‌نویسی‌شده از وجود یا عدم وجود ویژگی‌های خاص استفاده شوند.

این قابلیت که یک الگوریتم درهم‌سازی (hash algorithm) را به عنوان آرگومان می‌گیرد، نشان می‌دهد که کارساز از الگوریتم‌های درهم‌سازی داده‌شده پشتیبانی می‌کند. این قابلیت ممکن است چند بار ارسال شود؛ در این صورت، اولین مورد ذکرشده همان مقداری است که در اعلان مراجع (ref advertisement) استفاده می‌شود.

هنگامی که توسط کلاینت ارائه شود، نشان می‌دهد که قصد دارد از الگوریتم درهم‌سازی داده‌شده برای ارتباط استفاده کند. الگوریتم ارائه‌شده باید یکی از الگوریتم‌های پشتیبانی‌شده توسط کارساز باشد.

اگر این قابلیت ارائه نشود، فرض بر این است که تنها الگوریتم پشتیبانی‌شده SHA-1 است.

این قابلیت پارامتریک برای اطلاع دادن به گیرنده در این مورد به کار می‌رود که کدام مرجع نمادین (symbolic ref) به کدام مرجع اشاره می‌کند؛ برای مثال، "symref=HEAD:refs/heads/master" به گیرنده می‌گوید که HEAD به master اشاره دارد. این قابلیت می‌تواند برای نمایش چندین symref تکرار شود.

کارسازها در صورتی که HEAD یکی از مراجع در حال ارسال باشد، «باید» (SHOULD) این قابلیت را برای مرجع نمادین HEAD بگنجانند.

کلاینت‌ها «می‌توانند» (MAY) از پارامترهای این قابلیت برای انتخاب شاخه اولیه مناسب هنگام کلون کردن یک مخزن استفاده کنند.

این قابلیت دستورهای "deepen"، "shallow" و "unshallow" را به پروتکل fetch-pack/upload-pack اضافه می‌کند تا کلاینت‌ها بتوانند کلون‌های کم‌عمق (shallow clones) را درخواست کنند.

این قابلیت دستور "deepen-since" را به پروتکل fetch-pack/upload-pack اضافه می‌کند تا کلاینت بتواند کلون‌های کم‌عمقی را درخواست کند که به جای عمق، بر اساس یک زمان مشخص برش خورده‌اند. از نظر درونی این کار معادل اجرای "rev-list --max-age=<timestamp>" در سمت کارساز است. "deepen-since" نمی‌تواند همراه با "deepen" استفاده شود.

این قابلیت دستور "deepen-not" را به پروتکل fetch-pack/upload-pack اضافه می‌کند تا کلاینت بتواند کلون‌های کم‌عمقی را درخواست کند که به جای عمق، در یک بازنگری (revision) خاص برش خورده‌اند. از نظر درونی این کار معادل اجرای "rev-list --not <rev>" در سمت کارساز است. "deepen-not" نمی‌تواند همراه با "deepen" استفاده شود، اما می‌تواند با "deepen-since" به کار رود.

در صورت درخواست این قابلیت توسط کلاینت، معناشناسی دستور "deepen" تغییر می‌کند. آرگومان "depth" به جای عمق نسبت به مراجع دوردست، عمق نسبت به مرز کم‌عمق فعلی خواهد بود.

کلاینت با دستور "git clone -q" یا دستوری مشابه شروع به کار کرده و نیازی به باند جانبی ۲ (side band 2) ندارد. در واقع کلاینت اعلام می‌کند که «من تمایلی به دریافت جریان ۲ روی sideband ندارم، بنابراین آن را برای من ارسال نکنید و اگر ارسال کنید، آن را نادیده گرفته و دور می‌ریزم». با این حال، کانال جانبی ۳ همچنان برای پاسخ‌های خطا استفاده می‌شود.

قابلیت include-tag مربوط به ارسال برچسب‌های دارای یادداشت (annotated tags) در صورتی است که اشیایی که به آن‌ها اشاره دارند در حال ارسال باشند. اگر شیئی را برای کلاینت بسته‌بندی کنیم و یک شیء برچسب دقیقاً به همان شیء اشاره کند، شیء برچسب را نیز بسته‌بندی می‌کنیم. به طور کلی این قابلیت به کلاینت اجازه می‌دهد تا تمام برچسب‌های یادداشت‌دار جدید را هنگام دریافت یک شاخه، در قالب یک اتصال شبکه واحد دریافت کند.

کلاینت‌ها «می‌توانند» (MAY) زمانی که کارساز این قابلیت را تبلیغ می‌کند، همیشه include-tag را در درخواست ارسال کنند. تصمیم کلاینت برای درخواست include-tag صرفاً به تمایل کلاینت برای دریافت داده‌های برچسب بستگی دارد، بدون توجه به اینکه آیا کارساز اشیایی را در فضای نام refs/tags/* تبلیغ کرده است یا خیر.

کارسازها در صورتی که شیء مرجع برچسب بسته‌بندی شده باشد و کلاینت include-tags را درخواست کرده باشد، «باید» (MUST) برچسب‌ها را بسته‌بندی کنند.

کلاینت‌ها «باید» (MUST) برای حالتی که کارساز include-tag را نادیده گرفته و برچسب‌ها را در بسته ارسال نکرده است آماده باشند. در چنین مواردی کلاینت «باید» (SHOULD) یک درخواست fetch بعدی برای به دست آوردن برچسب‌هایی که در غیر این صورت include-tag به کلاینت می‌داد، ارسال کند.

کارساز در صورت پشتیبانی از include-tag «باید» (SHOULD) آن را ارسال کند، بدون در نظر گرفتن اینکه آیا برچسبی در دسترس هست یا خیر.

فرایند receive-pack می‌تواند قابلیت report-status را دریافت کند که نشان می‌دهد کلاینت گزارشی از اتفاقات پس از بارگذاری packfile و به‌روزرسانی مراجع می‌خواهد. اگر کلاینت ارسال‌کننده (pushing client) این قابلیت را درخواست کند، پس از باز کردن بسته و به‌روزرسانی مراجع، کارساز با وضعیت موفقیت‌آمیز بودن باز شدن بسته و به‌روزرسانی تک‌تک مراجع پاسخ خواهد داد. اگر هر یک از آن‌ها ناموفق باشد، پیام خطایی بازمی‌گرداند. برای پیام‌های نمونه به gitprotocol-pack(5) مراجعه کنید.

قابلیت report-status-v2 با افزودن دستورالعمل‌های جدید "option"، قابلیت report-status را گسترش می‌دهد تا از مراجع بازنویسی‌شده توسط قلاب (hook) موسوم به "proc-receive" پشتیبانی کند. قلاب "proc-receive" ممکن است فرمانی را برای یک شبه‌مرجع (pseudo-reference) پردازش کند که مرجعی با نام دیگر، new-oid و old-oid متفاوت ایجاد یا به‌روزرسانی نماید، در حالی که قابلیت report-status قادر به گزارش‌دهی برای چنین حالتی نیست. برای جزئیات به gitprotocol-pack(5) مراجعه کنید.

در صورتی که کارساز قابلیت delete-refs را بازگرداند، به این معنی است که قادر به پذیرش مقدار صفر (zero-id) به عنوان مقدار هدف برای به‌روزرسانی مرجع است. این قابلیت توسط کلاینت بازگردانده نمی‌شود، بلکه صرفاً به کلاینت اطلاع می‌دهد که می‌تواند مقادیر zero-id را برای حذف مراجع ارسال کند.

اگر کارساز receive-pack قابلیت quiet را تبلیغ کند، قادر به متوقف کردن خروجی پیشرفت خوانا برای انسان است که در غیر این صورت هنگام پردازش بسته دریافتی نمایش داده می‌شد. کلاینت send-pack باید در صورتی که گزارش پیشرفت محلی نیز متوقف شده است (مثلاً از طریق push -q، یا اگر خروجی خطای استاندارد stderr به tty متصل نباشد)، با قابلیت quiet پاسخ دهد تا گزارش پیشرفت در سمت کارساز را سرکوب کند.

اگر کارساز قابلیت atomic را ارسال کند، قادر به پذیرش ارسال‌های اتمیک (atomic pushes) است. اگر کلاینت ارسال‌کننده این قابلیت را درخواست کند، کارساز مراجع را در یک تراکنش اتمیک به‌روزرسانی خواهد کرد؛ به این معنی که یا همه مراجع به‌روزرسانی می‌شوند یا هیچ‌کدام.

اگر کارساز قابلیت push-options را ارسال کند، قادر است گزینه‌های push را پس از ارسال دستورهای به‌روزرسانی اما پیش از جاری‌سازی packfile بپذیرد. در صورتی که کلاینت ارسال‌کننده این قابلیت را درخواست کند، کارساز این گزینه‌ها را به قلاب‌های pre-receive و post-receive که این درخواست push را پردازش می‌کنند، منتقل خواهد کرد.

اگر کارساز upload-pack این قابلیت را تبلیغ کند، fetch-pack ممکن است خطوط "want" را با نام اشیایی ارسال کند که در کارساز وجود دارند اما توسط upload-pack تبلیغ نشده‌اند. به دلایل تاریخی، نام این قابلیت شامل "sha1" است. نام‌های اشیاء همیشه با استفاده از قالب شیء توافق‌شده از طریق قابلیت object-format مشخص می‌شوند.

اگر کارساز upload-pack این قابلیت را تبلیغ کند، fetch-pack می‌تواند خطوط "want" را با نام اشیایی که در کارساز قابل دسترسی هستند اما مستقیماً توسط upload-pack تبلیغ نشده‌اند ارسال کند. به دلایل تاریخی، نام این قابلیت شامل "sha1" است. نام‌های اشیاء همیشه با استفاده از قالب شیء توافق‌شده از طریق قابلیت object-format ارائه می‌شوند.

کارساز receive-pack که این قابلیت را تبلیغ می‌کند، مایل به پذیرش گواهی push امضاشده است و درخواست می‌کند که <nonce> در گواهی push گنجانده شود. کلاینت send-pack «نباید» (MUST NOT) بسته push-cert ارسال کند مگر اینکه کارساز receive-pack این قابلیت را تبلیغ کرده باشد.

در صورتی که کارساز upload-pack قابلیت filter را تبلیغ کند، fetch-pack می‌تواند دستورهای "filter" را برای درخواست یک کلون جزئی (partial clone) یا دریافت جزئی (partial fetch) ارسال کند و از کارساز بخواهد که اشیای مختلفی را از packfile حذف کند.

کارساز ممکن است یک شناسه نشست (session ID) را تبلیغ کند که می‌تواند برای شناسایی این فرایند در میان چندین درخواست استفاده شود. کلاینت نیز می‌تواند شناسه نشست خود را به کارساز اعلام کند.

شناسه‌های نشست باید برای یک فرایند مشخص، یکتا باشند. آن‌ها باید در یک packet-line جا شوند و نباید حاوی نویسه‌های غیرقابل‌چاپ یا فاصله باشند. پیاده‌سازی فعلی از شناسه‌های نشست trace2 استفاده می‌کند (برای جزئیات به api-trace2[1] مراجعه کنید)، اما این ممکن است تغییر کند و کاربرانِ شناسه نشست نباید به این موضوع اتکا کنند.

بخشی از مجموعه git(1)

1.
api-trace2
file:///usr/share/doc/git-doc/technical/api-trace2.html
2026-06-29 Git 2.55.0