Русский ▾ Topics ▾ Latest version ▾ git-format-patch last updated in 2.54.0

НАЗВАНИЕ

git-format-patch - Подготовка изменений (патчей) для отправки по электронной почте

ОБЗОР

git format-patch [-k] [(-o|--output-directory) <каталог> | --stdout]
		   [--no-thread | --thread[=<стиль>]]
		   [(--attach|--inline)[=<граница>] | --no-attach]
		   [-s | --signoff]
		   [--signature=<подпись> | --no-signature]
		   [--signature-file=<файл>]
		   [-n | --numbered | -N | --no-numbered]
		   [--start-number <n>] [--numbered-files]
		   [--in-reply-to=<id-сообщения>] [--suffix=.<суффикс>]
		   [--ignore-if-in-upstream] [--always]
		   [--cover-from-description=<режим>]
		   [--rfc[=<rfc>]] [--subject-prefix=<префикс-темы>]
		   [(--reroll-count|-v) <n>]
		   [--to=<email>] [--cc=<email>]
		   [--[no-]cover-letter] [--quiet]
		   [--[no-]encode-email-headers]
		   [--no-notes | --notes[=<ссылка>]]
		   [--interdiff=<предыдущий>]
		   [--range-diff=<предыдущий> [--creation-factor=<процент>]]
		   [--filename-max-length=<n>]
		   [--progress]
		   [<общие-параметры-diff>]
		   [ <начиная-с> | <диапазон-редакций> ]

ОПИСАНИЕ

Подготавливает каждый коммит без слияния с его «изменением» (патчем) в одном «сообщении» на коммит, отформатированном так, чтобы напоминать почтовый ящик UNIX. Вывод этой команды удобен для отправки по электронной почте или для использования с git am.

«Сообщение», созданное командой, состоит из трёх частей:

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

  • Второй и последующие абзацы сообщения журнала коммита.

  • "Патч", который является выводом "diff -p --stat" (см. git-diff[1]) между коммитом и его родителем.

Сообщение журнала и патч разделены строкой с тремя дефисами.

Существует два способа указать, с какими коммитами работать.

  1. Одиночный коммит, <начиная-с>, указывает, что должны быть выведены коммиты, ведущие к верхушке текущей ветки, которых нет в истории, ведущей к <начиная-с>.

  2. Выражение <диапазон-редакций> общего вида (см. раздел "ЗАДАНИЕ РЕВИЗИЙ" в gitrevisions[7]) означает коммиты в указанном диапазоне.

В случае одиночного <коммита> первое правило имеет приоритет. Чтобы применить второе правило, т.е. отформатировать всё с начала истории до <коммита>, используйте параметр --root: git format-patch --root <коммит>. Если вы хотите отформатировать только сам <коммит>, вы можете сделать это с помощью git format-patch -1 <коммит>.

По умолчанию каждый выходной файл нумеруется последовательно, начиная с 1, и использует первую строку сообщения коммита (обработанную для безопасности имени пути) в качестве имени файла. С параметром --numbered-files имена выходных файлов будут только номерами, без добавления первой строки коммита. Имена выходных файлов выводятся в стандартный вывод, если не указан параметр --stdout.

Если указан -o, выходные файлы создаются в <каталог>. В противном случае они создаются в текущем рабочем каталоге. Путь по умолчанию можно задать с помощью переменной конфигурации 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

Генерировать обыкновенные патчи, без статистической информации diffstat.

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

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

--output=<файл>

Выводить в указанный файл вместо стандартного вывода.

--output-indicator-new=<символ>
--output-indicator-old=<символ>
--output-indicator-context=<символ>

Задаёт символ, используемый для обозначения новых, старых или контекстных строк в сгенерированном патче. Обычно это +, - и ` ` соответственно.

--indent-heuristic

Применять эвристику, которая сдвигает границы блоков списков изменений, дабы сделать патчи более удобными для чтения. Это поведение включено по умолчанию.

--no-indent-heuristic

Не применять эвристику сдвига границ блоков.

--minimal

Потратить дополнительное время, чтобы гарантировать, что будет сгенерирован минимально возможный список изменений.

--patience

Генерировать списки изменений с помощью «терпеливого» алгоритма (patience diff).

--histogram

Генерировать списки изменений с помощью «гистограммного» алгоритма (histogram diff).

--anchored=<текст>

Генерировать списки изменений с помощью алгоритма поиска различий «с якорем» (anchored diff).

Этот параметр может быть указана несколько раз.

Если строка существует как в источнике, так и в назначении, встречается только один раз и начинается с <текста>, этот алгоритм пытается не допустить, чтобы эта строка была обозначена в выводе как удаляемая или добавляемая. Для собственно поиска отличий используется «терпеливый» алгоритм.

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

Выберите алгоритм для получения списка изменений. Доступны следующие варианты:

default
myers

Базовый жадный алгоритм, используемый в стандартной утилите сравнения (diff). В настоящее время это значение по умолчанию.

minimal

Потратить дополнительное время, чтобы гарантировать, что будет сгенерирован минимально возможный список изменений.

patience

Используйте «терпеливый» алгоритм сравнения (patience diff) для генерации патчей.

histogram

Этот алгоритм расширяет «терпеливый» алгоритм так, что он «поддерживает общие элементы с низкой частотой встречаемости».

В частности, если вы настроили переменную diff.algorithm на нестандартное значение и хотите использовать стандартный алгоритм, то следует задать параметр --diff-algorithm=default.

--stat[=<ширина>[,<ширина-имени>[,<число>]]]

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

Эти параметры также могут быть установлены в индивидуальном порядке с помощью --stat-width=<ширина>, --stat-name-width=<ширина-имени> и --stat-count=<число>.

--compact-summary

Выводить в статистике diffstat краткую выжимку информации, содержащейся в расширенном заголовке, в частности, был ли файл создан или удалён («new» или «gone», и возможно с «+l», если это символическая ссылка) и был ли изменён режим доступа к нему (+x или -x для добавления или удаления исполняемого бита соответственно). Эта информация помещается между имени файла и графиком. Подразумевает --stat.

--numstat

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

--shortstat

Выводить только последнюю строку, выводимую --stat, содержащую общее количество изменённых файлов, а также количество добавленных и удалённых строк.

-X [<аргумент>,...]
--dirstat[=<аргумент>,...]

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

changes

Подсчитывать количество строк, которые были удалены или добавлены. Этот алгоритм игнорирует чистые перемещения кода внутри файла. Другими словами, строки перемещённые внутри файла без изменений не учитываются в отличии от других правок. Это поведение по умолчанию, когда аргумент не указан.

lines

Подсчитывает количество строк с использованием обычного алгоритма поиска изменений, основываясь на строках и суммируя количество удалённых/добавленных строк. (Для бинарных файлов подсчитываются 64-байтовые блоки, так как у них нет естественного понятия «строк»). Это более затратный алгоритм работы --dirstat, чем changes, но он учитывает переставленные строки внутри файла так же, как и другие изменения. Вывод с этим алгоритмом лучше согласуется с теми данными, которые вы получаете от других параметров --*stat.

files

Подсчитывает количество изменённых файлов. При анализе каждый изменённый файл учитывается в равной степени. Это наиболее экономичный алгоритм --dirstat, так как он не требует просмотра содержимого файлов.

cumulative

Для родительского каталога также учитывает изменения в дочерних подкаталогах. Обратите внимание, что при использовании cumulative сумма процентов может превышать 100%. Поведение по умолчанию (некумулятивное) можно задать с помощью аргумента noncumulative.

<предел>

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

Пример: Следующая команда будет подсчитывать какую долю составляют файлы, которые были изменены в каждом конкретном каталоге, при этом игнорируя каталоги, на которые приходится менее 10% изменённых файлов и считая изменения в дочерних каталогов, как часть изменений в родительских: --dirstat=files,10,cumulative.

--cumulative

Синоним для --dirstat=cumulative.

--dirstat-by-file[=<аргумент>,...]

Синоним для --dirstat=files,<аргумент>,....

--summary

Вывести краткую сводку из информации, содержащейся в расширенных заголовках списков изменений. В частности, информацию о создании, переименовании и изменении режима доступа к файлу.

--no-renames

Отключить обнаружение переименований, даже если в файле конфигурации оно включено по умолчанию.

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

Определяет, рассматривать ли пустые бинарные объекты, как возможные источники переименований.

--full-index

Вместо первых нескольких символов показывать полные имена blob-объектов в строке «index» при выводе патча.

--binary

Выводить список изменений в бинарных файлах, который может быть применён с помощью git-apply. Также подразумевает --full-index.

--abbrev[=<n>]

Вместо вывода полных 40-байтовых шестнадцатеричных имён объектов в списках изменений в сыром формате, а также в строках заголовков diff-tree, выводить их минимальный префикс, который имеет как минимум <n> шестнадцатеричных цифр и уникально идентифицирует объект. Однако, при выводе списка изменений в виде патча параметр --full-index имеет приоритет, т.е. если задан параметр --full-index, будут выведены полные имена блоков, независимо от того, задан ли --abbrev. Количество выводимых цифр отличное от значения по умолчанию можно задать с помощью --abbrev=<n>.

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

Разбивать изменения, которые полностью переписывают файл на пары удаления и создания. Этот параметр служит двум целям:

Влияет на то, как правка, которая по сути представляет собой полное переписывание файла, отображается в списке изменений не как серия удалений и вставок, смешанных с несколькими строками «контекста», которые оказались таковыми лишь по случайному стечению обстоятельств, а как одно единое удаление старого файла целиком, за которым следует создание нового файла. Число <m>(по умолчанию 60%) в аргументе параметра -B задаёт, какая часть файла должна быть изменена, чтобы он считался полностью переписанным. Например, -B/70% указывает, что, чтобы Git считал файл полностью переписанным, в нём должно оставаться нетронутым менее 30% исходного содержимого (т.е. в случае, если нетронутыми будут больше 30% объёма файла, полученный патч будет серией удалений и вставок, смешанных с контекстными строками, как при обычном выводе).

При использовании совместно с -M, полностью переписанный файл также рассматривается как возможный источник переименований (обычно -M рассматривает в качестве таковых только файлы, которые были удалены). Число <n>(по умолчанию 50%) в аргументе параметра -B задаёт, какая часть файла должна быть изменена, чтобы он рассматривался как возможный источник переименований. Например, при указании -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, а исключительно для тех людей, кто хочет сосредоточиться на рецензировании или просмотре различий после внесения изменений. Кроме того, с таким патчем, очевидно, не будет возможности обратить изменения, даже вручную; отсюда и название параметра: «irreversible» — необратимый.

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

-l<число>

Выполнение поиска для параметров -M и -C происходит в два этапа: сначала производится некоторый предварительные шаги, которые позволяют дёшево обнаружить лишь часть переименований/копирований, а затем следует исчерпывающая часть поиска, на которой все оставшиеся назначения для которых не было найдено пары сравниваются со всеми подходящими для них источниками. (Для переименований подходящими считаются только те источники, которым ещё не были найдены пары; для копирований — все исходные источники.) Для N возможных файлов источников и назначений эта исчерпывающая проверка имеет сложность O(N^2). Данный параметр предотвращает запуск исчерпывающей части поиск переименований/копирований, если количество файлов источников/назначений превышает указанное <число> (по умолчанию: diff.renameLimit). Обратите внимание, что значение 0 означает, что это количество файлов неограниченно.

-O<файл-порядка>

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

Порядок вывода определяется порядком glob-шаблонов в <файле-порядка>. Первыми выводятся все файлы, пути которых соответствуют первому шаблону, затем файлы, соответствующие второму шаблону (но не первому), и так далее. Все файлы, которые не соответствуют ни одному из шаблонов, выводятся в конце, как если бы в конце файла был неявно задан шаблон, который сопоставляется всем путям. Пути одного ранка (которые соответствуют какому-либо одному шаблону, но не одному из предыдущих) относительно друг друга выводятся в нормальном порядке.

Синтаксис <файла-порядка> следующий:

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

  • Строки, начинающиеся с символа решётки («#»), игнорируются, их можно использовать для комментариев. Если шаблон начинается с решётки, добавьте обратный слэш («\») перед ней.

  • Все остальные строки являются шаблонами; по одному на строку.

Синтаксис и семантика у этих шаблонов те же, что и у шаблонов, используемых для fnmatch(3) без флага FNM_PATHNAME, за исключением того, что путь к файлу также сопоставляются шаблону; при этом в качестве пути к файлу сопоставляется путь к его родительскому каталогу любого уровня. Например, шаблону «foo*bar» будет соответствовать как fooasdfbar, так и «foo/bar/baz/asdf», но не «foobarx».

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

Пропускать в выводе файлы до указанного <файла> (со --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=<регулярное-выражение>

Игнорировать изменения, в которых все строки сопоставляются <регулярному-выражению>. Этот параметр может быть указан несколько раз.

--inter-hunk-context=<число>

Выводить в качестве контекста между блоками изменений до <n> строк, тем самым объединяя близкие блоки изменений. По умолчанию равно значению переменной конфигурации diff.interHunkContext или 0, если она не установлена.

-W
--function-context

Показывать всю функцию в качестве контекста для каждого изменения. Для определения имён функций используется тот же механизм, что и для определения заголовков блоков изменений командой git diff (см. «Определение пользовательского заголовка блока» в gitattributes[5]).

--ext-diff

Разрешить выполнение вспомогательных сторонних утилит сравнения. Если вы настроили драйвер сторонней утилиты сравнения с помощью gitattributes[5], то вам нужно будет использовать этот параметр с командой git-log[1] и другими подобными.

--no-ext-diff

Запретить драйверы сторонних утилит сравнения.

--textconv
--no-textconv

Разрешить (или запретить) преобразование бинарных файлов в текст с помощью внешних фильтров при их сравнении. См. подробности в gitattributes[5]. Полученный вывод подходит для восприятия человеком, но поскольку фильтры textconv обычно представляют из себя одностороннее преобразование, полученный патч нельзя будет применить. По этой причине фильтры textconv по умолчанию включены только для git-diff[1] и git-log[1], но не для git-format-patch[1] или низкоуровневых команд сравнения.

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

Игнорировать изменения в подмодулях при создании вывода. Значением по умолчанию является all. При использовании значения none будет считаться, что подмодуль изменён, если он содержит неотслеживаемые или изменённые файлы или если его HEAD отличается от коммита, зафиксированного в надпроекте и может быть использовано для переопределения любых переменных конфигурации с ignore в git-config[1] или gitmodules[5]. При использовании untracked подмодули не считаются грязными только из-за того, что они содержат неотслеживаемые файлы (но они всё равно проверяются на наличие изменений в содержимом). При использовании dirty игнорируются все изменения в рабочих каталогах подмодулей и показываются только изменения коммитов, хранящихся в надпроекте (таким было поведение до версии 1.7.0). При использовании all все изменения в подмодулях скрываются.

--src-prefix=<префикс>

Использовать указанный <префикс> для источника вместо «a/».

--dst-prefix=<префикс>

Использовать указанный <префикс> для назначения вместо «b/».

--no-prefix

Не выводить ни префикс источника, ни назначения.

--default-prefix

Использовать стандартные префиксы источника и назначения ("a/" и "b/"). Это переопределяет такие переменные конфигурации, как format.noprefix, diff.srcPrefix, diff.dstPrefix и diff.mnemonicPrefix (см. git-config[1]).

--line-prefix=<префикс>

Добавить дополнительный <префикс> к каждой строке вывода.

--ita-invisible-in-index

По умолчанию записи, добавленные командой git add -N, отображаются в выводе git diff как существующий пустой файл, а в выводе git diff --cached` — как новый файл. Этот параметр делает так, что такие записи отображаются как новый файл в выводе git diff и отсутствовать в выводе git diff --cached. Этот параметр может быть переопределён с помощью --ita-visible-in-index. Оба эти параметра являются экспериментальными и могут быть удалены в будущем.

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

Подготовить патчи из верхних <число> коммитов.

-o <каталог>
--output-directory <каталог>

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

-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 в сообщение коммита, используя вашу личность коммитера. Для получения дополнительной информации см. опцию signoff в 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 для ссылки.

Необязательный аргумент <стиль> может быть 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=<id-сообщения>

Сделать первое письмо (или все письма с --no-thread) ответом на указанный <id-сообщения>, что позволяет не разрывать поток при отправке новой серии патчей.

--ignore-if-in-upstream

Не включать патч, соответствующий коммиту в <до>..<начиная-с>. Это проверит все патчи, достижимые из <начиная-с>, но не из <до>, и сравнит их с создаваемыми патчами; любой соответствующий патч игнорируется.

--always

Включать патчи для коммитов, которые не вносят никаких изменений (по умолчанию они опускаются).

--cover-from-description=<режим>

Управляет тем, какие части сопроводительного письма будут автоматически заполнены с использованием описания ветки.

Если <режим> — message или default, тема сопроводительного письма будет заполнена текстом-заполнителем. Тело сопроводительного письма будет заполнено описанием ветки. Это режим по умолчанию, когда не указана ни конфигурация, ни параметр командной строки.

Если <режим> — subject, первый абзац описания ветки заполнит тему сопроводительного письма. Остальная часть описания заполнит тело сопроводительного письма.

Если <режим> — auto, то если первый абзац описания ветки больше 100 байт, режим будет message, в противном случае будет использован subject.

Если <режим> — none, и тема, и тело сопроводительного письма будут заполнены текстом-заполнителем.

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

Использовать содержимое <файла> вместо описания ветки для создания сопроводительного письма.

--subject-prefix=<префикс-темы>

Вместо стандартного префикса [PATCH] в строке темы использовать [<префикс-темы>]. Это можно использовать для именования серии патчей и комбинировать с параметром --numbered.

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

--filename-max-length=<n>

Вместо стандартных 64 байт обрезать имена создаваемых выходных файлов примерно до <число> байт (слишком короткое значение будет автоматически увеличено до разумной длины). По умолчанию используется значение переменной конфигурации format.filenameMaxLength или 64, если не задано.

--rfc[=<rfc>]

Добавляет строку <rfc> (по умолчанию "RFC") в начало префикса темы. Поскольку префикс темы по умолчанию — "PATCH", по умолчанию вы получите "RFC PATCH".

RFC означает "Request For Comments" (Запрос комментариев); используйте это при отправке экспериментального патча для обсуждения, а не для применения. "--rfc=WIP" также может быть полезным способом указать, что патч ещё не завершён ("WIP" расшифровывается как "Work In Progress" — "в процессе работы").

Если в сообществе получателей принято, чтобы определённая дополнительная строка располагалась после префикса темы, строку <rfc> можно предварить дефисом ("-"), чтобы указать, что остальная часть строки <rfc> должна быть добавлена к префиксу темы, например, --rfc='-(WIP) даёт "PATCH (WIP)".

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

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

--to=<email>

Добавляет заголовок To: в заголовки письма. Это дополнение к любым настроенным заголовкам, может использоваться несколько раз. Отрицательная форма --no-to отбрасывает все заголовки To:, добавленные до этого (из конфигурации или командной строки).

--cc=<email>

Добавляет заголовок Cc: в заголовки письма. Это дополнение к любым настроенным заголовкам, может использоваться несколько раз. Отрицательная форма --no-cc отбрасывает все заголовки Cc:, добавленные до этого (из конфигурации или командной строки).

--from
--from=<ident>

Использовать идентификатор в заголовке From: каждого письма с коммитом. Если идентификатор автора коммита текстуально не совпадает с указанным идентификатором, поместить заголовок From: в тело сообщения с исходным автором. Если идентификатор не указан, использовать идентификатор коммиттера.

Обратите внимание, что этот параметр полезен только если вы действительно отправляете письма и хотите идентифицировать себя как отправителя, но сохранить исходного автора (и git am правильно распознает заголовок в теле). Также учтите, что 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-encoding" (описано в RFC 2047), вместо вывода заголовков как есть. По умолчанию используется значение переменной конфигурации format.encodeEmailHeaders.

--interdiff=<previous>

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

--range-diff=<previous>

В качестве помощи рецензенту вставляет range-diff (см. git-range-diff[1]) в сопроводительное письмо или в комментарий к единственному патчу серии из одного патча, показывая различия между предыдущей версией серии патчей и серией, которая в данный момент форматируется. предыдущая может быть одной редакцией, указывающей на верхушку предыдущей серии, если она имеет общую основу с форматируемой серией (например, 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).

Обратите внимание, что параметры сравнения, переданные команде, влияют на то, как создаётся основной продукт format-patch, и они не передаются в механизм range-diff, используемый для создания материала сопроводительного письма (это может измениться в будущем).

--creation-factor=<percent>

Используется с --range-diff, настраивает эвристику, которая сопоставляет коммиты между предыдущей и текущей сериями патчей, путём регулировки фактора корректировки стоимости создания/удаления. Подробности см. в git-range-diff[1]).

По умолчанию используется 999 (git-range-diff[1] использует 60), так как вариант использования — показать сравнение с более старой итерацией той же темы, и инструмент должен находить больше соответствий между двумя наборами патчей.

--notes[=<ссылка>]
--no-notes

Добавляет заметки (см. git-notes[1]) для коммита после строки с тремя дефисами.

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

По умолчанию используется --no-notes, если не задана конфигурация format.notes.

--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[=<коммит>]

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

--root

Обрабатывать аргумент редакции как <диапазон-редакций>, даже если это просто один коммит (который обычно обрабатывается как <начиная-с>). Обратите внимание, что корневые коммиты, включённые в указанный диапазон, всегда форматируются как патчи создания, независимо от этого флага.

--progress

Показывать отчёты о ходе выполнения в stderr по мере создания патчей.

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

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

[format]
	headers = "Organization: git-foo\n"
	subjectPrefix = CHANGE
	suffix = .txt
	numbered = auto
	to = <адрес-электронной-почты>
	cc = <адрес-электронной-почты>
	attach [ = строка-границы-mime ]
	signOff = true
	outputDirectory = <каталог>
	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 --
Subject: [IA64] Посадим файлы конфигурации ia64 на диету Уве Кляйне-Кёнига

файлы конфигурации arch/arm были уменьшены с помощью скрипта python
...

При отправке патча таким образом, чаще всего вы отправляете свой собственный патч, поэтому в дополнение к маркеру "From $SHA1 $magic_timestamp" вам следует опустить строки From: и Date: из файла патча. Заголовок патча, вероятно, будет отличаться от темы обсуждения, на которое отвечает патч, поэтому, скорее всего, вы захотите сохранить строку Subject:, как в примере выше.

Проверка на повреждение патча

Многие почтовые программы, если они настроены неправильно, повреждают пробелы. Вот два распространённых типа повреждений:

  • Пустые строки контекста, не имеющие никаких пробелов.

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

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

  • Отправьте патч себе, точно так же, как вы бы отправили, за исключением строк To: и Cc:, которые не содержат адрес списка и сопровождающего.

  • Сохраните этот патч в файл в формате почтового ящика UNIX. Назовите его, например, a.patch.

  • Примените его:

    $ git fetch <проект> 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 для подключения к серверу IMAP google и пересылать письма через него.

Советы по использованию 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-шестнадцатеричным 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, чтобы скопировать их:

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

  • Извлечь все коммиты, которые находятся в текущей ветке, но не в ветке origin:

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