українська мова ▾ Topics ▾ Latest version ▾ git-format-patch last updated in 2.51.1

НАЗВА

git-format-patch - Підготовка патчів для надсилання електронною поштою

СИНОПСИС

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]
		   [--[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> ]

ОПИС

Підготуйте кожен коміт, що не об’єднується, з його "патчем" в одному "повідомленні" на коміт, відформатованому як поштова скринька UNIX. Вивід цієї команди зручний для надсилання електронною поштою або для використання з git am.

«Повідомлення», згенероване командою, складається з трьох частин:

  • Короткий заголовок метаданих, що починається з From <commit> з фіксованою міткою дати Mon Sep 17 00:00:00 2001, щоб допомогти програмам, таким як "file(1)", розпізнати, що файл є виходом цієї команди, поля, що записують ідентифікацію автора, дату авторства та назву зміни (взято з першого абзацу повідомлення журналу комітів).

  • Другий та наступні абзаци повідомлення журналу комітів.

  • «Патч», який є виводом «diff -p --stat» (див. git-diff[1]) між комітом та його батьківським комітом.

Повідомлення журналу та патч розділені лінією з трьома пунктирними лініями.

Існує два способи вказати, з якими коммітами працювати.

  1. Один коміт <since> вказує, що будуть виведені коміти, що ведуть до кінчика поточної гілки, яких немає в історії, що призводить до <since>.

  2. Загальний вираз <revision-range> (див. розділ "ВИЗНАЧЕННЯ РЕВІЗІЙ" у gitrevisions[7]) означає коміти у вказаному діапазоні.

Перше правило має пріоритет у випадку одного <commit>. Щоб застосувати друге правило, тобто відформатувати все з початку історії до <commit>, використовуйте опцію --root: git format-patch --root <commit>. Якщо ви хочете відформатувати лише сам <commit>, ви можете зробити це за допомогою git format-patch -1 <commit>.

За замовчуванням кожен вихідний файл нумерується послідовно, починаючи з 1, і як ім’я файлу використовується перший рядок повідомлення коміту (змінений для безпеки шляхів). З опцією --numbered-files імена вихідних файлів будуть лише числами, без додавання першого рядка коміту. Імена вихідних файлів виводяться на стандартний вивід, якщо не вказано опцію --stdout.

Якщо вказано -o, вихідні файли створюються в <dir>. В іншому випадку вони створюються в поточному робочому каталозі. Шлях за замовчуванням можна встановити за допомогою параметра конфігурації format.outputDirectory. Параметр -o має пріоритет над format.outputDirectory. Щоб зберігати патчі в поточному робочому каталозі, навіть якщо format.outputDirectory вказує на інше місце, використовуйте -o. Будуть створені всі компоненти каталогу.

За замовчуванням тема окремого патча — "[PATCH]", після чого йде об’єднання рядків від повідомлення коміту до першого порожнього рядка (див. розділ ОБГОВОРЕННЯ у git-commit[1]).

Коли виводиться кілька патчів, префікс теми буде "[PATCH n/m]". Щоб примусово додати 1/1 для одного патча, використовуйте -n. Щоб виключити номери патчів з теми, використовуйте -N.

Якщо вказано --thread, git-format-patch генеруватиме заголовки In-Reply-To та References, щоб другий та наступні листи з патчем відображалися як відповіді на перший лист; це також генеруватиме заголовок Message-ID для посилання.

ОПЦІЇ

-p
--no-stat

Генерувати прості патчі без будь-яких diffstats.

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

Генерувати різниці з <n> рядками контексту замість звичайних трьох.

--output=<файл>

Вивід у певний файл замість stdout.

--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)

Виберіть алгоритм порівняння. Варіанти такі:

default
myers

Базовий алгоритм жадібного різниці. Наразі це алгоритм за замовчуванням.

minimal

Витратьте додатковий час, щоб переконатися, що отримано найменшу можливу різницю.

patience

Використовуйте алгоритм "різниця терпіння" під час створення патчів.

histogram

Цей алгоритм розширює алгоритм терпіння для «підтримки рідко зустрічаються поширених елементів».

Наприклад, якщо ви налаштували змінну diff.algorithm на значення, відмінне від значення за замовчуванням, і хочете використовувати значення за замовчуванням, тоді вам потрібно використовувати опцію --diff-algorithm=default.

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

Згенерувати diffstat. За замовчуванням для частини імені файлу буде використано стільки місця, скільки потрібно, а решта – для частини графу. Максимальна ширина за замовчуванням дорівнює ширині терміналу або 80 стовпців, якщо не підключено до терміналу, і може бути перевизначена за допомогою <width>. Ширину частини імені файлу можна обмежити, вказавши іншу ширину <name-width> після коми або встановивши diff.statNameWidth=<name-width>. Ширину частини графу можна обмежити за допомогою --stat-graph-width=<graph-width> або встановивши diff.statGraphWidth=<graph-width>. Використання --stat або --stat-graph-width впливає на всі команди, що генерують графік статистики, тоді як встановлення diff.statNameWidth або diff.statGraphWidth не впливає на git format-patch. Надаючи третій параметр <count>, ви можете обмежити вивід першими рядками <count>, а потім ..., якщо їх більше.

Ці параметри також можна встановити окремо за допомогою --stat-width=<ширина>, --stat-name-width=<ширина-назви> та --stat-count=<кількість>.

--compact-summary

Вивести стислий виклад розширеної інформації заголовка, такої як створення або видалення файлів ("new" або "gone", необов’язково +l, якщо це символічне посилання) та зміни режиму (+x або -x для додавання або видалення виконуваного біта відповідно) у diffstat. Інформація розміщується між частиною імені файлу та частиною графу. Має на увазі --stat.

--numstat

Подібно до --stat, але показує кількість доданих та видалених рядків у десятковому форматі та шлях без скорочень, що робить його зручнішим для машинного обчислення. Для бінарних файлів виводить два - замість 0 0.

--shortstat

Виведіть лише останній рядок формату --stat, що містить загальну кількість змінених файлів, а також кількість доданих та видалених рядків.

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

Виведіть розподіл відносної кількості змін для кожного підкаталогу. Поведінку --dirstat можна налаштувати, передавши їй список параметрів, розділених комами. Значення за замовчуванням контролюються змінною конфігурації diff.dirstat (див. git-config[1]). Доступні такі параметри:

changes

Обчисліть числа dirstat, підрахувавши рядки, які були видалені з джерела або додані до місця призначення. Це ігнорує кількість чистих переміщень коду у файлі. Іншими словами, перестановка рядків у файлі враховується не так часто, як інші зміни. Це поведінка за замовчуванням, коли не задано параметр.

lines

Обчисліть числа dirstat, виконавши звичайний рядковий аналіз різниці та підсумувавши кількість видалених/доданих рядків. (Для бінарних файлів рахуйте 64-байтові фрагменти, оскільки бінарні файли не мають природного поняття рядків). Це дорожча поведінка --dirstat, ніж поведінка changes, але вона враховує переставлені рядки у файлі так само, як і інші зміни. Отриманий результат узгоджується з тим, що ви отримуєте від інших опцій --*stat.

files

Обчисліть числа dirstat, підрахувавши кількість змінених файлів. Кожен змінений файл враховується однаково в аналізі dirstat. Це найдешевша з точки зору обчислень поведінка --dirstat, оскільки взагалі не потрібно переглядати вміст файлу.

cumulative

Також підраховуйте зміни в дочірньому каталозі для батьківського каталогу. Зверніть увагу, що під час використання cumulative сума відсотків, що повідомляються, може перевищувати 100%. Поведінку за замовчуванням (некумулятивну) можна вказати за допомогою параметра noncumulative.

<limit>

Цілочисельний параметр визначає граничний відсоток (за замовчуванням 3%). Каталоги, що вносять менше змін, ніж цей відсоток, не відображаються у виводі.

Приклад: Наступний код підраховуватиме змінені файли, ігноруючи каталоги з менш ніж 10% від загальної кількості змінених файлів, та накопичуючи кількість дочірніх каталогів у батьківських каталогах: --dirstat=files,10,cumulative.

--cumulative

Синонім до --dirstat=cumulative.

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

Синонім до --dirstat=files,<param>,....

--summary

Вивести стислий виклад розширеної інформації заголовка, такої як створення, перейменування та зміни режиму.

--no-renames

Вимкніть виявлення перейменування, навіть якщо у файлі конфігурації це встановлено за замовчуванням.

--[no-]rename-empty

Чи використовувати порожні блоби як джерело перейменування.

--full-index

Замість перших кількох символів, відображати повні назви об’єктів blob до та після зображення в рядку "index" під час створення виводу у форматі патча.

--binary

Окрім --full-index, виведіть бінарний diff, який можна застосувати за допомогою git-apply.

--abbrev[=<n>]

Замість відображення повної 40-байтової шістнадцяткової назви об’єкта у вивідному форматі diff-raw та рядках заголовків diff-tree, відображайте найкоротший префікс довжиною щонайменше <n> шістнадцяткових цифр, який унікально посилається на об’єкт. У вивідному форматі diff-patch --full-index має вищий пріоритет, тобто якщо вказано --full-index, будуть відображатися повні назви блобів незалежно від --abbrev. Кількість цифр, відмінну від стандартної, можна вказати за допомогою --abbrev=<n>.

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

Розбийте повні зміни перезапису на пари видалення та створення. Це служить двом цілям:

Це впливає на те, як зміна, яка зводиться до повного перезапису файлу, представляється не як серія видалення та вставки, змішаних разом з дуже невеликою кількістю рядків, які випадково відповідають контексту, а як одне видалення всього старого, за яким слідує одна вставка всього нового, і число <m> контролює цей аспект опції -B (за замовчуванням 60%). -B/70% вказує, що менше 30% оригіналу має залишитися в результаті, щоб Git вважав це повним перезаписом (тобто інакше отриманий патч буде серією видалення та вставки, змішаних разом з рядками контексту).

При використанні з -M, повністю перезаписаний файл також вважається джерелом перейменування (зазвичай -M розглядає лише файл, який зник, як джерело перейменування), а число <n> контролює цей аспект опції -B (за замовчуванням 50%). -B20% вказує, що зміна з додаванням та видаленням порівняно з 20% або більше від розміру файлу може бути розглянута як можливе джерело перейменування на інший файл.

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

Виявлення перейменувань. Якщо вказано <n>, це поріг подібності індекс (тобто кількість додавань/видалень порівняно з розмір файлу). Наприклад, -M90% означає, що Git повинен враховувати видалити/додати пару для перейменування, якщо більше 90% файлу не змінилося. Без знака % число слід читати як дріб з десятковою комою перед ним. Тобто, -M5 стає 0,5, і таким чином те саме, що й -M50%. Аналогічно, -M05 це те саме, що й -M5%. Щоб обмежити виявлення точними перейменуваннями, використовуйте -M100%. Індекс подібності за замовчуванням становить 50%.

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

Виявляти копії, а також перейменування. Див. також --find-copies-harder. Якщо вказано <n>, це має те саме значення, що й -M<n>.

--find-copies-harder

З міркувань продуктивності, за замовчуванням, опція -C знаходить копії, лише якщо оригінальний файл копії був змінений у тому ж наборі змін. Цей прапорець змушує команду перевіряти незмінені файли як кандидатів на джерело копії. Це дуже ресурсоємна операція для великих проектів, тому використовуйте її з обережністю. Використання кількох опцій -C має той самий ефект.

-D
--irreversible-delete

Пропускайте преобраз для видалення, тобто виводьте лише заголовок, але не різницю між преобразом та /dev/null. Отриманий патч не призначений для застосування за допомогою patch або git apply; це виключно для тих, хто хоче зосередитися на перегляді тексту після зміни. Крім того, у виводі явно бракує інформації для застосування такого патчу у зворотному порядку, навіть вручну, звідси й назва опції.

При використанні разом з -B, також пропускається прообраз у частині видалення пари видалення/створення.

-l<num>

Опції -M та -C передбачають деякі попередні кроки, які можуть дешево виявляти підмножини перейменувань/копій, а потім виконується вичерпна резервна частина, яка порівнює всі непарні місця призначення, що залишилися, з усіма відповідними джерелами. (Для перейменувань релевантними є лише непарні джерела, що залишилися; для копій релевантними є всі оригінальні джерела.) Для N джерел та місць призначення ця вичерпна перевірка дорівнює O(N^2). Ця опція запобігає запуску вичерпної частини виявлення перейменування/копіювання, якщо кількість вихідних/цільових файлів перевищує задану кількість. За замовчуванням використовується значення diff.renameLimit. Зверніть увагу, що значення 0 вважається необмеженим.

-O<файл замовлень>

Контролюйте порядок, у якому файли відображаються у виводі. Це перевизначає змінну конфігурації diff.orderFile (див. git-config[1]). Щоб скасувати diff.orderFile, використовуйте -O/dev/null.

Порядок виведення визначається порядком шаблонів глобусів у <orderfile>. Усі файли зі шляхами, що відповідають першому шаблону, виводяться першими, усі файли зі шляхами, що відповідають другому шаблону (але не першому), виводяться наступними і так далі. Усі файли зі шляхами, що не відповідають жодному шаблону, виводяться останніми, ніби в кінці файлу є неявний шаблон збігу всіх. Якщо кілька шляхів мають однаковий ранг (вони відповідають одному шаблону, але не попереднім шаблонам), їхній порядок виведення відносно один одного є звичайним порядком.

<файл_замовлення> аналізується наступним чином:

  • Пусті рядки ігноруються, тому їх можна використовувати як роздільники для зручності читання.

  • Рядки, що починаються з хеш-символа ("#"), ігноруються, тому їх можна використовувати для коментарів. Додайте зворотну скісну риску ("\") на початок шаблону, якщо він починається з хеш-символа.

  • Кожен інший рядок містить один візерунок.

Шаблони мають той самий синтаксис і семантику, що й шаблони, що використовуються для fnmatch(3) без прапорця FNM_PATHNAME, за винятком того, що ім’я шляху також відповідає шаблону, якщо видалення будь-якої кількості компонентів кінцевого імені шляху відповідає шаблону. Наприклад, шаблон "foo*bar" відповідає "fooasdfbar" та "foo/bar/baz/asdf", але не "foobarx".

--skip-to=<файл>
--rotate-to=<файл>

Видалити файли перед іменем <файл> з виводу (тобто «перейти до») або перемістити їх у кінець виводу (тобто «повернути до»). Ці опції були винайдені в основному для використання команди git difftool і можуть бути не дуже корисними в іншому випадку.

--relative[=<шлях>]
--no-relative

Під час запуску з підкаталогу проєкту можна наказати програмі виключати зміни за межами каталогу та показувати шляхи відносно нього за допомогою цієї опції. Коли ви не перебуваєте в підкаталозі (наприклад, у чистому репозиторії), ви можете вказати, відносно якого підкаталогу робити вивід, вказавши <шлях> як аргумент. --no-relative можна використовувати для скасування як опції конфігурації diff.relative, так і попереднього --relative.

-a
--text

Обробляти всі файли як текст.

--ignore-cr-at-eol

Ігноруйте повернення каретки в кінці рядка під час порівняння.

--ignore-space-at-eol

Ігнорувати зміни пробілів в кінці циклу.

-b
--ignore-space-change

Ігнорувати зміни кількості пробілів. Це ігнорує пробіли в кінці рядка та вважає всі інші послідовності з одного або кількох пробілних символів еквівалентними.

-w
--ignore-all-space

Ігнорувати пробіли під час порівняння рядків. Це ігнорує відмінності, навіть якщо один рядок має пробіли, а інший їх не має.

--ignore-blank-lines

Ігнорувати зміни, рядки яких порожні.

-I<регулярний вираз>
--ignore-matching-lines=<регулярний вираз>

Ігнорувати зміни, усі рядки яких відповідають <regex>. Цей параметр можна вказувати більше одного разу.

--inter-hunk-context=<number>

Показує контекст між різницями (diff hanks), до вказаної <кількості> рядків, таким чином об’єднуючи ханки, що знаходяться близько один до одного. За замовчуванням використовується значення diff.interHunkContext або 0, якщо параметр конфігурації не встановлено.

-W
--function-context

Показувати всю функцію як рядки контексту для кожної зміни. Назви функцій визначаються так само, як git diff визначає заголовки патч-хунк (див. "Визначення власного заголовка hunk" у gitattributes[5]).

--ext-diff

Дозволити виконання зовнішнього допоміжного засобу різниці. Якщо ви встановлюєте зовнішній драйвер різниці за допомогою gitattributes[5], вам потрібно використовувати цю опцію з git-log[1] та подібними.

--no-ext-diff

Заборонити зовнішні драйвери різниці.

--textconv
--no-textconv

Дозволити (або заборонити) використання зовнішніх фільтрів перетворення тексту під час порівняння бінарних файлів. Див. gitattributes[5] для отримання детальної інформації. Оскільки фільтри textconv зазвичай є одностороннім перетворенням, отриманий diff придатний для використання людиною, але не може бути застосований. З цієї причини фільтри textconv увімкнено за замовчуванням лише для git-diff[1] та git-log[1], але не для git-format-patch[1] або команд diff plumbing.

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

Ігнорувати зміни в підмодулях під час генерації різниці. all є значенням за замовчуванням. Використання none вважатиме підмодуль зміненим, якщо він містить невідстежувані або змінені файли, або його HEAD відрізняється від коміту, записаного в суперпроекті, і може бути використано для перевизначення будь-яких налаштувань опції ignore в git-config[1] або gitmodules[5]. Коли використовується untracked, підмодулі не вважаються брудними, якщо вони містять лише невідстежуваний контент (але вони все одно скануються на наявність зміненого контенту). Використання dirty ігнорує всі зміни в робочому дереві підмодулів, відображаються лише зміни в коммітах, що зберігаються в суперпроекті (така поведінка була до версії 1.7.0). Використання all приховує всі зміни в підмодулях.

--src-prefix=<prefix>

Показати вказане джерело <префікс> замість "a/".

--dst-prefix=<prefix>

Показувати вказаний пункт призначення <префікс> замість "b/".

--no-prefix

Не показувати жодного префікса джерела чи призначення.

--default-prefix

Використовуйте префікси джерела та призначення за замовчуванням ("a/" та "b/"). Це замінює змінні конфігурації, такі як diff.noprefix, diff.srcPrefix, diff.dstPrefix та diff.mnemonicPrefix (див. git-config[1]).

--line-prefix=<prefix>

Додайте додатковий <префікс> до кожного рядка виводу.

--ita-invisible-in-index

За замовчуванням записи, додані за допомогою git add -N, відображаються як існуючий порожній файл у git diff та як новий файл у git diff --cached. Ця опція робить запис відображатися як новий файл у git diff та як неіснуючий у git diff --cached. Цю опцію можна скасувати за допомогою --ita-visible-in-index. Обидва параметри є експериментальними та можуть бути видалені в майбутньому.

Для більш детального пояснення цих поширених опцій див. також gitdiffcore[7].

-<n>

Підготуйте патчі з найвищих <n> комітів.

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

Використовуйте <dir> для зберігання результуючих файлів замість поточного робочого каталогу.

-n
--numbered

Назвіть вивід у форматі [PATCH n/m], навіть якщо це один патч.

-N
--no-numbered

Назвіть вивід у форматі [PATCH].

--start-number <n>

Почніть нумерацію патчів з <n> замість 1.

--numbered-files

Імена вихідних файлів будуть простою числовою послідовністю без додавання першого рядка коміту за замовчуванням.

-k
--keep-subject

Не видаляйте/не додавайте [PATCH] з першого рядка повідомлення журналу комітів.

-s
--signoff

Додайте трейлер Signed-off-by до повідомлення коміту, використовуючи свій ідентифікатор комітера. Дивіться опцію підписання в git-commit[1] для отримання додаткової інформації.

--stdout

Виводити всі коміти на стандартний вивід у форматі mbox, замість створення окремого файлу для кожного з них.

--attach[=<boundary>]

Створіть багаточастинне/змішане вкладення, перша частина якого є повідомленням коміту, а сама латка — у другій частині, за допомогою Content-Disposition: attachment.

--no-attach

Вимкнути створення вкладення, замінивши налаштування конфігурації.

--inline[=<boundary>]

Створіть багаточастинний/змішаний вкладений файл, перша частина якого є повідомленням коміту, а сама латка — у другій частині, з Content-Disposition: inline.

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

Керує додаванням заголовків In-Reply-To та References, щоб другий та наступні листи відображалися як відповіді на перший. Також керує генерацією заголовка Message-ID для посилання.

Необов’язковий аргумент <style> може мати значення shallow або deep. При shallow кожен лист є відповіддю на заголовок серії, де заголовок вибирається з супровідного листа, --in-reply-to та першого листа з патчем у такому порядку. deep робить кожен лист відповіддю на попередній.

Значення за замовчуванням — --no-thread, якщо не встановлено конфігурацію format.thread. --thread без аргументу еквівалентно --thread=shallow.

Зверніть увагу, що за замовчуванням для git send-email власне обробляє електронні листи за допомогою потоків. Якщо ви хочете, щоб git format-patch виконував обробляння за допомогою потоків, вам потрібно переконатися, що обробляння за допомогою git send-email вимкнено.

--in-reply-to=<ідентифікатор повідомлення>

Зробити так, щоб перший лист (або всі листи з --no-thread) відображалися як відповідь на заданий <message-id>, що дозволяє уникнути розриву потоків для створення нової серії патчів.

--ignore-if-in-upstream

Не включайте патч, що відповідає коміту, у <until>..<since>. Це перевірить усі патчі, доступні з <since>, але не з <until>, та порівняє їх зі згенерованими патчами, а будь-який патч, що відповідає, буде ігноровано.

--always

Включити патчі для комітів, які не вносять жодних змін, що пропускаються за замовчуванням.

--cover-from-description=<mode>

Контролює, які частини супровідного листа будуть автоматично заповнені з використанням опису філії.

Якщо <mode> має значення message або default, тема супровідного листа буде заповнена текстом-заповнювачем. Основна частина супровідного листа буде заповнена описом гілки. Це режим за замовчуванням, коли не вказано жодної конфігурації чи параметра командного рядка.

Якщо <mode> має значення subject, то перший абзац опису гілки заповнить тему супровідного листа. Решта опису заповнить основну частину супровідного листа.

Якщо <mode> має значення auto, і перший абзац опису гілки перевищує 100 байт, тоді режим буде message, інакше буде використано subject.

Якщо <mode> має значення none, то і тема, і тіло супровідного листа будуть заповнені текстом-заповнювачем.

--description-file=<файл>

Використовуйте вміст <file> замість опису гілки для створення супровідного листа.

--subject-prefix=<subject-prefix>

Замість стандартного префікса [PATCH] у рядку теми листа використовуйте [<префікс-суб’єкта>]. Його можна використовувати для назви серії патчів, а також поєднувати з опцією --numbered.

Змінна конфігурації format.subjectPrefix також може бути використана для налаштування префікса теми, який застосовуватиметься до заданого репозиторію для всіх патчів. Це часто корисно в списках розсилки, які отримують патчі для кількох репозиторіїв, і може бути використано для усунення неоднозначності патчів (наприклад, зі значенням "PATCH my-project").

--filename-max-length=<n>

Замість стандартних 64 байтів, скоротіть згенеровані назви вихідних файлів приблизно до <n> байтів (занадто коротке значення буде непомітно збільшено до прийнятної довжини). За замовчуванням використовується значення змінної конфігурації format.filenameMaxLength або 64, якщо не налаштовано.

--rfc[=<rfc>]

Додає рядок <rfc> (за замовчуванням "RFC") до префікса теми. Оскільки префікс теми за замовчуванням має значення "PATCH", ви отримаєте "RFC PATCH" за замовчуванням.

RFC означає «Запит на коментарі»; використовуйте це, надсилаючи експериментальний патч для обговорення, а не для застосування. «--rfc=WIP» також може бути корисним способом вказати, що патч ще не завершено («WIP» означає «Work In Progress» – «Робота в процесі»).

Якщо спільнота приймаючого коду для певного додаткового рядка за домовленістю має розташовуватися після префікса теми, рядок <rfc> може мати префікс ("-‘"), щоб сигналізувати про те, що решту рядка <rfc> слід додавати до префікса теми, наприклад, `--rfc=-(WIP)’ призведе до "PATCH (WIP)".

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

Позначте серію як <n>-ту ітерацію теми. До імен вихідних файлів додається v<n>, а до префікса теми (за замовчуванням "PATCH", але його можна налаштувати за допомогою опції --subject-prefix) додається v<n>. Наприклад, --reroll-count=4 може створити файл v4-0001-add-makefile.patch, який містить "Тема: [PATCH v4 1/20] Додати makefile". <n> не обов’язково має бути цілим числом (наприклад, "--reroll-count=4.4" або "--reroll-count=4rev2" дозволені), але недоліком використання такого reroll-count є те, що range-diff/interdiff з попередньою версією не вказує точно, з якою версією порівнюється нова ітерація.

--to=<email>

Додайте заголовок To: до заголовків електронного листа. Це доповнення до будь-яких налаштованих заголовків і може використовуватися кілька разів. Заперечувана форма --no-to відкидає всі заголовки To:, додані до цього часу (з конфігурації або командного рядка).

--cc=<email>

Додайте заголовок Cc: до заголовків електронної пошти. Це доповнення до будь-яких налаштованих заголовків і може використовуватися кілька разів. Заперечення форми --no-cc відкидає всі заголовки Cc:, додані до цього часу (з конфігурації або командного рядка).

--from
--from=<ident>

Використовуйте ident у заголовку From: кожного електронного листа з комітом. Якщо ідентифікатор автора коміта текстово не ідентичний наданому ident, розмістіть заголовок From: у тілі повідомлення з оригінальним автором. Якщо ident не вказано, використовуйте ідентифікатор коміта.

Зверніть увагу, що ця опція корисна лише тоді, коли ви фактично надсилаєте електронні листи та хочете ідентифікувати себе як відправника, але зберегти оригінального автора (і git am правильно отримає заголовок in-body). Також зауважте, що git send-email вже обробляє це перетворення за вас, і цю опцію не слід використовувати, якщо ви передаєте результат до git send-email.

--[no-]force-in-body-from

Якщо відправника електронної пошти вказано за допомогою опції --from, за замовчуванням у верхній частині повідомлення журналу комітів додається поле "Від:" для ідентифікації справжнього автора коміта, якщо відправник відрізняється від автора. З цією опцією поле "Від:" додається, навіть якщо відправник та автор мають однакове ім’я та адресу, що може допомогти, якщо програмне забезпечення списку розсилки спотворює особу відправника. За замовчуванням використовується значення змінної конфігурації format.forceInBodyFrom.

--add-header=<header>

Додайте довільний заголовок до заголовків електронного листа. Це доповнення до будь-яких налаштованих заголовків і може використовуватися кілька разів. Наприклад, --add-header="Організація: git-foo". Заперечувана форма --no-add-header відкидає всі заголовки (To:, Cc: та власні), додані до цього моменту з конфігурації або командного рядка.

--[no-]cover-letter

Окрім патчів, згенеруйте файл супровідного листа, що містить опис гілки, короткий журнал та загальну статистику змін. Ви можете заповнити опис у файлі перед його надсиланням.

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

Кодувати заголовки електронних листів, що містять символи, відмінні від ASCII, за допомогою "Q-кодування" (описано в RFC 2047), замість дослівного виведення заголовків. За замовчуванням використовується значення змінної конфігурації format.encodeEmailHeaders.

--interdiff=<previous>

Як допоміжний засіб для рецензентів, вставте інтердиф у супровідний лист або як коментар до окремого патча серії з 1 патча, показуючи відмінності між попередньою версією серії патчів та серією, що наразі форматується. previous – це окрема ревізія з назвою кінця попередньої серії, яка має спільну основу з серією, що форматується (наприклад, git format-patch --cover-letter --interdiff=feature/v1 -3 feature/v2).

--range-diff=<previous>

Як допомога рецензентам, вставте range-diff (див. git-range-diff[1]) у супровідний лист або як коментар до окремого патча серії з 1 патча, показуючи відмінності між попередньою версією серії патчів та серією, що наразі форматується. previous може бути однією ревізією з назвою кінця попередньої серії, якщо вона має спільну основу з серією, що форматується (наприклад, git format-patch --cover-letter --range-diff=feature/v1 -3 feature/v2), або діапазоном ревізій, якщо дві версії серії не перетинаються (наприклад, git format-patch --cover-letter --range-diff=feature/v1~3..feature/v1 -3 feature/v2).

Зверніть увагу, що параметри diff, передані команді, впливають на те, як генерується основний продукт format-patch, і вони не передаються базовому механізму range-diff, який використовується для генерації матеріалу супровідного листа (це може змінитися в майбутньому).

--creation-factor=<percent>

Використовується з --range-diff, налаштовує евристику, яка зіставляє коміти між попередньою та поточною серією патчів, коригуючи коефіцієнт витрати на створення/видалення. Див. git-range-diff[1]) для деталей.

За замовчуванням використовується значення 999 (git-range-diff[1] використовує 60), оскільки варіант використання полягає в тому, щоб показати порівняння зі старішою версією тієї ж теми, і інструмент повинен знайти більше відповідностей між двома наборами патчів.

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

Додайте примітки (див. git-notes[1]) для коміту після триштрихової лінії.

Очікуваним варіантом використання цього є написання підтверджувального пояснення для коміту, який не належить до власне повідомлення журналу комітів, та включення його до надісланого патча. Хоча можна просто написати ці пояснення після виконання format-patch, але перед надсиланням, збереження їх як нотаток Git дозволяє підтримувати їх між версіями серії патчів (але дивіться обговорення параметрів конфігурації notes.rewrite у git-notes[1] для використання цього робочого процесу).

Значення за замовчуванням — --no-notes, якщо не встановлено конфігурацію format.notes.

--[no-]signature=<signature>

Додайте підпис до кожного створеного повідомлення. Згідно з RFC 3676, підпис відділяється від тіла рядком із символом --. Якщо параметр підпису пропущено, підпис за замовчуванням використовує номер версії Git.

--signature-file=<file>

Працює так само, як --signature, за винятком того, що підпис зчитується з файлу.

--suffix=.<sfx>

Замість використання .patch як суфікса для згенерованих назв файлів, використовуйте вказаний суфікс. Поширеною альтернативою є --suffix=.txt. Якщо залишити це поле порожнім, суфікс .patch буде видалено.

Зверніть увагу, що початковий символ не обов’язково має бути крапкою; наприклад, ви можете використовувати --suffix=-patch, щоб отримати 0001-description-of-my-change-patch.

-q
--quiet

Не виводьте назви згенерованих файлів у стандартний вивід.

--no-binary

Не виводити вміст змін у бінарних файлах, натомість відображати повідомлення про те, що ці файли змінилися. Патчі, згенеровані за допомогою цієї опції, не можуть бути застосовані належним чином, але вони все одно корисні для перевірки коду.

--zero-commit

Вивести хеш, що складається з нулів, у заголовку From кожного патча замість хешу коміта.

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

Запишіть інформацію про базове дерево, щоб визначити стан, до якого застосовується серія патчів. Див. розділ ІНФОРМАЦІЯ ПРО БАЗОВЕ ДЕРЕВО нижче для отримання детальної інформації. Якщо <commit> має значення "auto", базовий коміт вибирається автоматично. Опція --no-base перевизначає конфігурацію format.useAutoBase.

--root

Розглядати аргумент revision як <revision-range>, навіть якщо це лише один коміт (який зазвичай розглядається як <since>). Зверніть увагу, що кореневі коміти, що входять до зазначеного діапазону, завжди форматуються як патчі створення, незалежно від цього прапорця.

--progress

Показувати звіти про прогрес на stderr під час створення патчів.

КОНФІГУРАЦІЯ

Ви можете вказати додаткові рядки заголовка листа, які потрібно додавати до кожного повідомлення, значення за замовчуванням для префікса теми та суфікса файлу, нумерувати патчі під час виведення кількох патчів, додавати заголовки "Кому:" або "Копія:", налаштовувати вкладення, змінювати каталог виведення патчів та підписувати патчі за допомогою змінних конфігурації.

[формат]
	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
	coverFromDescription = auto

ОБГОВОРЕННЯ

Патч, створений командою «git format-patch», має формат поштової скриньки UNIX з фіксованою «магічною» міткою часу, яка вказує на те, що файл виводиться з 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 були скорочені за допомогою скрипта Python
(Див. коментар до коміту c2330e286f68f1c408b4aa6515ba49d57f05beae)

Зробіть те саме для ia64, щоб ми могли мати елегантний та акуратний вигляд
...

Зазвичай його розміщують у папці чернеток MUA, редагують для додавання своєчасних коментарів, які не повинні потрапляти до журналу змін після трьох дефісів, а потім надсилають як повідомлення, тіло якого, у нашому прикладі, починається з "файли конфігурації arch/arm були…​". З іншого боку, читачі можуть зберігати цікаві патчі у поштовій скриньці UNIX та застосовувати їх за допомогою git-am[1].

Коли патч є частиною поточного обговорення, патч, згенерований командою git format-patch, можна налаштувати, щоб скористатися перевагами функції git am --scissors. Після вашої відповіді на обговорення йде рядок, який складається виключно з "-- >8 --" (ножиці та перфорація), а потім сам патч з видаленими непотрібними полями заголовка:

...
> Отже, нам слід зробити те й те.

Мені зрозуміло. Як щодо цього патча?

-- >8 --
Тема: [IA64] Додати конфігураційні файли ia64 до дієти Уве Кляйне-Кеніга

Файли конфігурації arch/arm були скорочені за допомогою скрипта Python
...

Надсилаючи патч таким чином, найчастіше ви надсилаєте свій власний патч, тому, окрім маркера "From $SHA1 $magic_timestamp", вам слід пропустити рядки From: та Date: з файлу патча. Назва патча, ймовірно, відрізнятиметься від теми обговорення, на яке відповідає патч, тому, ймовірно, вам варто зберегти рядок Subject:, як у прикладі вище.

Перевірка на наявність пошкоджень патчів

Багато поштових програм, якщо їх неправильно налаштувати, пошкоджують пробіли. Ось два поширені типи пошкодження:

  • Порожні рядки контексту, які не містять будь-яких пробілів.

  • Непорожні рядки контексту, що мають один додатковий пробіл на початку.

Один із способів перевірити, чи правильно налаштовано ваш MUA:

  • Надішліть патч собі саме так, як і ви це зробили б, за винятком того, що рядки «Кому:» та «Копія:» не містять адреси списку та відповідальної особи.

  • Збережіть цей патч у файлі у форматі поштової скриньки UNIX. Назвіть його, скажімо, a.patch.

  • Застосуйте це:

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

Якщо він застосовується неправильно, на це може бути кілька причин.

  • Сам патч застосовується не зовсім коректно. Це погано, але це не має великого відношення до вашого MUA. У цьому випадку, можливо, варто перебазувати патч за допомогою git-rebase[1] перед його повторною генерацією.

  • Програма багаторазового використання (MUA) пошкодила ваш патч; "am" скаржився, що патч не застосовується. Перегляньте підкаталог .git/rebase-apply/ та перевірте, що містить файл "patch", і перевірте наявність згаданих вище типових шаблонів пошкодження.

  • Також перевірте файли info та final-commit. Якщо вміст final-commit не зовсім відповідає тому, що ви хотіли б бачити в повідомленні журналу комітів, дуже ймовірно, що одержувач вручну редагуватиме повідомлення журналу під час застосування вашого патчу. Такі речі, як "Привіт, це мій перший патч.\n" у електронному листі з патчем, повинні йти після тритире, яка сигналізує про кінець повідомлення коміту.

СПЕЦИФІЧНІ ПІДКАЗКИ ДЛЯ MUA

Ось кілька порад щодо успішного надсилання патчів безпосередньо за допомогою різних поштових програм.

GMail

У веб-інтерфейсі GMail немає можливості вимкнути перенесення рядків, тому будь-які надіслані вами електронні листи будуть спотворені. Однак ви можете скористатися командою "git send-email" та надсилати свої патчі через SMTP-сервер GMail або будь-яким поштовим клієнтом IMAP для підключення до сервера Google IMAP та пересилання електронних листів через нього.

Підказки щодо використання «git send-email» для надсилання патчів через SMTP-сервер GMail дивіться в розділі ПРИКЛАД у документі git-send-email[1].

Підказки щодо надсилання за допомогою інтерфейсу IMAP див. у розділі ПРИКЛАД у файлі git-imap-send[1].

Тандерберд

За замовчуванням Thunderbird як переносить електронні листи в обгортку, так і позначає їх як такі, що мають формат format=flowed, що зробить отриманий лист непридатним для використання Git.

Існує три різні підходи: використовувати доповнення, щоб вимкнути перенесення рядків, налаштувати Thunderbird так, щоб він не спотворював латки, або використовувати зовнішній редактор, щоб Thunderbird не спотворював латки.

Підхід №1 (додатковий)

Встановіть доповнення Toggle Word Wrap, доступне за адресою https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/. Воно додає пункт меню «Увімкнути перенесення слів» у меню «Параметри» редактора, який можна позначити. Тепер ви можете писати повідомлення так само, як і зазвичай (вирізати + вставити, «git format-patch» | «git imap-send» тощо), але вам доведеться вручну вставляти розриви рядків у будь-який текст, який ви вводите.

Підхід №2 (конфігурація)

Три кроки:

  1. Налаштуйте склад поштового сервера як звичайний текст: Редагувати…​ Налаштування облікового запису…​ Складання та адресація, зніміть прапорець "Створювати повідомлення у форматі HTML".

  2. Налаштуйте загальне вікно композиції так, щоб воно не переносилося.

    У Thunderbird 2: Редагувати..Налаштування..Створення, переносити текстові повідомлення на 0

    У Thunderbird 3: Редагувати…​ Налаштування…​ Додатково…​ Редактор конфігурацій. Знайдіть "mail.wrap_long_lines". Перемкніть його, щоб переконатися, що для нього встановлено значення false. Також знайдіть "mailnews.wraplength" і встановіть значення 0.

  3. Вимкніть використання format=flowed: Редагувати..Налаштування..Додатково..Редактор конфігурацій. Знайдіть "mailnews.send_plaintext_flowed". Перемкніть його, щоб переконатися, що для нього встановлено значення false.

Після цього ви зможете писати електронні листи так, як це зазвичай робите (вирізати + вставити, git format-patch | git imap-send тощо), і латки не будуть пошкоджені.

Підхід №3 (зовнішній редактор)

Потрібні такі розширення Thunderbird: AboutConfig з https://mjg.github.io/AboutConfig/ та External Editor з https://globs.org/articles.php?lng=en&pg=8

  1. Підготуйте патч у вигляді текстового файлу, використовуючи обраний вами метод.

  2. Перш ніж відкривати вікно створення повідомлення, скористайтеся меню Редагувати→Налаштування облікового запису, щоб зняти прапорець «Створювати повідомлення у форматі HTML» на панелі «Створення та адресація» облікового запису, з якого потрібно надсилати патч.

  3. У головному вікні Thunderbird, «перед» відкриттям вікна створення патчу, скористайтеся Інструменти→about:config, щоб встановити вказані значення для наступних параметрів:

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

  4. Відкрийте вікно створення листа та натисніть значок зовнішнього редактора.

  5. У вікні зовнішнього редактора зчитайте файл патча та вийдіть з редактора звичайним способом.

Примітка: можливо, можна виконати крок 2 з about:config та наступними налаштуваннями, але ніхто ще не пробував.

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

У contrib/thunderbird-patch-inline є скрипт, який допоможе вам легко додавати патчі за допомогою Thunderbird. Щоб його використовувати, виконайте наведені вище кроки, а потім використовуйте скрипт як зовнішній редактор.

KMail

Це має допомогти вам надсилати патчі безпосередньо за допомогою KMail.

  1. Підготуйте патч у вигляді текстового файлу.

  2. Натисніть на «Нова пошта».

  3. Перейдіть до розділу "Параметри" у вікні редактора тексту та переконайтеся, що параметр "Перенос слів" не встановлено.

  4. Використайте Повідомлення → Вставити файл…​ та вставте.

  5. Повернувшись у вікно створення листа: додайте до повідомлення будь-який інший текст, заповніть поля адреси та теми й натисніть «Надіслати».

ІНФОРМАЦІЯ ПРО БАЗОВЕ ДЕРЕВО

Інформаційний блок базового дерева використовується для того, щоб розробники та сторонні тестувальники могли точно знати, до якого стану застосовується серія патчів. Він складається з «базового коміту», який є добре відомим комітом, що є частиною стабільної частини історії проекту, над яким працюють усі інші, та нуля або більше «попередніх патчів», які є добре відомими патчами в процесі розробки, що ще не є частиною «базового коміту», які необхідно застосувати поверх «базового коміту» в топологічному порядку, перш ніж патчі можна буде застосувати.

«Базовий коміт» відображається як «base-commit:», а потім 40-шістнадцяткове число назви об’єкта коміту. «Передумовий патч» відображається як «prerequisite-patch-id:», а потім 40-шістнадцяткове число «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, базовий коміт автоматично обчислюватиметься як база злиття коміту tip гілки віддаленого відстеження та діапазону ревізій, зазначених у командному рядку. Для локальної гілки потрібно налаштувати її відстеження віддаленої гілки за допомогою git branch --set-upstream-to, перш ніж використовувати цю опцію.

ПРИКЛАДИ

  • Витягніть коміти між ревізіями R1 та R2 та застосуйте їх поверх поточної гілки за допомогою git am для їх вибірки:

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

  • Витягнути всі коміти, які знаходяться в поточній гілці, але не в початковій гілці:

    $ git format-patch origin

    Для кожного коміту створюється окремий файл у поточному каталозі.

  • Витягніть усі коміти, що ведуть до «origin» з моменту початку проєкту:

    $ git format-patch --root origin

  • Те саме, що й попередній:

    $ git format-patch -M -B origin

    Крім того, він виявляє та обробляє перейменування й інтелектуально завершує перезаписи, створюючи патч для перейменування. Патч для перейменування зменшує обсяг виведеного тексту та загалом полегшує його перегляд. Зверніть увагу, що програми-"патчі", які не підтримують Git, не розуміють патчі для перейменування, тому використовуйте їх лише тоді, коли знаєте, що одержувач використовує Git для застосування вашого патча.

  • Витягніть три найвищі коміти з поточної гілки та відформатуйте їх як патчі для надсилання електронною поштою:

    $ git format-patch -3

ЗАСТЕРЕЖЕННЯ

Зверніть увагу, що format-patch пропустить коміти злиття з виводу, навіть якщо вони є частиною запитуваного діапазону. Простий "патч" не містить достатньо інформації для того, щоб приймаюча сторона могла відтворити той самий коміт злиття.

ДИВ. ТАКОЖ

git-am[1], git-send-email[1]

GIT

Частина набору git[1]