git-format-patch

Название

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]
                   [--commit-list-format=<format-spec>]
                   [--[no-]encode-email-headers]
                   [--no-notes | --notes[=<ref>]]
                   [--interdiff=<previous>]
                   [--range-diff=<previous> [--creation-factor=<percent>]]
                   [--filename-max-length=<n>]
                   [--progress]
                   [<common-diff-options>]
                   [ <since> | <revision-range> ]

Описание

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

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

Краткий заголовок метаданных, начинающийся с From <commit> с фиксированной временной меткой Mon Sep 17 00:00:00 2001, которая помогает программам, таким как «file(1)», распознать, что файл создан этой командой; далее идут поля с данными автора, датой автора и заголовком изменения (взятым из первого абзаца сообщения в журнале коммита).
Второй и последующие абзацы сообщения в журнале коммита.
«Патч» — вывод «diff -p --stat» (см. git-diff[1]) для сравнения коммита с его родителем.

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

Есть два способа указать коммиты, с которыми нужно работать.

Один коммит <since> означает, что будут выведены коммиты, ведущие к вершине текущей ветки и отсутствующие в истории, ведущей к <since>.
Общее выражение <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

Создать обычные патчи без статистики diff.

-U<n>

--unified=<n>

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

--output=<file>

Вывести данные в указанный файл вместо 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».

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

Если строка присутствует и в исходном, и в целевом файле, встречается там только один раз и начинается с <text>, этот алгоритм пытается не допустить её появления в выводе как удалённой или добавленной. Внутри он использует алгоритм «patience diff».

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

Выбрать алгоритм diff. Доступны следующие варианты:

default
myers: Базовый жадный алгоритм diff. В настоящее время используется по умолчанию.
minimal: Потратить дополнительное время, чтобы получить diff минимально возможного размера.
patience: Использовать алгоритм «patience diff» при создании патчей.
histogram: Этот алгоритм расширяет алгоритм patience, чтобы «поддерживать общие элементы с низкой частотой встречаемости».

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

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

Создать статистику diff. По умолчанию для имени файла используется столько места, сколько необходимо, а остальное отводится под график. Максимальная ширина по умолчанию равна ширине терминала или 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=<width>, --stat-name-width=<name-width> и --stat-count=<count>.

--compact-summary

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

--numstat

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

--shortstat

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

-X [<param>,...]

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

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

changes: Вычислять значения dirstat, подсчитывая строки, удалённые из исходного файла или добавленные в целевой. При этом не учитывается объём перемещений кода внутри файла. Иными словами, перестановка строк в файле учитывается меньше, чем другие изменения. Это поведение используется по умолчанию, если параметр не задан.
lines: Вычислять значения dirstat с помощью обычного построчного анализа diff и суммирования числа удалённых и добавленных строк. (Для двоичных файлов вместо этого подсчитываются блоки по 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

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

--full-index

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

--binary

В дополнение к --full-index вывести двоичный diff, который можно применить с помощью git-apply.

--abbrev[=<n>]

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

-B[<n>][/<m>]

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

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

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

При использовании вместе с -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

Не включать исходное содержимое удалённых файлов: выводить только заголовок, но не diff между исходным содержимым и /dev/null. Полученный патч не предназначен для применения с помощью patch или git apply; этот параметр предназначен только для тех, кто хочет сосредоточиться на проверке текста после изменения. Кроме того, в выводе заведомо недостаточно информации, чтобы применить такой патч в обратном направлении, даже вручную, отсюда и название параметра.

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

-l<num>

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

-O<orderfile>

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

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

Файл <orderfile> разбирается следующим образом:

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

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

--skip-to=<file>

--rotate-to=<file>

Исключить из вывода файлы, расположенные перед указанным <file> (то есть skip to), или переместить их в конец вывода (то есть rotate to). Эти параметры были созданы главным образом для команды git difftool и в других случаях могут быть не очень полезны.

--relative[=<path>]

--no-relative

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

--ignore-matching-lines=<regex>

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

--inter-hunk-context=<number>

Показывать контекст между фрагментами diff, не превышая указанное <number> строк; благодаря этому близко расположенные фрагменты объединяются. По умолчанию используется 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.

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

Игнорировать изменения подмодулей при создании diff. По умолчанию используется 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>

Для каждого pathspec, заданного в командной строке, спускаться не более чем на <depth> уровней каталогов. Значение -1 означает отсутствие ограничений. Нельзя сочетать с подстановочными знаками в pathspec. Для дерева, содержащего 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

Если pathspec не задан, глубина измеряется так, как если бы были указаны все элементы верхнего уровня. Обратите внимание: это отличается от измерения глубины от корня тем, что --max-depth=0 всё равно вернёт foo. Это позволяет ограничить глубину, запрашивая при этом подмножество элементов верхнего уровня.

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

Более подробное объяснение этих общих параметров см. также в 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 в сообщение коммита, используя ваши данные коммитера. Дополнительные сведения см. в описании параметра 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 для ссылки.

Необязательный аргумент <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) ответом на указанное <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>

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

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

--filename-max-length=<n>

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

--rfc[=<rfc>]

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

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

Если согласно правилам принимающего сообщества дополнительная строка должна after префиксу темы, строку <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] Add makefile». Значение <n> не обязано быть целым числом (например, допускаются «--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>

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

Обратите внимание: этот параметр полезен, только если вы действительно отправляете письма и хотите указать себя как отправителя, сохранив при этом исходного автора (и 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

В дополнение к патчам создать файл сопроводительного письма, содержащий описание ветки, список коммитов и общую статистику diff. Перед отправкой можно добавить описание в этот файл.

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

Задать формат списка коммитов серии патчей. Допустимые значения format-spec: shortlog, modern или строка формата с префиксом log:. Например: log: %s (%an). modern — то же, что и log:%w(72)[%(count)/%(total)] %s. Префикс log: можно опустить, если строка формата содержит % (предполагается, что он является частью %<placeholder>). По умолчанию используется переменная конфигурации format.commitListFormat, если она задана, или shortlog. Указание этого параметра в командной строке подразумевает использование --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>]

Записать сведения о базовом дереве, чтобы указать состояние, к которому применяется серия патчей. Подробности см. ниже в разделе BASE TREE INFORMATION. Если <commit> равен «auto», базовый коммит выбирается автоматически. Параметр --no-base переопределяет конфигурацию format.useAutoBase.

--root

Рассматривать аргумент ревизии как <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
        commitListFormat = shortlog
        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 config files were slimmed down using a python script
(See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)

Do the same for ia64 so we can have sleek & trim looking
...

Обычно его помещают в папку черновиков почтового клиента, редактируют, добавляя актуальные комментарии, которые не должны попасть в журнал изменений после трёх дефисов, а затем отправляют как сообщение, тело которого в нашем примере начинается со слов "arch/arm config files were…". На принимающей стороне читатели могут сохранить интересные патчи в почтовый ящик UNIX и применить их с помощью git-am[1].

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

...
> So we should do such-and-such.

Makes sense to me.  How about this patch?

-- >8 --
Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet

arch/arm config files were slimmed down using a python script
...

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

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

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

Пустые строки контекста, в которых отсутствуют пробелы any.
Непустые строки контекста с лишним пробелом в начале.

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

Отправьте патч себе точно так же, как собираетесь его отправить, но в строках To: и Cc: не указывайте адреса списка рассылки и сопровождающего.
Сохраните этот патч в файл в формате почтового ящика UNIX. Например, назовите его a.patch.

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

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

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

Сам патч применяется с ошибками. Это bad, но к почтовому клиенту имеет мало отношения. В этом случае перед повторной генерацией патча можно перебазировать его с помощью git-rebase[1].
Почтовый клиент исказил патч; команда "am" сообщит, что патч не применяется. Проверьте подкаталог .git/rebase-apply/ и содержимое файла patch, а также наличие упомянутых выше распространённых видов искажений.
Заодно проверьте файлы info и final-commit. Если содержимое final-commit не соответствует тому, что вы хотели бы видеть в сообщении журнала коммитов, получателю, скорее всего, придётся вручную редактировать сообщение журнала при применении вашего патча. Такие фразы, как "Hi, this is my first patch.\n", в электронном письме с патчем следует размещать после строки из трёх дефисов, обозначающей конец сообщения коммита.

Советы для конкретных почтовых клиентов

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

GMail

В веб-интерфейсе GMail нельзя отключить перенос строк, поэтому он будет искажать любые отправляемые вами письма. Однако можно воспользоваться командой "git send-email" и отправить патчи через SMTP-сервер GMail либо подключиться к серверу IMAP Google с помощью любого почтового клиента с поддержкой IMAP и переслать письма через него.

Советы по использованию git send-email для отправки патчей через SMTP-сервер GMail см. в разделе EXAMPLE страницы git-send-email[1].

Советы по отправке через интерфейс IMAP см. в разделе EXAMPLE страницы 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 (настройка)

Три шага:

Настройте составление сообщений для почтового сервера в виде обычного текста: Edit…Account Settings…Composition & Addressing, снимите флажок "Compose Messages in HTML".
Настройте общее окно составления сообщений так, чтобы перенос строк был отключён.

В Thunderbird 2: Edit..Preferences..Composition, установите для параметра переноса обычного текста значение 0.

В Thunderbird 3: Edit..Preferences..Advanced..Config Editor. Найдите параметр "mail.wrap_long_lines". Переключите его, чтобы убедиться, что установлено значение false. Также найдите параметр "mailnews.wraplength" и установите его значение равным 0.
Отключите использование format=flowed: Edit..Preferences..Advanced..Config Editor. Найдите параметр "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.

Подготовьте патч в виде текстового файла удобным для вас способом.
Прежде чем открывать окно создания сообщения, выберите Edit→Account Settings и снимите флажок "Compose messages in HTML format" на панели "Composition & Addressing" учётной записи, с которой будет отправлен патч.
В главном окне Thunderbird перед before открытием окна создания сообщения для патча выберите Tools→about:config и установите для следующих параметров указанные значения:
```
        mailnews.send_plaintext_flowed  => false
        mailnews.wraplength             => 0
```
Откройте окно создания сообщения и нажмите значок внешнего редактора.
В окне внешнего редактора откройте файл патча и штатным образом закройте редактор.

Примечание: возможно, шаг 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.

Подготовьте патч в виде текстового файла.
Нажмите New Mail.
В окне создания сообщения откройте меню "Options" и убедитесь, что флажок "Word wrap" снят.
Выберите Message → Insert file… и вставьте патч.
Вернувшись в окно создания сообщения, добавьте любой нужный текст, заполните поля адреса и темы и нажмите кнопку отправки.

Информация об исходном дереве

Блок информации об исходном дереве нужен сопровождающим или сторонним тестировщикам, чтобы знать точное состояние, к которому применяется серия патчей. Он состоит из base commit — известного коммита, входящего в стабильную часть истории проекта, на основе которой работают все остальные, — и нуля или более prerequisite patches, то есть известных патчей, находящихся в работе и ещё не вошедших в base commit. Эти патчи необходимо применить поверх base commit в топологическом порядке до применения остальных патчей.

base commit отображается как "base-commit: " с последующим 40-значным шестнадцатеричным именем объекта коммита. prerequisite patch отображается как "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 для их выборочного применения:
```
$ 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
```
Кроме того, команда интеллектуально обнаруживает и обрабатывает переименования и полные переписывания файлов, создавая патч переименования. Такой патч содержит меньше текста и, как правило, его проще проверять. Обратите внимание: программы для работы с «патчами», не относящиеся к Git, не распознают патчи переименования, поэтому используйте этот вариант, только если знаете, что получатель применяет ваш патч с помощью Git.
Извлечь три последних коммита текущей ветки и оформить их как патчи, готовые к отправке по электронной почте:
```
$ git format-patch -3
```

Предостережения

Обратите внимание: format-patch исключит из вывода коммиты слияния, даже если они входят в запрошенный диапазон. Обычный «патч» не содержит достаточно информации, чтобы принимающая сторона могла воссоздать тот же коммит слияния.

ПРИМЕНЕНИЕ ПАТЧА

При применении вывода git-format-patch[1] с помощью git-am[1] сообщение коммита может измениться. Применённый патч также может отличаться от созданного, либо применение патча может завершиться ошибкой.

Любая строка следующего вида:

три дефиса и конец строки; или
строка, начинающаяся с diff -; или
строка, начинающаяся с `Index: `

считается началом патча, а сообщение журнала коммита обрывается перед первым вхождением такой строки.

Особенно проблематичны не имеющие отступа diff-фрагменты в сообщении коммита: diff в сообщении коммита может быть применён вместе с разделом патча, либо механизм применения патча может дать сбой, поскольку целевой объект патча не подходит. Например, причиной может стать diff в блоке кода Markdown.

Чтобы избежать этого, добавьте отступ к diff-фрагменту или другому тексту, который может вызвать проблемы.

Такую потерю точности легко заметить, если применять патчи непосредственно из почтового ящика. Однако изменения, поступающие из Git, могут применяться пакетно, и тогда обнаружить это будет гораздо сложнее. Например, так может происходить в дистрибутиве Linux, который использует файлы патчей для применения изменений поверх коммитов из репозиториев upstream. Это показывает, что такое поведение затрагивает не только процессы работы с электронной почтой.

Учитывая эти ограничения, может возникнуть соблазн вместо этого воспользоваться универсальной утилитой, например patch(1). Однако patch(1) будет искать не только diff-фрагменты без отступа (как git-am[1]), но и пытаться применять diff-фрагменты с отступом.

См. также

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

© 2005–2026 Linus Torvalds and others
Licensed under the GNU General Public License version 2.
https://git-scm.com/docs/git-format-patch