'\" t
.\"     Title: gitprotocol-v2
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2026-06-29
.\"    Manual: راهنمای Git
.\"    Source: Git 2.55.0
.\"  Language: Persian
.\"
.TH "GITPROTOCOL\-V2" "5" "2026\-06\-29" "Git 2\&.55\&.0" "راهنمای Git"
.\" -----------------------------------------------------------------
.\" * 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)"
gitprotocol-v2 \- پروتکل ارتباطی گیت (Wire Protocol)، نسخه ۲
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
<over\-the\-wire\-protocol>
.fi
.sp
.SH "توضیحات (DESCRIPTION)"
.sp
این سند مشخصات فنی نسخه ۲ پروتکل ارتباطی گیت (Wire Protocol) را ارائه می‌دهد\&. پروتکل نسخه ۲ نسبت به نسخه ۱ از راه‌های زیر بهبود یافته است:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
به جای چندین نام سرویس، چندین دستور توسط یک سرویس واحد پشتیبانی می‌شوند
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
به‌سادگی قابل گسترش است، زیرا قابلیت‌ها (capabilities) به بخش مجزای خود در پروتکل منتقل شده‌اند و دیگر پشت یک بایت NUL پنهان نبوده و به اندازه یک pkt\-line محدود نیستند
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
جداسازی سایر اطلاعات پنهان‌شده پشت بایت‌های NUL (مثلاً رشته agent به عنوان یک قابلیت، و symrefها که می‌توانند با استفاده از
\fIls\-refs\fR
درخواست شوند)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اعلان ارجاعات (reference advertisement) حذف خواهد شد مگر اینکه صراحتاً درخواست شود
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
دستور ls\-refs برای درخواست صریح برخی از ارجاعات (refs)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
طراحی شده با در نظر گرفتن http و stateless\-rpc\&. با مفاهیم واضح تخلیه (flush semantics)، برنامه کمکی راه دور http می‌تواند به سادگی به عنوان یک پراکسی عمل کند
.RE
.sp
در پروتکل نسخه ۲ ارتباطات دستور\-محور هستند\&. در اولین تماس با یک سرور، فهرستی از قابلیت‌ها اعلان خواهد شد\&. برخی از این قابلیت‌ها دستوراتی هستند که کلاینت می‌تواند اجرای آن‌ها را درخواست کند\&. پس از اتمام یک دستور، کلاینت می‌تواند از اتصال مجدداً استفاده کرده و اجرای دستورات دیگری را درخواست نماید\&.
.SH "چارچوب‌بندی بسته‌-خط (PACKET\-LINE FRAMING)"
.sp
تمام ارتباطات با استفاده از قالب‌بندی بسته‌-خط (packet\-line framing) انجام می‌شود، دقیقاً مانند نسخه ۱\&. برای اطلاعات بیشتر به \fBgitprotocol-pack\fR(5) و \fBgitprotocol-common\fR(5) مراجعه کنید\&.
.sp
در پروتکل نسخه ۲ این بسته‌های ویژه دارای معانی زیر خواهند بود:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fI0000\fR
بسته تخلیه (flush\-pkt) \- پایان یک پیام را نشان می‌دهد
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fI0001\fR
بسته جداکننده (delim\-pkt) \- بخش‌های یک پیام را از هم جدا می‌کند
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fI0002\fR
بسته پایان پاسخ (response\-end\-pkt) \- پایان یک پاسخ را برای اتصالات بدون وضعیت (stateless) نشان می‌دهد
.RE
.SH "درخواست اولیه کلاینت (INITIAL CLIENT REQUEST)"
.sp
به طور کلی یک کلاینت می‌تواند با ارسال \fBversion=2\fR از طریق کانال جانبی مربوط به انتقالِ در حال استفاده، که در نهایت متغیر \fBGIT_PROTOCOL\fR را تنظیم می‌کند، درخواست استفاده از پروتکل نسخه ۲ را بدهد\&. اطلاعات بیشتر را می‌توان در \fBgitprotocol-pack\fR(5) و \fBgitprotocol-http\fR(5) و همچنین تعریف \fBGIT_PROTOCOL\fR در \fBgit\fR(1) یافت\&. در تمام موارد پاسخ سرور اعلان قابلیت‌ها است\&.
.SS "پروتکل انتقال Git (Git Transport)"
.sp
هنگام استفاده از پروتکل انتقال git://، می‌توانید با ارسال "version=2" به عنوان یک پارامتر اضافی درخواست استفاده از پروتکل نسخه ۲ را داشته باشید:
.sp
.if n \{\
.RS 4
.\}
.nf
003egit\-upload\-pack /project\&.git\e0host=myserver\&.com\e0\e0version=2\e0
.fi
.if n \{\
.RE
.\}
.SS "پروتکل‌های انتقال SSH و File (SSH and File Transport)"
.sp
هنگام استفاده از هر یک از پروتکل‌های انتقال ssh:// یا file://، متغیر محیطی GIT_PROTOCOL باید صراحتاً شامل "version=2" تنظیم شود\&. ممکن است لازم باشد سرور به گونه‌ای پیکربندی شود که اجازه عبور این متغیر محیطی را بدهد\&.
.SS "پروتکل انتقال HTTP (HTTP Transport)"
.sp
هنگام استفاده از پروتکل انتقال http:// یا https:// کلاینت یک درخواست "هوشمند" info/refs همان‌طور که در \fBgitprotocol-http\fR(5) توضیح داده شده است ارسال می‌کند و با ارائه "version=2" در سرآیند \fBGit\-Protocol\fR درخواست می‌کند که از نسخه ۲ استفاده شود\&.
.sp
.if n \{\
.RS 4
.\}
.nf
C: GET $GIT_URL/info/refs?service=git\-upload\-pack HTTP/1\&.0
C: Git\-Protocol: version=2
.fi
.if n \{\
.RE
.\}
.sp
یک سرور نسخه ۲ به این صورت پاسخ می‌دهد:
.sp
.if n \{\
.RS 4
.\}
.nf
S: 200 OK
S: <Some headers>
S: \&.\&.\&.
S:
S: 000eversion 2\en
S: <capability\-advertisement>
.fi
.if n \{\
.RE
.\}
.sp
درخواست‌های بعدی سپس مستقیماً به سرویس \fB$GIT_URL/git\-upload\-pack\fR ارسال می‌شوند\&. (این فرآیند برای git\-receive\-pack نیز یکسان است)\&.
.sp
از گزینه \fB\-\-http\-backend\-info\-refs\fR برای \fBgit-upload-pack\fR(1) استفاده می‌کند\&.
.sp
ممکن است لازم باشد سرور پیکربندی شود تا محتویات این سرآیند را از طریق متغیر \fBGIT_PROTOCOL\fR منتقل کند\&. به توضیحات موجود در \fBgit-http-backend\fR(1) مراجعه کنید\&.
.SH "اعلان قابلیت‌ها (CAPABILITY ADVERTISEMENT)"
.sp
سروری که تصمیم می‌گیرد (بر اساس درخواست کلاینت) با استفاده از پروتکل نسخه ۲ ارتباط برقرار کند، با ارسال یک رشته نسخه در پاسخ اولیه خود و به دنبال آن اعلان قابلیت‌های خود، به کلاینت اطلاع می‌دهد\&. هر قابلیت یک کلید (key) با یک مقدار (value) اختیاری است\&. کلاینت‌ها باید تمام کلیدهای ناشناخته را نادیده بگیرند\&. معنای مقادیر ناشناخته به تعریف هر کلید واگذار می‌شود\&. برخی از قابلیت‌ها دستوراتی را توصیف می‌کنند که کلاینت می‌تواند اجرای آن‌ها را درخواست کند\&.
.sp
.if n \{\
.RS 4
.\}
.nf
capability\-advertisement = protocol\-version
                           capability\-list
                           flush\-pkt
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
protocol\-version = PKT\-LINE("version 2" LF)
capability\-list = *capability
capability = PKT\-LINE(key[=value] LF)
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
key = 1*(ALPHA | DIGIT | "\-_")
value = 1*(ALPHA | DIGIT | " \-_\&.,?\e/{}[]()<>!@#$%^&*+=:;")
.fi
.if n \{\
.RE
.\}
.SH "درخواست دستور (COMMAND REQUEST)"
.sp
پس از دریافت اعلان قابلیت‌ها، کلاینت می‌تواند درخواستی برای انتخاب دستور مورد نظر خود همراه با هرگونه قابلیت یا آرگومان خاص ارسال کند\&. سپس یک بخش اختیاری وجود دارد که کلاینت می‌تواند هرگونه پارامتر یا پرس‌وجوی مخصوص دستور را ارائه دهد\&. در هر زمان تنها یک دستور واحد می‌تواند درخواست شود\&.
.sp
.if n \{\
.RS 4
.\}
.nf
request = empty\-request | command\-request
empty\-request = flush\-pkt
command\-request = command
                  capability\-list
                  delim\-pkt
                  command\-args
                  flush\-pkt
command = PKT\-LINE("command=" key LF)
command\-args = *command\-specific\-arg
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
command\-specific\-args are packet line framed arguments defined by
each individual command\&.
.fi
.if n \{\
.RE
.\}
.sp
سپس سرور بررسی خواهد کرد تا اطمینان حاصل کند که درخواست کلاینت شامل یک دستور معتبر و همچنین قابلیت‌های معتبری است که اعلان شده بودند\&. اگر درخواست معتبر باشد، سرور دستور را اجرا خواهد کرد\&. سرور پیش از صدور پاسخ، حتماً باید (MUST) منتظر بماند تا کل درخواست کلاینت را دریافت کند\&. قالب پاسخ توسط دستوری که اجرا می‌شود تعیین می‌گردد، اما در همه موارد یک flush\-pkt نشان‌دهنده پایان پاسخ است\&.
.sp
هنگامی که یک دستور به پایان رسید و کلاینت تمام پاسخ را از سرور دریافت کرد، کلاینت می‌تواند درخواست اجرای دستور دیگری را بدهد یا می‌تواند اتصال را قطع کند\&. کلاینت می‌تواند به صورت اختیاری یک درخواست خالی شامل فقط یک flush\-pkt ارسال کند تا نشان دهد که درخواست دیگری ارسال نخواهد شد\&.
.SH "قابلیت‌ها (CAPABILITIES)"
.sp
دو نوع مختلف از قابلیت‌ها وجود دارد: قابلیت‌های عادی، که می‌توانند برای انتقال اطلاعات یا تغییر رفتار یک درخواست استفاده شوند، و دستورات، که اقدامات اصلی هستند که یک کلاینت می‌خواهد انجام دهد (fetch، push، و غیره)\&.
.sp
پروتکل نسخه ۲ به طور پیش‌فرض بدون وضعیت (stateless) است\&. این بدان معناست که تمام دستورات فقط باید یک دور (single round) دوام داشته باشند و از دید سمت سرور بدون وضعیت باشند، مگر اینکه کلاینت قابلیتی را درخواست کرده باشد که نشان دهد وضعیت باید توسط سرور حفظ شود\&. کلاینت‌ها برای عملکرد صحیح نباید نیازمند مدیریت وضعیت در سمت سرور باشند (MUST NOT)\&. این امر امکان توزیع بار چرخشی ساده (round\-robin load\-balancing) را در سمت سرور بدون نیاز به نگرانی در مورد مدیریت وضعیت فراهم می‌کند\&.
.SS "agent"
.sp
سرور می‌تواند قابلیت \fBagent\fR را با مقدار \fBX\fR (به صورت \fBagent=X\fR) اعلان کند تا به کلاینت اطلاع دهد که سرور در حال اجرای نسخه \fBX\fR است\&. کلاینت می‌تواند به صورت اختیاری با گنجاندن قابلیت \fBagent\fR با مقدار \fBY\fR (به صورت \fBagent=Y\fR) در درخواست خود به سرور، رشته agent خود را ارسال کند (اما اگر سرور قابلیت agent را اعلان نکرده باشد، کلاینت نباید این کار را انجام دهد - MUST NOT)\&. رشته‌های \fBX\fR و \fBY\fR می‌توانند شامل هر نویسه قابل چاپ ASCII به جز فاصله باشند (یعنی محدوده بایتی ۳۳ \(la x \(la ۱۲۶)، و معمولاً به صورت "package/version\-os" هستند (مانند "git/1\&.8\&.3\&.1\-Linux") که در آن \fBos\fR نام سیستم‌عامل است (مانند "Linux")\&. \fBX\fR و \fBY\fR را می‌توان با استفاده از متغیر محیطی GIT_USER_AGENT پیکربندی کرد و این متغیر اولویت دارد\&. مقدار \fBos\fR با استفاده از فیلد \fIsysname\fR از فراخوانی سیستمی \fBuname\fR(\fB2\fR) یا معادل آن بازیابی می‌شود\&. رشته‌های agent صرفاً جنبه اطلاعاتی برای آمار و اهداف اشکال‌زدایی دارند و نباید (MUST NOT) برای فرض برنامه‌نویسی‌شده مبنی بر وجود یا عدم وجود ویژگی‌های خاص مورد استفاده قرار گیرند\&.
.SS "ls\-refs"
.sp
\fBls\-refs\fR دستوری است که برای درخواست اعلان ارجاعات (reference advertisement) در نسخه ۲ استفاده می‌شود\&. برخلاف اعلان ارجاعات فعلی، ls\-refs آرگومان‌هایی دریافت می‌کند که می‌توان از آن‌ها برای محدود کردن ارجاعات ارسالی از سرور استفاده کرد\&.
.sp
ویژگی‌های اضافی که در دستور پایه پشتیبانی نمی‌شوند، به عنوان مقدار دستور در اعلان قابلیت‌ها به صورت فهرستی از ویژگی‌ها که با فاصله جدا شده‌اند اعلان خواهند شد: "<command>=<feature\-1> <feature\-2>"
.sp
دستور ls\-refs آرگومان‌های زیر را دریافت می‌کند:
.sp
.if n \{\
.RS 4
.\}
.nf
symrefs
    علاوه بر شیئی که به آن اشاره شده، هنگام نمایش یک ارجاع نمادین (symbolic ref)،
    ارجاع زیربنایی که به آن اشاره دارد را نیز نمایش می‌دهد\&.
peel
    برچسب‌های پوسته‌گیری‌شده (peeled tags) را نشان می‌دهد\&.
ref\-prefix <prefix>
    در صورت مشخص شدن، فقط ارجاعاتی نمایش داده می‌شوند که پیشوندی مطابق
    با یکی از پیشوندهای ارائه‌شده داشته باشند\&. می‌توان چندین مورد را مشخص کرد،
    که در این صورت ارجاعات مطابق با هر یک از پیشوندها نشان داده خواهند شد\&.
    توجه داشته باشید که این صرفاً برای بهینه‌سازی است؛ سرور در صورت تمایل
    می‌تواند (MAY) ارجاعاتی را که با پیشوند مطابقت ندارند نیز نشان دهد،
    و کلاینت‌ها باید خودشان نتیجه را فیلتر کنند\&.
.fi
.if n \{\
.RE
.\}
.sp
اگر ویژگی \fIunborn\fR اعلان شده باشد، آرگومان زیر را می‌توان در درخواست کلاینت گنجاند\&.
.sp
.if n \{\
.RS 4
.\}
.nf
unborn
    سرور اطلاعات مربوط به HEAD را حتی اگر یک symref اشاره‌کننده به یک شاخه
    ایجاد‌نشده (unborn branch) باشد به صورت "unborn HEAD symref\-target:<target>"
    ارسال خواهد کرد\&.
.fi
.if n \{\
.RE
.\}
.sp
خروجی ls\-refs به شرح زیر است:
.sp
.if n \{\
.RS 4
.\}
.nf
output = *ref
         flush\-pkt
obj\-id\-or\-unborn = (obj\-id | "unborn")
ref = PKT\-LINE(obj\-id\-or\-unborn SP refname *(SP ref\-attribute) LF)
ref\-attribute = (symref | peeled)
symref = "symref\-target:" symref\-target
peeled = "peeled:" obj\-id
.fi
.if n \{\
.RE
.\}
.SS "fetch"
.sp
\fBfetch\fR دستوری است که برای دریافت packfile در نسخه ۲ استفاده می‌شود\&. می‌توان آن را به عنوان یک نسخه اصلاح‌شده از fetch نسخه ۱ در نظر گرفت که در آن ref\-advertisement حذف شده است (زیرا دستور \fBls\-refs\fR این نقش را پر می‌کند) و قالب پیام برای حذف افزونگی‌ها و امکان افزودن آسان الحاقات آینده اصلاح شده است\&.
.sp
ویژگی‌های اضافی که در دستور پایه پشتیبانی نمی‌شوند، به عنوان مقدار دستور در اعلان قابلیت‌ها به صورت فهرستی از ویژگی‌ها که با فاصله جدا شده‌اند اعلان خواهند شد: "<command>=<feature\-1> <feature\-2>"
.sp
یک درخواست \fBfetch\fR می‌تواند آرگومان‌های زیر را بپذیرد:
.sp
.if n \{\
.RS 4
.\}
.nf
want <oid>
    شیئی را به سرور نشان می‌دهد که کلاینت می‌خواهد آن را بازیابی کند\&.
    مقادیر want می‌توانند هر چیزی باشند و محدود به اشیاء اعلان‌شده نیستند\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
have <oid>
    شیئی را به سرور نشان می‌دهد که کلاینت به صورت محلی دارد\&.
    این به سرور اجازه می‌دهد تا یک packfile بسازد که فقط شامل اشیاء مورد
    نیاز کلاینت باشد\&. می‌توان چندین خط \*(Aqhave\*(Aq ارسال کرد\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
done
    به سرور نشان می‌دهد که مذاکره باید پایان یابد (یا در صورت انجام clone،
    اصلاً آغاز نشود) و سرور باید از اطلاعات ارائه‌شده در درخواست برای
    ساخت packfile استفاده کند\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
thin\-pack
    درخواست می‌کند که یک thin pack ارسال شود، که یک بسته با دلتاهایی است که
    به اشیاء پایه‌ای اشاره می‌کنند که درون بسته قرار ندارند (اما مشخص است که
    در سمت دریافت‌کننده وجود دارند)\&. این می‌تواند ترافیک شبکه را به طور چشمگیری
    کاهش دهد، اما دریافت‌کننده باید بداند چگونه با افزودن پایه‌های از دست رفته به بسته،
    این بسته‌ها را "ضخیم" (thicken) کند\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
no\-progress
    درخواست می‌کند که اطلاعات پیشرفت که معمولاً در حین انتقال packfile روی کانال
    جانبی ۲ (side\-band channel 2) ارسال می‌شود، ارسال نشود\&. با این حال، کانال
    جانبی ۳ همچنان برای پاسخ‌های خطا استفاده می‌شود\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
include\-tag
    درخواست می‌کند که اگر اشیایی که برچسب‌های حاشیه‌نویسی‌شده (annotated tags)
    به آن‌ها اشاره دارند در حال ارسال هستند، آن برچسب‌ها نیز ارسال شوند\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
ofs\-delta
    نشان می‌دهد که کلاینت PACKv2 را با دلتایی که به جای oid، بر اساس موقعیت
    در بسته به پایه خود اشاره می‌کند، درک می‌کند\&. یعنی می‌تواند OBJ_OFS_DELTA
    (معروف به نوع ۶) را در یک packfile بخواند\&.
.fi
.if n \{\
.RE
.\}
.sp
اگر ویژگی \fIshallow\fR اعلان شده باشد، آرگومان‌های زیر را می‌توان در درخواست کلاینت‌ها گنجاند و همچنین بخش \fIshallow\-info\fR ممکن است به پاسخ سرور اضافه شود، همان‌طور که در زیر توضیح داده شده است\&.
.sp
.if n \{\
.RS 4
.\}
.nf
shallow <oid>
    کلاینت باید سرور را از تمام کامیت‌هایی که فقط کپی‌های کم‌عمق (shallow) از آن‌ها
    دارد (به این معنی که والدین یک کامیت را ندارد) با ارسال یک خط \*(Aqshallow <oid>\*(Aq
    برای هر یک از این اشیاء مطلع کند تا سرور از محدودیت‌های تاریخچه کلاینت آگاه باشد\&.
    این کار به این دلیل است که سرور بداند کلاینت ممکن است تمام اشیاء قابل دسترس
    از چنین کامیت‌هایی را نداشته باشد\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
deepen <depth>
    درخواست می‌کند که fetch/clone کم‌عمق بوده و دارای عمق کامیت <depth>
    نسبت به سمت راه دور باشد\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
deepen\-relative
    درخواست می‌کند که معنای دستور "deepen" تغییر کند تا نشان دهد که عمق درخواستی
    به جای این که نسبت به کامیت‌های درخواستی باشد، نسبت به مرز کم‌عمق فعلی کلاینت است\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
deepen\-since <timestamp>
    درخواست می‌کند که clone/fetch کم‌عمق به جای عمق، در یک زمان مشخص بریده شود\&.
    از نظر داخلی معادل اجرای "git rev\-list \-\-max\-age=<timestamp>" است\&.
    نمی‌توان از آن همراه با "deepen" استفاده کرد\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
deepen\-not <rev>
    درخواست می‌کند که clone/fetch کم‌عمق به جای عمق، در یک بازنگری مشخص‌شده
    توسط \*(Aq<rev>\*(Aq بریده شود\&. از نظر داخلی معادل اجرای "git rev\-list \-\-not <rev>"
    است\&. نمی‌توان از آن همراه با "deepen" استفاده کرد، اما با "deepen\-since"
    قابل استفاده است\&.
.fi
.if n \{\
.RE
.\}
.sp
اگر ویژگی \fIfilter\fR اعلان شده باشد، آرگومان زیر را می‌توان در درخواست کلاینت گنجاند:
.sp
.if n \{\
.RS 4
.\}
.nf
filter <filter\-spec>
    درخواست می‌کند که اشیاء مختلف از packfile با استفاده از یکی از چندین تکنیک
    فیلترسازی حذف شوند\&. این موارد برای استفاده در عملیات کلون جزئی (partial clone)
    و واکشی جزئی (partial fetch) در نظر گرفته شده‌اند\&. برای مقادیر ممکن "filter\-spec"
    به `rev\-list` مراجعه کنید\&. هنگام برقراری ارتباط با فرآیندهای دیگر، فرستنده‌ها
    باید (SHOULD) اعداد صحیح مقیاس‌بندی‌شده (مانند "1k") را به شکل کاملاً گسترش‌یافته
    (مانند "1024") تبدیل کنند تا به قابلیت همکاری با دریافت‌کننده‌های قدیمی‌تر که
    ممکن است پسوندهای مقیاس‌بندی جدید را درک نکنند، کمک نمایند\&. با این حال،
    دریافت‌کننده‌ها باید (SHOULD) پسوندهای زیر را بپذیرند: \*(Aqk\*(Aq، \*(Aqm\*(Aq و \*(Aqg\*(Aq به ترتیب
    برای ۱۰۲۴، ۱۰۴۸۵۷۶ و ۱۰۷۳۷۴۱۸۲۴\&.
.fi
.if n \{\
.RE
.\}
.sp
اگر ویژگی \fIref\-in\-want\fR اعلان شده باشد، آرگومان زیر را می‌توان در درخواست کلاینت گنجاند و همچنین بخش \fIwanted\-refs\fR ممکن است به پاسخ سرور اضافه شود، همان‌طور که در زیر توضیح داده شده است\&.
.sp
.if n \{\
.RS 4
.\}
.nf
want\-ref <ref>
    به سرور نشان می‌دهد که کلاینت می‌خواهد یک ارجاع خاص را بازیابی کند، که در آن
    <ref> نام کامل یک ارجاع روی سرور است\&. ارسال want\-ref برای یک ارجاع یکسان
    بیش از یک بار، یک خطای پروتکل است\&.
.fi
.if n \{\
.RE
.\}
.sp
اگر ویژگی \fIsideband\-all\fR اعلان شده باشد، آرگومان زیر را می‌توان در درخواست کلاینت گنجاند:
.sp
.if n \{\
.RS 4
.\}
.nf
sideband\-all
    به سرور دستور می‌دهد که کل پاسخ را مالتی‌پلکس (تسهیم) شده ارسال کند، نه فقط
    بخش packfile را\&. تمام خطوط غیر flush و غیر delim در PKT\-LINE در پاسخ
    (نه فقط در بخش packfile) با یک بایت شروع می‌شوند که باند جانبی آن را مشخص می‌کند
    (۱، ۲ یا ۳)، و سرور ممکن است "0005\e2" (یک PKT\-LINE از باند جانبی ۲ بدون بار داده)
    را به عنوان یک بسته زنده نگه‌داشتن (keepalive) ارسال کند\&.
.fi
.if n \{\
.RE
.\}
.sp
اگر ویژگی \fIpackfile\-uris\fR اعلان شده باشد، آرگومان زیر را می‌توان در درخواست کلاینت گنجاند و همچنین بخش \fIpackfile\-uris\fR ممکن است به پاسخ سرور اضافه شود، همان‌طور که در زیر توضیح داده شده است\&. توجه داشته باشید که حداکثر یک خط \fBpackfile\-uris\fR می‌تواند به سرور ارسال شود\&.
.sp
.if n \{\
.RS 4
.\}
.nf
packfile\-uris <comma\-separated\-list\-of\-protocols>
    به سرور نشان می‌دهد که کلاینت مایل است به جای اشیاء موجود در packfile
    ارسالی، URIهای مربوط به هر یک از پروتکل‌های ارائه‌شده را دریافت کند\&. قبل از
    انجام بررسی اتصال‌پذیری، کلاینت باید از تمام URIهای داده‌شده دانلود کند\&.
    در حال حاضر، پروتکل‌های پشتیبانی‌شده "http" و "https" هستند\&.
.fi
.if n \{\
.RE
.\}
.sp
اگر ویژگی \fIwait\-for\-done\fR اعلان شده باشد، آرگومان زیر را می‌توان در درخواست کلاینت گنجاند\&.
.sp
.if n \{\
.RS 4
.\}
.nf
wait\-for\-done
    به سرور نشان می‌دهد که هرگز نباید "ready" را ارسال کند، بلکه باید قبل از ارسال
    packfile منتظر بماند تا کلاینت "done" بگوید\&.
.fi
.if n \{\
.RE
.\}
.sp
پاسخ \fBfetch\fR به تعدادی بخش تقسیم می‌شود که با بسته‌های جداکننده (0001) از هم جدا شده‌اند و هر بخش با سرآیند بخش خود آغاز می‌شود\&. اکثر بخش‌ها فقط زمانی ارسال می‌شوند که packfile ارسال شود\&.
.sp
.if n \{\
.RS 4
.\}
.nf
output = acknowledgements flush\-pkt |
         [acknowledgments delim\-pkt] [shallow\-info delim\-pkt]
         [wanted\-refs delim\-pkt] [packfile\-uris delim\-pkt]
         packfile flush\-pkt
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
acknowledgments = PKT\-LINE("acknowledgments" LF)
                  (nak | *ack)
                  (ready)
ready = PKT\-LINE("ready" LF)
nak = PKT\-LINE("NAK" LF)
ack = PKT\-LINE("ACK" SP obj\-id LF)
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
shallow\-info = PKT\-LINE("shallow\-info" LF)
               *PKT\-LINE((shallow | unshallow) LF)
shallow = "shallow" SP obj\-id
unshallow = "unshallow" SP obj\-id
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
wanted\-refs = PKT\-LINE("wanted\-refs" LF)
              *PKT\-LINE(wanted\-ref LF)
wanted\-ref = obj\-id SP refname
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
packfile\-uris = PKT\-LINE("packfile\-uris" LF) *packfile\-uri
packfile\-uri = PKT\-LINE(40*(HEXDIGIT) SP *%x20\-ff LF)
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
packfile = PKT\-LINE("packfile" LF)
           *PKT\-LINE(%x01\-03 *%x00\-ff)
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
بخش acknowledgments
    * اگر کلاینت با ارسال یک خط "done" مشخص کند که مذاکراتش به پایان رسیده است
      (و در نتیجه از سرور می‌خواهد که یک packfile ارسال کند)، بخش acknowledgments
      حتماً باید (MUST) از پاسخ سرور حذف شود\&.
.fi
.if n \{\
.RE
.\}
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
همیشه با سرآیند بخش "acknowledgments" شروع می‌شود
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر هیچ‌یک از شناسه‌های شیء ارسال‌شده در خطوط have مشترک نبودند، سرور با "NAK" پاسخ خواهد داد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
سرور برای تمام شناسه‌های شیء ارسال‌شده در خطوط have که مشترک هستند، با "ACK obj\-id" پاسخ خواهد داد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
یک پاسخ نمی‌تواند هم شامل خطوط "ACK" و هم یک خط "NAK" باشد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
سرور با یک خط "ready" پاسخ خواهد داد که نشان می‌دهد سرور یک پایه مشترک قابل قبول پیدا کرده و آماده ساخت و ارسال یک packfile است (که در بخش packfile همان پاسخ قرار خواهد داشت)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر سرور یک نقطه برش مناسب پیدا کرده باشد و تصمیم گرفته باشد خط "ready" ارسال کند، می‌تواند (به عنوان یک بهینه‌سازی) از ارسال هرگونه خط "ACK" که قرار بود در طول پاسخ خود ارسال کند، صرف‌نظر نماید\&. دلیل این امر آن است که سرور از قبل اشیایی را که قصد دارد به کلاینت ارسال کند تعیین کرده است و نیازی به مذاکره بیشتر نیست\&.
.sp
.if n \{\
.RS 4
.\}
.nf
بخش shallow\-info
    * اگر کلاینت یک fetch/clone کم‌عمق درخواست کرده باشد، یک کلاینت کم‌عمق
      درخواست fetch کند، یا سرور کم‌عمق باشد، پاسخ سرور ممکن است شامل یک
      بخش shallow\-info باشد\&. بخش shallow\-info در صورتی گنجانده خواهد شد که
      (به دلیل یکی از شرایط فوق) سرور نیاز داشته باشد کلاینت را از هرگونه مرز کم‌عمق
      یا تنظیمات مرزهای کم‌عمق فعلی کلاینت مطلع سازد\&.
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
همیشه با سرآیند بخش "shallow\-info" شروع می‌شود
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اگر یک عمق مثبت درخواست شود، سرور مجموعه‌ای از کامیت‌ها را که عمیق‌تر از عمق مورد نظر نیستند محاسبه می‌کند\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
سرور برای هر کامیتی که والدین آن در packfile بعدی ارسال نخواهند شد، یک خط "shallow obj\-id" ارسال می‌کند\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
سرور برای هر کامیتی که کلاینت نشان داده کم‌عمق است، اما در نتیجه fetch دیگر کم‌عمق نیست (به دلیل ارسال والدین آن در packfile بعدی)، یک خط "unshallow obj\-id" ارسال می‌کند\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
سرور نباید (MUST NOT) برای مواردی که کلاینت به عنوان بخشی از درخواست خود آن‌ها را کم‌عمق اعلام نکرده است، هیچ خط "unshallow" ارسال کند\&.
.sp
.if n \{\
.RS 4
.\}
.nf
بخش wanted\-refs
    * این بخش فقط در صورتی گنجانده می‌شود که کلاینت ارجاعی را با استفاده از یک خط
      \*(Aqwant\-ref\*(Aq درخواست کرده باشد و بخش packfile نیز در پاسخ گنجانده شده باشد\&.
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
همیشه با سرآیند بخش "wanted\-refs" شروع می‌شود\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
سرور برای هر ارجاعی که با استفاده از خطوط
\fIwant\-ref\fR
درخواست شده است، یک فهرست ارجاع ("<oid> <refname>") ارسال می‌کند\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
سرور نباید (MUST NOT) هیچ ارجاعی را که با استفاده از خطوط
\fIwant\-ref\fR
درخواست نشده است ارسال کند\&.
.sp
.if n \{\
.RS 4
.\}
.nf
بخش packfile\-uris
    * این بخش فقط در صورتی گنجانده می‌شود که کلاینت \*(Aqpackfile\-uris\*(Aq ارسال کرده
      باشد و سرور حداقل یک URI از این دست برای ارسال داشته باشد\&.
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
همیشه با سرآیند بخش "packfile\-uris" شروع می‌شود\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
به ازای هر URI که سرور ارسال می‌کند، یک هش از محتویات بسته (همان‌طور که توسط git index\-pack خروجی داده می‌شود) به همراه URI ارسال می‌نماید\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
هش‌ها ۴۰ نویسه هگزادسیمال طول دارند\&. هنگامی که Git به یک الگوریتم هش جدید ارتقا می‌یابد، ممکن است این بخش نیاز به به‌روزرسانی داشته باشد\&. (باید با هر آنچه که index\-pack بعد از "pack\et" یا "keep\et" خروجی می‌دهد مطابقت داشته باشد)\&.
.sp
.if n \{\
.RS 4
.\}
.nf
بخش packfile
    * این بخش فقط در صورتی گنجانده می‌شود که کلاینت خطوط \*(Aqwant\*(Aq را در درخواست
      خود ارسال کرده باشد و یا با ارسال \*(Aqdone\*(Aq درخواست کرده باشد که مذاکره
      بیشتری انجام نشود، یا اینکه سرور به این نتیجه رسیده باشد که نقطه برش کافی برای
      تولید یک packfile را پیدا کرده است\&.
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
همیشه با سرآیند بخش "packfile" شروع می‌شود
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
انتقال packfile بلافاصله پس از سرآیند بخش آغاز می‌شود
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
انتقال داده‌های packfile همیشه تسهیم‌شده (multiplexed) است و از همان مفاهیم قابلیت
\fIside\-band\-64k\fR
از نسخه ۱ پروتکل استفاده می‌کند\&. این بدان معنی است که هر بسته در طول جریان داده‌های packfile، از یک طول ۴ بایتی ابتدایی pkt\-line (معمول در قالب pkt\-line)، به دنبال یک کد جریان ۱ بایتی، و سپس داده‌های واقعی تشکیل شده است\&.
.sp
.if n \{\
.RS 4
.\}
.nf
کد جریان می‌تواند یکی از موارد زیر باشد:
      1 \- داده‌های بسته (pack data)
      2 \- پیام‌های پیشرفت (progress messages)
      3 \- پیام خطای مهلک درست قبل از لغو جریان (fatal error message)
.fi
.if n \{\
.RE
.\}
.RE
.SS "server\-option"
.sp
در صورت اعلان شدن، نشان می‌دهد که هر تعداد از گزینه‌های خاص سرور را می‌توان در یک درخواست گنجاند\&. این کار با ارسال هر گزینه به عنوان یک خط قابلیت "server\-option=<option>" در بخش capability\-list یک درخواست انجام می‌شود\&.
.sp
گزینه‌های ارائه‌شده نباید شامل نویسه‌های NUL یا LF باشند\&.
.SS "object\-format"
.sp
سرور می‌تواند قابلیت \fBobject\-format\fR را با یک مقدار \fBX\fR (به صورت \fBobject\-format=X\fR) اعلان کند تا به کلاینت اطلاع دهد که سرور قادر به پردازش اشیاء با استفاده از الگوریتم هش X است\&. در صورت عدم تعیین، فرض می‌شود که سرور فقط SHA\-1 را پشتیبانی می‌کند\&. اگر کلاینت مایل به استفاده از یک الگوریتم هش غیر از SHA\-1 باشد، باید رشته object\-format خود را مشخص کند\&.
.SS "session\-id=<session\-id>"
.sp
سرور ممکن است یک شناسه نشست (session ID) را اعلان کند که می‌تواند برای شناسایی این فرآیند در چندین درخواست استفاده شود\&. کلاینت نیز می‌تواند شناسه نشست خود را به سرور اعلان کند\&.
.sp
شناسه‌های نشست باید برای یک فرآیند معین یکتا باشند\&. آن‌ها باید در یک packet\-line جا شوند و نباید شامل نویسه‌های غیرقابل چاپ یا فاصله باشند\&. پیاده‌سازی فعلی از شناسه‌های نشست trace2 استفاده می‌کند (برای جزئیات به \m[blue]\fBapi\-trace2\fR\m[]\&\s-2\u[1]\d\s+2 مراجعه کنید)، اما ممکن است این موضوع تغییر کند و کاربرانِ شناسه نشست نباید به این واقعیت متکی باشند\&.
.SS "object\-info"
.sp
\fBobject\-info\fR دستوری برای بازیابی اطلاعات مربوط به یک یا چند شیء است\&. هدف اصلی آن این است که به کلاینت اجازه دهد بدون نیاز به واکشی کامل اشیاء، بر اساس این اطلاعات تصمیم‌گیری کند\&. اندازه شیء تنها اطلاعاتی است که در حال حاضر پشتیبانی می‌شود\&.
.sp
یک درخواست \fBobject\-info\fR آرگومان‌های زیر را می‌پذیرد:
.sp
.if n \{\
.RS 4
.\}
.nf
size
درخواست می‌کند که اطلاعات اندازه برای هر شناسه شیء فهرست‌شده برگردانده شود\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
oid <oid>
شیئی را به سرور نشان می‌دهد که کلاینت می‌خواهد برای آن اطلاعات دریافت کند\&.
.fi
.if n \{\
.RE
.\}
.sp
پاسخ \fBobject\-info\fR فهرستی از شناسه‌های شیء درخواستی و اطلاعات درخواستی مرتبط با آن‌ها است که هر کدام با یک فاصله جدا شده‌اند\&.
.sp
.if n \{\
.RS 4
.\}
.nf
output = info flush\-pkt
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
info = PKT\-LINE(attrs) LF)
        *PKT\-LINE(obj\-info LF)
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
attrs = attr | attrs SP attrs
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
attr = "size"
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
obj\-info = obj\-id SP obj\-size
.fi
.if n \{\
.RE
.\}
.SS "bundle\-uri"
.sp
اگر قابلیت \fIbundle\-uri\fR اعلان شود، سرور از دستور \(oqbundle\-uri\(cq پشتیبانی می‌کند\&.
.sp
این قابلیت در حال حاضر بدون مقدار اعلان می‌شود (یعنی نه به صورت "bundle\-uri=somevalue")، ممکن است در آینده مقداری برای پشتیبانی از الحاقات در سطح دستور اضافه شود\&. کلاینت‌ها حتماً باید (MUST) هرگونه مقدار قابلیت ناشناخته را نادیده بگیرند و با گفتگوی \*(Aqbundle\-uri` که پشتیبانی می‌کنند ادامه دهند\&.
.sp
دستور \fIbundle\-uri\fR به این منظور در نظر گرفته شده است که قبل از \fBfetch\fR صادر شود تا URIهای فایل‌های bundle (به \fBgit-bundle\fR(1) مراجعه کنید) را برای "تغذیه اولیه" (seed) و آگاه‌سازی دستور \fBfetch\fR بعدی دریافت نماید\&.
.sp
کلاینت می‌تواند (CAN) دستور \fBbundle\-uri\fR را قبل یا بعد از هر دستور معتبر دیگری صادر کند\&. برای مفید بودن برای کلاینت‌ها، انتظار می‌رود که بعد از \fBls\-refs\fR و قبل از \fBfetch\fR صادر شود، اما می‌تواند (CAN) در هر زمانی در طول گفتگو صادر گردد\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBبررسی bundle-uri\fR
.RS 4
.sp
هدف از این ویژگی بهینه‌سازی مصرف منابع سرور در حالت متداول است، با تبدیل حالت متداولِ واکشی یک PACK بسیار بزرگ در حین اجرای \fBgit-clone\fR(1) به یک واکشی افزایشی (incremental fetch) کوچک‌تر\&.
.sp
همچنین به سرورها امکان می‌دهد تا در ترکیب با یک \fBuploadpack\&.packObjectsHook\fR به حافظه نهان (کَش) بهتری دست یابند (به \fBgit-config\fR(1) مراجعه کنید)\&.
.sp
با تبدیل کلون‌ها یا واکشی‌های جدید به یک مذاکره قابل پیش‌بینی‌تر و متداول‌تر در برابر رأس‌های (tips) فایل(های) bundle.* که اخیراً تولید شده‌اند\&. سرورها حتی ممکن است با ورود pushهای جدید، نتایج چنین مذاکراتی را برای \fBuploadpack\&.packObjectsHook\fR از پیش تولید کنند\&.
.sp
یکی از راه‌هایی که سرورها می‌توانند از این بسته‌ها بهره ببرند این است که سرور پیش‌بینی می‌کند که کلون‌های تازه یک bundle شناخته‌شده را دانلود کرده و سپس با استفاده از نوک ارجاعات (ref tips) یافت‌شده در آن بسته (یا بسته‌ها)، به وضعیت فعلی مخزن برسند\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBپروتکل برای bundle-uri\fR
.RS 4
.sp
درخواست \fBbundle\-uri\fR هیچ آرگومانی دریافت نمی‌کند، و همان‌طور که در بالا ذکر شد در حال حاضر مقدار قابلیتی را اعلان نمی‌کند\&. هر دوی این‌ها ممکن است در آینده اضافه شوند\&.
.sp
هنگامی که کلاینت یک درخواست \fBcommand=bundle\-uri\fR صادر می‌کند، پاسخ فهرستی از جفت‌های کلید-مقدار است که به صورت خطوط بسته با مقدار \fI<key>\fR\fB=\fR\fI<value>\fR ارائه می‌شوند\&. هر \fI<key>\fR باید به عنوان یک کلید پیکربندی از فضای نام \fBbundle\&.*\fR تفسیر شود تا فهرستی از بسته‌ها را بسازد\&. این کلیدها توسط زیربخش \fBbundle\&.\fR\fI<id>\fR\&. گروه‌بندی می‌شوند، که در آن هر کلید مربوط به یک \fI<id>\fR مشخص، ویژگی‌هایی را به بسته تعریف‌شده توسط آن \fI<id>\fR اختصاص می‌دهد\&. برای جزئیات خاص این کلیدها و نحوه تفسیر مقادیر آن‌ها توسط کلاینت گیت به \fBgit-config\fR(1) مراجعه کنید\&.
.sp
کلاینت‌ها حتماً باید (MUST) خط را مطابق با قالب بالا تجزیه کنند، خطوطی که با این قالب مطابقت ندارند باید (SHOULD) کنار گذاشته شوند\&. در چنین حالتی ممکن است (MAY) به کاربر هشدار داده شود\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBانتظارات کلاینت و سرور در bundle-uri\fR
.RS 4
.PP
محتوای URI
.RS 4
محتوای موجود در URIهای اعلان‌شده حتماً باید (MUST) یکی از دو نوع زیر باشد\&.
.sp
URI اعلان‌شده ممکن است حاوی یک فایل bundle باشد که دستور
\fBgit\fR
\fBbundle\fR
\fBverify\fR
آن را می‌پذیرد\&. به این معنی که آن‌ها حتماً باید (MUST) شامل یک یا چند نوک ارجاع برای استفاده کلاینت باشند، حتماً باید (MUST) پیش‌نیازها را (در صورت وجود) با پیشوندهای استاندارد "-" مشخص کنند، و در صورت لزوم باید (MUST) "object\-format" خود را نشان دهند\&.
.sp
همچنین URI اعلان‌شده ممکن است حاوی یک فایل متنی ساده باشد که دستور
\fBgit\fR
\fBconfig\fR
\fBlist\fR
آن را می‌پذیرد (همراه با گزینه
\fB\-\-file\fR)\&.
جفت‌های کلید-مقدار در این لیست در فضای نام
\fBbundle\&.*\fR
قرار دارند (به
\fBgit-config\fR(1)
مراجعه کنید)\&.
.RE
.PP
بازیابی خطای کلاینت در bundle\-uri
.RS 4
یک کلاینت بیش از هر چیز باید در مواجهه با خطاها رفتار تخریب برازنده (gracefully degrade) داشته باشد، چه این خطا به دلیل داده‌های بد/ناقص در URI(های) بسته باشد، چه به این دلیل باشد که آن کلاینت برای مثال قادر به درک و تجزیه کامل سرآیندهای بسته و روابط پیش‌نیاز آن‌ها نیست، یا هر چیز دیگر\&.
.sp
مدیران سرور باید با اطمینان خاطر "bundle\-uri" را فعال کنند و نگران نباشند که به عنوان مثال اگر CDN آن‌ها از کار بیفتد، عملیات کلون یا واکشی با شکست قطعی روبرو شود\&. حتی اگر بسته(های) سرور ناقص باشند یا به نحوی اشکال داشته باشند، کلاینت همچنان باید به یک مخزن کارآمد دست یابد، دقیقاً همان‌طور که اگر تصمیم می‌گرفت از این الحاقیه پروتکل استفاده نکند\&.
.sp
تمام بحث‌های بعدی درباره تعامل کلاینت و سرور حتماً باید (MUST) این موضوع را در نظر داشته باشند\&.
.RE
.PP
سرور به کلاینت در bundle\-uri
.RS 4
ترتیب بازگرداندن URIهای بسته اهمیتی ندارد\&. کلاینت‌ها حتماً باید (MUST) سرآیندهای آن‌ها را برای کشف OIDهای موجود و پیش‌نیازها تجزیه کنند\&. یک کلاینت حتماً باید (MUST) محتوای خود بسته(ها) و سرآیند آن‌ها را به عنوان منبع نهایی حقیقت در نظر بگیرد\&.
.sp
یک سرور حتی ممکن است (MAY) بسته(هایی) را برگرداند که هیچ ارتباط مستقیمی با مخزن در حال کلون شدن ندارند (چه به طور تصادفی یا از روی پیکربندی عمدی و "هوشمندانه")، و انتظار داشته باشد که کلاینت داده‌های مورد نظر خود را از بسته(ها) در صورت وجود استخراج کند\&.
.RE
.PP
کلاینت به سرور در bundle\-uri
.RS 4
کلاینت بهتر است (SHOULD) نوک‌های ارجاع یافت‌شده در سرآیند(های) بسته را به عنوان خطوط
\fIhave\fR
در هر درخواست بعدی
\fBfetch\fR
ارائه دهد\&. یک کلاینت همچنین می‌تواند (MAY) در صورتی که استفاده از بسته(ها) به دلایلی نامطلوب تشخیص داده شود، مثلاً اگر بسته‌ها قابل دانلود نباشند، نوک‌های یافت‌شده را نپسندد و غیره، بسته‌ها را کاملاً نادیده بگیرد\&.
.RE
.PP
هنگامی که بسته(های) اعلان‌شده نیاز به مذاکره بیشتری ندارند
.RS 4
اگر پس از اجرای
\fBbundle\-uri\fR
و
\fBls\-refs\fR
و دریافت سرآیند(های) بسته(ها)، کلاینت متوجه شود که نوک‌های ارجاع مورد نظرش را می‌توان به طور کامل از بسته(های) اعلان‌شده بازیابی کرد، کلاینت می‌تواند (MAY) اتصال خود را از سرور گیت قطع کند\&. نتایج چنین عملیات
\fIclone\fR
یا
\fIfetch\fR
نباید با وضعیتی که بدون استفاده از bundle\-uri به دست می‌آمد تفاوتی داشته باشد\&.
.RE
.PP
قطع زودهنگام اتصال کلاینت و بازیابی خطا
.RS 4
یک کلاینت می‌تواند (MAY) در حین دانلود بسته(ها) (پس از دریافت جریانی و تجزیه سرآیندهای آن‌ها) اقدام به قطع زودهنگام اتصال نماید\&. در چنین حالتی، کلاینت حتماً باید (MUST) در برابر هرگونه خطای مربوط به اتمام دانلود و اعتبارسنجی بسته(ها) به صورت برازنده بازیابی (recovery) شود\&.
.sp
به این معنی که ممکن است کلاینت نیاز به اتصال مجدد و اجرای یک دستور
\fIfetch\fR
داشته باشد، و احتمالاً به استفاده نکردن از
\fIbundle\-uri\fR
رجوع نماید\&.
.sp
این رفتار "می‌تواند (MAY)" بر اساس این فرض مشخص شده است (و نه یک "باید (SHOULD)") که سروری که URIهای بسته را اعلان می‌کند به احتمال زیاد در حال ارائه یک مخزن نسبتاً بزرگ است و به URIهایی اشاره می‌کند که شانس زیادی برای کارکرد صحیح دارند\&. کلاینت می‌تواند (MAY) مثلاً به اندازه بار داده بسته‌ها به عنوان یک روش اکتشافی نگاه کند تا ببیند آیا قطع زودهنگام اتصال ارزش دارد یا خیر، در صورتی که بازگشت به یک گفتگوی کامل "fetch" لازم باشد\&.
.RE
.PP
هنگامی که بسته(های) اعلان‌شده به مذاکره بیشتری نیاز دارند
.RS 4
یک کلاینت بهتر است (SHOULD) مذاکره یک PACK را از سرور از طریق دستور "fetch" با استفاده از نوک‌های OID یافت‌شده در بسته‌های اعلان‌شده آغاز کند، حتی اگر هنوز در حال دانلود آن بسته(ها) باشد\&.
.sp
این امر امکان قطع سریع و زودهنگام اتصال از هر گفتگوی تعاملی سرور را فراهم می‌کند\&. کلاینت کورکورانه اعتماد می‌کند که نوک‌های OID اعلان‌شده مرتبط هستند، و آن‌ها را به عنوان خطوط
\fIhave\fR
ارسال می‌کند، سپس هر نوکی را که می‌خواهد (معمولاً از اعلان "ls\-refs") از طریق خطوط
\fIwant\fR
درخواست می‌نماید\&. سپس سرور یک PACK (امیدوارم کوچک) را با تفاوت مورد انتظار بین نوک‌های حاصل از بسته(ها) و داده‌های درخواستی محاسبه خواهد کرد\&.
.sp
تنها اتصالی که کلاینت پس از آن نیاز به فعال نگه‌داشتن آن دارد، اتصال به بسته‌های ایستا است که همزمان دانلود می‌شوند؛ هنگامی که آن‌ها و PACK افزایشی بازیابی شدند، باید باز شده و اعتبارسنجی شوند\&. هرگونه خطا در این مرحله باید به صورت برازنده بازیابی شود، به موارد بالا مراجعه کنید\&.
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBویژگی‌های پروتکل bundle-uri\fR
.RS 4
.sp
کلاینت یک لیست بسته را از جفت‌های \fI<key>\fR\fB=\fR\fI<value>\fR ارائه شده توسط سرور می‌سازد\&. این جفت‌ها بخشی از فضای نام \fBbundle\&.*\fR هستند همان‌طور که در \fBgit-config\fR(1) مستند شده است\&. در این بخش، ما برخی از این کلیدها را بررسی می‌کنیم و اقداماتی را که کلاینت در پاسخ به این اطلاعات انجام می‌دهد شرح می‌دهیم\&.
.sp
به طور خاص، کلید \fBbundle\&.version\fR یک مقدار عددی صحیح را مشخص می‌کند\&. در حال حاضر تنها مقدار پذیرفته‌شده \fB1\fR است، اما اگر کلاینت مقدار غیرمنتظره‌ای را در اینجا مشاهده کند، کلاینت حتماً باید (MUST) لیست بسته را نادیده بگیرد\&.
.sp
تا زمانی که \fBbundle\&.version\fR درک شود، سایر کلیدهای ناشناخته ممکن است (MAY) توسط کلاینت نادیده گرفته شوند\&. سرور سازگاری با کلاینت‌های قدیمی‌تر را تضمین می‌کند، اگرچه کلاینت‌های جدیدتر ممکن است بهتر بتوانند از کلیدهای اضافی برای به حداقل رساندن دانلودها استفاده کنند\&.
.sp
هرگونه افزودن ناسازگار با گذشته به جفت‌های کلید-مقدار در سطح هر URI با مقدار یا مقادیر جدید \fBbundle\&.version\fR در خود اعلان قابلیت \fIbundle\-uri\fR و/یا با آرگومان‌های درخواست جدید \fBbundle\-uri\fR در آینده محافظت خواهد شد\&.
.sp
برخی از نمونه جفت‌های کلید-مقدار که در حال حاضر پیاده‌سازی نشده‌اند اما می‌توانند در آینده پیاده‌سازی شوند عبارتند از:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
افزودن یک "hash=<val>" یا "size=<bytes>" برای اعلان هش یا اندازه مورد انتظار فایل بسته\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اعلان اینکه یک یا چند فایل بسته یکسان هستند (مثلاً برای اینکه کلاینت‌ها به صورت round\-robin یا روش دیگر یکی از N فایل ممکن را انتخاب کنند)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
یک میانبر "oid=<OID>" و میانبر "prerequisite=<OID>"\&. برای بیان حالت متداول بسته‌ای با یک نوک و بدون پیش‌نیاز، یا یک نوک و یک پیش‌نیاز\&.
.sp
این امر امکان بهینه‌سازی حالت معمول سرورهایی را فراهم می‌کند که مایلند یک "بسته بزرگ" حاوی تنها شاخه "main" خود و/یا به‌روزرسانی‌های افزایشی آن را ارائه دهند\&.
.sp
کلاینتی که چنین پاسخی دریافت می‌کند می‌تواند (MAY) فرض کند که می‌تواند از بازیابی سرآیند از یک بسته در URI مشخص‌شده صرف‌نظر کند، و در نتیجه خود و سرور(ها) را از درخواست(های) مورد نیاز برای بررسی سرآیندهای آن بسته یا بسته‌ها بی‌نیاز کند\&.
.RE
.RE
.SS "promisor\-remote=<pr\-info>"
.sp
سرور ممکن است برخی از ریموت‌های promisor را که استفاده می‌کند یا از آن‌ها آگاه است به کلاینتی که ممکن است بخواهد از آن‌ها به عنوان ریموت‌های promisor خود به جای این مخزن استفاده کند، اعلان نماید\&. در این حالت <pr\-info> باید به این شکل باشد:
.sp
.if n \{\
.RS 4
.\}
.nf
pr\-info = pr\-fields | pr\-info ";" pr\-fields
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
pr\-fields = pr\-field | pr\-fields "," pr\-field
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
pr\-field = field\-name "=" field\-value
.fi
.if n \{\
.RE
.\}
.sp
که در آن تمام \fBfield\-name\fR و \fBfield\-value\fR در یک \fBpr\-fields\fR داده‌شده، نام‌ها و مقادیر فیلدهای مربوط به یک ریموت promisor منفرد هستند\&. یک \fBfield\-name\fR داده‌شده نباید بیش از یک بار در یک \fBpr\-fields\fR مشخص ظاهر شود (MUST NOT)\&.
.sp
سرور حتماً باید (MUST) حداقل نام‌های فیلد "name" و "url" را همراه با مقادیر فیلد مربوطه، که نام یک ریموت معتبر و URL آن هستند، در هر \fBpr\-fields\fR اعلان کند\&. فیلدهای "name" و "url" حتماً باید (MUST) ابتدا در هر pr\-fields و به همین ترتیب ظاهر شوند\&.
.sp
پس از این فیلدهای اجباری، سرور می‌تواند (MAY) فیلدهای اختیاری زیر را به هر ترتیبی اعلان کند:
.PP
\fBpartialCloneFilter\fR
.RS 4
مشخصات فیلتر برای ریموت\&. این مقدار متناظر با تنظیمات پیکربندی "remote\&.<name>\&.partialCloneFilter" است\&. کلاینت‌ها می‌توانند از این فیلد برای تعیین اینکه آیا استراتژی فیلترسازی ریموت با نیازهای آن‌ها سازگار است یا خیر (مثلاً بررسی اینکه آیا هر دو از "blob:none" استفاده می‌کنند) استفاده کنند\&. علاوه بر این، آن‌ها می‌توانند از طریق گزینه
\fB\-\-filter=auto\fR
در
\fBgit-clone\fR(1)
از آن استفاده کنند\&. با این گزینه، مشخصات فیلتر کلون به صورت خودکار با ترکیب مشخصات فیلتر ریموت‌های promisor که کلاینت می‌پذیرد، محاسبه می‌شود\&.
.RE
.PP
\fBtoken\fR
.RS 4
یک توکن احراز هویت که کلاینت‌ها می‌توانند هنگام اتصال به ریموت از آن استفاده کنند\&. این مقدار متناظر با تنظیم پیکربندی "remote\&.<name>\&.token" است\&.
.RE
.sp
در حال حاضر هیچ فیلد دیگری توسط پروتکل تعریف نشده است\&. نام فیلدها به حروف کوچک و بزرگ حساس هستند و حتماً باید (MUST) دقیقاً همان‌طور که در بالا مشخص شده است منتقل شوند\&. کلاینت‌ها حتماً باید (MUST) فیلدهایی را که تشخیص نمی‌دهند نادیده بگیرند تا امکان الحاقات آینده پروتکل فراهم شود\&.
.sp
کلاینت می‌تواند از اطلاعات منتقل‌شده از طریق این فیلدها استفاده کند تا تصمیم بگیرد که آیا ریموت promisor اعلان‌شده را می‌پذیرد یا خیر\&. همچنین، کلاینت را می‌توان به گونه‌ای پیکربندی کرد که مقادیر این فیلدها را ذخیره کند یا از آن‌ها برای پیکربندی خودکار مخزن استفاده نماید (به "promisor\&.storeFields" در \fBgit-config\fR(1) و \fB\-\-filter=auto\fR در \fBgit-clone\fR(1) مراجعه کنید)\&.
.sp
مقادیر فیلد حتماً باید به صورت urlencoded باشند (MUST)\&.
.sp
اگر کلاینت تصمیم بگیرد از یک یا چند ریموت promisor که سرور اعلان کرده است استفاده کند، می‌تواند با "promisor\-remote=<pr\-names>" پاسخ دهد که در آن <pr\-names> باید به شکل زیر باشد:
.sp
.if n \{\
.RS 4
.\}
.nf
pr\-names = pr\-name | pr\-names ";" pr\-name
.fi
.if n \{\
.RE
.\}
.sp
که در آن \fBpr\-name\fR نام urlencoded یک ریموت promisor است که سرور اعلان کرده و کلاینت آن را پذیرفته است\&.
.sp
ریموت‌های promisor که کلاینت پذیرفته است، هنگام تلاش کلاینت برای واکشی اشیاء گمشده، قبل از سایر ریموت‌های promisor پیکربندی‌شده امتحان خواهند شد\&.
.sp
توجه داشته باشید که در سراسر این سند، در صورتی که نویسه‌های \fI;\fR و \fI,\fR در \fBpr\-name\fR یا \fBfield\-value\fR ظاهر شوند، حتماً باید کدگذاری شوند (MUST)\&.
.sp
اگر سرور هیچ ریموت promisor را که بتواند برای کلاینت مناسب باشد نداند، یا ترجیح دهد کلاینت از هیچ ریموت promisor که سرور استفاده می‌کند یا از آن آگاه است استفاده نکند، اصلاً نباید قابلیت "promisor\-remote" را اعلان کند\&.
.sp
در این حالت، یا اگر کلاینت تمایلی به استفاده از هیچ‌یک از ریموت‌های promisor اعلان‌شده توسط سرور نداشته باشد، کلاینت نباید قابلیت "promisor\-remote" را در پاسخ خود اعلان نماید\&.
.sp
در سمت سرور، گزینه‌های پیکربندی "promisor\&.advertise" و "promisor\&.sendFields" می‌توانند برای کنترل آنچه اعلان می‌کند استفاده شوند\&. در سمت کلاینت، گزینه پیکربندی "promisor\&.acceptFromServer" می‌تواند برای کنترل آنچه می‌پذیرد، و گزینه "promisor\&.storeFields" برای کنترل آنچه ذخیره می‌کند، استفاده شود\&. برای اطلاعات بیشتر به مستندات این گزینه‌های پیکربندی در \fBgit-config\fR(1) مراجعه کنید\&.
.sp
توجه داشته باشید که در آینده بسیار مطلوب خواهد بود اگر قابلیت پروتکل "promisor\-remote" بتواند توسط سرور هنگام پاسخ به \fBgit\fR \fBfetch\fR یا \fBgit\fR \fBclone\fR استفاده شود تا ریموت‌هایی با اتصال بهتر را که کلاینت می‌تواند به عنوان ریموت‌های promisor به جای این مخزن استفاده کند اعلان نماید، به طوری که کلاینت بتواند به صورت تنبل (lazily) اشیاء را از این ریموت‌های با اتصال بهتر واکشی کند\&. این امر مستلزم آن است که سرور در پاسخ خود از ارسال اشیاء موجود در ریموت‌های دارای اتصال بهتر که کلاینت پذیرفته است، صرف‌نظر نماید\&. با این حال این مورد هنوز پیاده‌سازی نشده است\&. بنابراین در حال حاضر این قابلیت "promisor\-remote" تنها زمانی مفید است که سرور برخی از ریموت‌های promisor را که از قبل برای قرض گرفتن اشیاء استفاده می‌کند، اعلان نماید\&.
.SH "گیت (GIT)"
.sp
بخشی از مجموعه \fBgit\fR(1)
.SH "یادداشت‌ها (NOTES)"
.IP " 1." 4
api-trace2
.RS 4
\%file:///usr/share/doc/git-doc/technical/api-trace2.html
.RE