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

НАЗВА

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>

Створити diffs з <n> рядками контексту. Зазвичай кількість рядків контексту дорівнює значенню diff.context або 3, якщо ця змінна конфігурації не встановлена. (Опція -U без аргументу <n> через історичну випадковість мовчки приймається як синонім опції -p).

--output=<файл>

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

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

Визначає символ, який використовуватиметься для позначення нових, старих або контекстних рядків у згенерованій латці. Зазвичай це відповідно +, - та “ ”.

--indent-heuristic

Увімкнути евристику, яка зсуває межі фрагментів diff, щоб зробити латки легшими для читання. Це стандартне значення.

--no-indent-heuristic

Вимкнути евристику відступів.

--minimal

Витрачає додатковий час, щоб переконатися, що отримано найменший можливий diff.

--patience

Створювати diff використовуючи алгоритм "patience diff".

--histogram

Створювати diff використовуючи алгоритм "histogram diff".

--anchored=<text>

Створювати diff використовуючи алгоритм "anchored diff".

Цей параметр можна вказати більше одного разу.

Якщо рядок існує як у вихідному, так і в цільовому тексті, зустрічається лише один раз і починається з <текст>, цей алгоритм намагається запобігти його появі у вигляді видалення або додавання у результаті. Внутрішньо він використовує алгоритм «patience diff».

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

Вибір алгоритму порівняння. Є наступні варіанти:

default
myers

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

minimal

Витрачає додатковий час, щоб переконатися, що отримано найменший можливий diff.

patience

При створенні латок використовується алгоритм «patience diff».

histogram

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

Наприклад, якщо ви налаштували змінну 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

Виводити у diffstat стислий звіт про інформацію розширеного заголовка, таку як створення або видалення файлів («new» або «gone», за бажанням із позначкою +l, якщо це символічне посилання), а також зміни прав доступу (+x або -x для додавання чи видалення біта виконуваності відповідно). Ця інформація розміщується між частиною з іменем файлу та частиною з графом. Передбачає використання опції --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

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

--rename-empty
--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.

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

<файл-порядку> має наступний синтаксис:

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

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

  • Кожен інший рядок містить один шаблон.

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

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

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

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

Якщо запускати з субтеки проєкту, за допомогою цього параметра можна вказати, щоб виключити зміни поза межами цієї теки та показувати шляхи відносно неї. Якщо ви не перебуваєте в субтеці (наприклад, у «голому» репозиторії), ви можете вказати, щодо якої саме субтеки має бути відносний вивід, передавши <path> як аргумент. --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=<регулярний вираз>

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

--inter-hunk-context=<number>

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

-W
--function-context

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

--ext-diff

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

--no-ext-diff

Заборонити сторонні драйвери 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>

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

--dst-prefix=<prefix>

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

--no-prefix

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

--default-prefix

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

--line-prefix=<prefix>

Додавати додатковий <prefix> до кожного рядка виводу.

--ita-invisible-in-index

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

--max-depth=<depth>

Для кожного специфікатора шляху, вказаного в командному рядку, слід просканувати не більше ніж <depth> рівнів тек. Значення -1 означає відсутність обмеження. Не можна поєднувати з символами-замінниками у специфікаторі шляху. Якщо дерево містить foo/bar/baz, у наведеному нижче списку показано результати, отримані для кожного набору опцій:

  • --max-depth=0 -- foo: foo

  • --max-depth=1 -- foo: foo/bar

  • --max-depth=1 -- foo/bar: foo/bar/baz

  • --max-depth=1 -- foo foo/bar: foo/bar/baz

  • --max-depth=2 -- foo: foo/bar/baz

Якщо специфікатор шляху не вказано, глибина вимірюється так, ніби вказано всі записи верхнього рівня. Зверніть увагу, що це відрізняється від вимірювання від кореня тим, що при --max-depth=0 все одно буде повернуто foo. Це дозволяє обмежувати глибину, запитуючи при цьому лише підмножину записів верхнього рівня.

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

Для більш детального пояснення цих поширених опцій див. також 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>]

Створення вкладення типу «multipart/mixed», перша частина якого — це повідомлення про коміт, а друга — власне латка, із заголовком Content-Disposition: attachment.

--no-attach

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

--inline[=<boundary>]

Створення вкладення типу «multipart/mixed», перша частина якого — це повідомлення про коміт, а друга — власне латка, із заголовком 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=<message-id>

Зробити так, щоб перший лист (або всі листи з --no-thread) gjrfpedfkbcm як відповідь на вказаний <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>

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

--subject-prefix=<subject-prefix>

Замість стандартного префікса [PATCH] у рядку теми листа використовувати [<subject-prefix>]. Його можна використовувати для назви серії латок, а також поєднувати з опцією --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, який містить "Subject: [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.

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

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

--add-header=<header>

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

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

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

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

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

--interdiff=<previous>

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

--range-diff=<previous>

Як допомога рецензентам, вставте range-diff (див. git-range-diff[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.

--signature=<signature>
--no-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
--base[=<commit>]

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

--root

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

--progress

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

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

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

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

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

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

Підхід №1 (доповнення)

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

Як бонусна функція, доповнення може виявляти текст латки в редакторі тексту та попереджати, коли перенесення рядків ще не вимкнено.

Для роботи доповнення потрібно внести кілька змін у розширену конфігурацію (about:config). Вони перелічені на сторінці завантаження.

Підхід №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, система автоматично обчислить базовий коміт як базу злиття для кінцевого коміту гілки, що відстежує віддалену гілку, та діапазону ревізій, зазначеного в командному рядку. Для локальної гілки перед використанням цього параметра необхідно налаштувати її на відстеження віддаленої гілки за допомогою команди git branch --set-upstream-to.

ПРИКЛАДИ

  • Отримання комітів між ревізіями R1 та R2 та застосування їх поверх поточної гілки за допомогою git am для їх вибірки (cherry-pick):

    $ 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

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

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

    $ git format-patch -3

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

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

ДИВ. ТАКОЖ

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

GIT

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