نام (NAME)

git-format-patch - آماده‌سازی وصله‌ها برای ارسال با ایمیل

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

git format-patch [-k] [(-o|--output-directory) <dir> | --stdout]
                   [--no-thread | --thread[=<style>]]
                   [(--attach|--inline)[=<boundary>] | --no-attach]
                   [-s | --signoff]
                   [--signature=<signature> | --no-signature]
                   [--signature-file=<file>]
                   [-n | --numbered | -N | --no-numbered]
                   [--start-number <n>] [--numbered-files]
                   [--in-reply-to=<message-id>] [--suffix=.<sfx>]
                   [--ignore-if-in-upstream] [--always]
                   [--cover-from-description=<mode>]
                   [--rfc[=<rfc>]] [--subject-prefix=<subject-prefix>]
                   [(--reroll-count|-v) <n>]
                   [--to=<email>] [--cc=<email>]
                   [--[no-]cover-letter] [--quiet]
                   [--commit-list-format=<format-spec>]
                   [--[no-]encode-email-headers]
                   [--no-notes | --notes[=<ref>]]
                   [--interdiff=<previous>]
                   [--range-diff=<previous> [--creation-factor=<percent>]]
                   [--filename-max-length=<n>]
                   [--progress]
                   [<common-diff-options>]
                   [ <since> | <revision-range> ]

توضیحات (DESCRIPTION)

هر کامیت غیرادغام را به همراه «وصله» (patch) آن در قالب یک «پیام» در ازای هر کامیت آماده می‌کند که قالبی شبیه به صندوق پستی یونیکس (UNIX mailbox) دارد. خروجی این دستور برای ارسال با ایمیل یا استفاده با git am بسیار مناسب است.

یک «پیام» ایجادشده توسط این دستور از سه بخش تشکیل می‌شود:

پیام لاگ و وصله با خطی شامل سه خط تیره (---) از یکدیگر جدا می‌شوند.

دو روش برای تعیین اینکه دستور روی کدام کامیت‌ها کار کند وجود دارد.

در صورت وجود یک <commit> منفرد، قاعده اول اولویت دارد. برای اعمال قاعده دوم، یعنی قالب‌بندی همه‌چیز از ابتدای تاریخچه تا <commit>، از گزینه --root استفاده کنید: git format-patch --root <commit>. اگر می‌خواهید فقط خود <commit> را قالب‌بندی کنید، می‌توانید این کار را با git format-patch -1 <commit> انجام دهید.

به طور پیش‌فرض، هر فایل خروجی از ۱ به صورت متوالی شماره‌گذاری می‌شود و از خط اول پیام کامیت (که برای ایمنی نام مسیر پردازش شده) به عنوان نام فایل استفاده می‌کند. با گزینه --numbered-files، نام فایل‌های خروجی تنها عدد خواهند بود، بدون اینکه خط اول پیام کامیت به آن اضافه شود. نام فایل‌های خروجی در خروجی استاندارد چاپ می‌شود، مگر اینکه گزینه --stdout مشخص شده باشد.

اگر -o مشخص شده باشد، فایل‌های خروجی در <dir> ایجاد می‌شوند. در غیر این صورت در دایرکتوری کاری فعلی ایجاد خواهند شد. مسیر پیش‌فرض را می‌توان با گزینه پیکربندی format.outputDirectory تنظیم کرد. گزینه -o بر format.outputDirectory اولویت دارد. برای ذخیره وصله‌ها در دایرکتوری کاری فعلی حتی زمانی که format.outputDirectory به جای دیگری اشاره دارد، از -o . استفاده کنید. تمام بخش‌های دایرکتوری ساخته خواهند شد.

به طور پیش‌فرض، موضوع (subject) یک وصله تکی عبارت است از "[PATCH] " که پس از آن خطوط پیام کامیت تا اولین خط خالی قرار می‌گیرند (بخش بحث در git-commit(1) را ببینید).

هنگامی که چندین وصله در خروجی تولید می‌شوند، پیشوند موضوع در عوض "[PATCH n/m] " خواهد بود. برای اجبار به افزودن 1/1 برای یک تک‌وصله، از -n استفاده کنید. برای حذف شماره‌های وصله از موضوع، از -N استفاده نمایید.

در صورت دادن --thread، دستور git-format-patch هدرهای In-Reply-To و References را تولید می‌کند تا ایمیل‌های وصله دوم و بعدی به صورت پاسخی به اولین ایمیل نمایش داده شوند؛ این کار همچنین یک هدر Message-ID برای ارجاع ایجاد می‌کند.

گزینه‌ها (OPTIONS)

-p, --no-stat

-U<n>, --unified=<n>

--output=<file>

--output-indicator-new=<char>, --output-indicator-old=<char>, --output-indicator-context=<char>

--indent-heuristic

--no-indent-heuristic

--minimal

--patience

--histogram

--anchored=<text>

--diff-algorithm=(patience|minimal|histogram|myers)

--stat[=<width>[,<name-width>[,<count>]]]

--compact-summary

--numstat

--shortstat

-X [<param>,...], --dirstat[=<param>,...]

--cumulative

--dirstat-by-file[=<param>,...]

--summary

--no-renames

--rename-empty, --no-rename-empty

--full-index

--binary

--abbrev[=<n>]

-B[<n>][/<m>], --break-rewrites[=[<n>][/<m>]]

-M[<n>], --find-renames[=<n>]

-C[<n>], --find-copies[=<n>]

--find-copies-harder

-D, --irreversible-delete

-l<num>

-O<orderfile>

--skip-to=<file>, --rotate-to=<file>

--relative[=<path>], --no-relative

-a, --text

--ignore-cr-at-eol

--ignore-space-at-eol

-b, --ignore-space-change

-w, --ignore-all-space

--ignore-blank-lines

-I<regex>, --ignore-matching-lines=<regex>

--inter-hunk-context=<number>

-W, --function-context

--ext-diff

--no-ext-diff

--textconv, --no-textconv

--ignore-submodules[=(none|untracked|dirty|all)]

--src-prefix=<prefix>

--dst-prefix=<prefix>

--no-prefix

--default-prefix

--line-prefix=<prefix>

--ita-invisible-in-index

--max-depth=<depth>

برای توضیحات مفصل‌تر درباره این گزینه‌های مشترک، gitdiffcore(7) را نیز ببینید.

-<n>

-o <dir>, --output-directory <dir>

-n, --numbered

-N, --no-numbered

--start-number <n>

--numbered-files

-k, --keep-subject

-s, --signoff

--stdout

--attach[=<boundary>]

--no-attach

--inline[=<boundary>]

--thread[=<style>], --no-thread

--in-reply-to=<message-id>

--ignore-if-in-upstream

--always

--cover-from-description=<mode>

--description-file=<file>

--subject-prefix=<subject-prefix>

--filename-max-length=<n>

--rfc[=<rfc>]

-v <n>, --reroll-count=<n>

--to=<email>

--cc=<email>

--from, --from=<ident>

--force-in-body-from, --no-force-in-body-from

--add-header=<header>

--cover-letter, --no-cover-letter

--commit-list-format=<format-spec>

--encode-email-headers, --no-encode-email-headers

--interdiff=<previous>

--range-diff=<previous>

--creation-factor=<percent>

--notes[=<ref>], --no-notes

--signature=<signature>, --no-signature

--signature-file=<file>

--suffix=.<sfx>

-q, --quiet

--no-binary

--zero-commit

--no-base, --base[=<commit>]

--root

--progress

پیکربندی (CONFIGURATION)

شما می‌توانید خطوط هدر اضافی ایمیل برای اضافه شدن به هر پیام، مقادیر پیش‌فرض برای پیشوند موضوع و پسوند فایل، شماره‌گذاری وصله‌ها هنگام خروجی دادن بیش از یک وصله، افزودن هدرهای "To:" یا "Cc:"، پیکربندی پیوست‌ها، تغییر دایرکتوری خروجی وصله، و امضا کردن (sign off) وصله‌ها را با متغیرهای پیکربندی مشخص کنید.

[format]
        headers = "Organization: git-foo\n"
        subjectPrefix = CHANGE
        suffix = .txt
        numbered = auto
        to = <email>
        cc = <email>
        attach [ = mime-boundary-string ]
        signOff = true
        outputDirectory = <directory>
        coverLetter = auto
        commitListFormat = shortlog
        coverFromDescription = auto

بحث (DISCUSSION)

وصله تولیدشده توسط git format-patch در قالب صندوق پستی یونیکس (UNIX mailbox) است، با یک مهر زمانی ثابت و جادویی ("magic") برای نشان دادن اینکه فایل خروجی format-patch است و نه یک صندوق پستی واقعی، به این صورت:

From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
From: Tony Luck <tony.luck@intel.com>
Date: Tue, 13 Jul 2010 11:42:54 -0700
Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
 =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
arch/arm config files were slimmed down using a python script
(See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
Do the same for ia64 so we can have sleek & trim looking
...

به طور معمول این فایل در پوشه پیش‌نویس‌های (drafts) نرم‌افزار MUA قرار می‌گیرد، ویرایش می‌شود تا توضیحات به‌موقع که نباید بعد از سه خط تیره در گزارش تغییرات قرار گیرند به آن اضافه شوند، و سپس به عنوان پیامی ارسال می‌شود که بدنه آن، در مثال ما، با "arch/arm config files were..." شروع می‌شود. در سمت دریافت‌کننده، خوانندگان می‌توانند وصله‌های جالب را در یک صندوق پستی یونیکس ذخیره کرده و آن‌ها را با git-am(1) اعمال کنند.

هنگامی که یک وصله بخشی از یک بحث ادامه‌دار است، وصله تولیدشده توسط git format-patch می‌تواند طوری تنظیم شود که از ویژگی git am --scissors بهره‌مند شود. پس از پاسخ شما به بحث، خطی می‌آید که صرفاً شامل "-- >8 --" (قیچی و خط برش) است، و پس از آن وصله با حذف فیلدهای هدر غیرضروری قرار می‌گیرد:

...
> So we should do such-and-such.
Makes sense to me.  How about this patch?
-- >8 --
Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
arch/arm config files were slimmed down using a python script
...

هنگام ارسال وصله به این روش، اغلب شما در حال ارسال وصله خودتان هستید، بنابراین علاوه بر نشانگر "From $SHA1 $magic_timestamp"، باید خطوط From: و Date: را از فایل وصله حذف کنید. عنوان وصله احتمالاً با موضوع بحثی که وصله در پاسخ به آن است تفاوت دارد، بنابراین به احتمال زیاد می‌خواهید خط Subject: را مانند مثال بالا حفظ کنید.

$ git fetch <project> master:test-apply
$ git switch test-apply
$ git restore --source=HEAD --staged --worktree :/
$ git am a.patch

نکات ویژه کلاینت‌های ایمیل (MUA-SPECIFIC HINTS)

در اینجا نکاتی درباره نحوه ارسال موفقیت‌آمیز وصله‌ها به صورت درون‌متنی (inline) با استفاده از برنامه‌های مختلف ایمیل آورده شده است.

mailnews.send_plaintext_flowed  => false
mailnews.wraplength             => 0

mail.html_compose                       => false
mail.identity.default.compose_html      => false
mail.identity.id?.compose_html          => false

اطلاعات درخت پایه (BASE TREE INFORMATION)

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

کامیت پایه به صورت "base-commit: " و به دنبال آن نام شیء کامیت به صورت هگزادسیمال ۴۰ رقمی نشان داده می‌شود. یک وصله پیش‌نیاز به صورت "prerequisite-patch-id: " و به دنبال آن شناسه وصله ۴۰ رقمی نشان داده می‌شود، که می‌توان آن را با ارسال وصله به دستور git patch-id --stable به دست آورد.

تصور کنید که روی کامیت عمومی P، وصله‌های شناخته‌شده X، Y و Z را از شخص دیگری اعمال کرده‌اید، و سپس سری سه وصله‌ای خود یعنی A، B و C را ساخته‌اید؛ تاریخچه به این شکل خواهد بود:

---P---X---Y---Z---A---B---C

با git format-patch --base=P -3 C (یا گونه‌های دیگر آن، مثلاً با --cover-letter یا با استفاده از Z..C به جای -3 C برای مشخص کردن محدوده)، بلوک اطلاعات درخت پایه در انتهای اولین پیامی که دستور خروجی می‌دهد (یا اولین وصله، یا نامه پوششی) به این صورت نشان داده می‌شود:

base-commit: P
prerequisite-patch-id: X
prerequisite-patch-id: Y
prerequisite-patch-id: Z

برای توپولوژی غیرخطی، مانند

---P---X---A---M---C
    \         /
     Y---Z---B

همچنین می‌توانید از git format-patch --base=P -3 C برای تولید وصله‌های A، B و C استفاده کنید، و شناسه‌های P، X، Y و Z به انتهای اولین پیام پیوست می‌شوند.

اگر --base=auto در خط فرمان تنظیم شود، کامیت پایه به طور خودکار به عنوان پایه ادغامِ (merge base) کامیت نوک شاخه ردیابی از راه دور و محدوده بازنگری مشخص‌شده در خط فرمان محاسبه می‌شود. برای یک شاخه محلی، پیش از استفاده از این گزینه باید با git branch --set-upstream-to آن را طوری تنظیم کنید که یک شاخه از راه دور را ردیابی کند.

مثال‌ها (EXAMPLES)

$ git format-patch -k --stdout R1..R2 | git am -3 -k

$ git format-patch origin

$ git format-patch --root origin

$ git format-patch -M -B origin

$ git format-patch -3

هشدارها (CAVEATS)

توجه داشته باشید که format-patch کامیت‌های ادغام را از خروجی حذف می‌کند، حتی اگر بخشی از محدوده درخواستی باشند. یک "وصله" ساده شامل اطلاعات کافی برای سمت دریافت‌کننده جهت بازتولید همان کامیت ادغام نیست.

همچنین ببینید (SEE ALSO)

git-am(1), git-send-email(1)

گیت (GIT)

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