git-format-patch - Подготовка патчей для отправки по электронной почте
git format-patch [-k] [(-o|--output-directory) <dir> | --stdout]
[--no-thread | --thread[=<style>]]
[(--attach|--inline)[=<boundary>] | --no-attach]
[-s | --signoff]
[--signature=<signature> | --no-signature]
[--signature-file=<file>]
[-n | --numbered | -N | --no-numbered]
[--start-number <n>] [--numbered-files]
[--in-reply-to=<message-id>] [--suffix=.<sfx>]
[--ignore-if-in-upstream] [--always]
[--cover-from-description=<mode>]
[--rfc[=<rfc>]] [--subject-prefix=<subject-prefix>]
[(--reroll-count|-v) <n>]
[--to=<email>] [--cc=<email>]
[--[no-]cover-letter] [--quiet]
[--[no-]encode-email-headers]
[--no-notes | --notes[=<ref>]]
[--interdiff=<previous>]
[--range-diff=<previous> [--creation-factor=<percent>]]
[--filename-max-length=<n>]
[--progress]
[<common-diff-options>]
[ <since> | <revision-range> ] Подготовить каждый не-слияние коммит с его «патчем» в одном «сообщении» на коммит, отформатированном так, чтобы напоминать почтовый ящик UNIX. Выходные данные этой команды удобны для отправки по электронной почте или для использования с git am.
«Сообщение», сгенерированное командой, состоит из трёх частей:
Краткая заголовок метаданных, начинающийся с From <commit> с фиксированным Mon Sep 17 00:00:00 2001 отметкой даты, чтобы помочь программам, таким как «file(1)», распознать, что файл является результатом работы этой команды, поля, которые записывают идентификатор автора, дату автора и заголовок изменения (взятые из первого абзаца сообщения коммита).
Второй и последующие абзацы сообщения коммита.
«Патч», который является выводом «diff -p --stat» (см. git-diff[1]) между коммитом и его родителем.
Сообщение журнала и патч разделены строкой с тройной чертой.
Существует два способа указать, над какими коммитами нужно выполнить операцию.
Один коммит, <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 для ссылки.
Генерировать простые патчи без diffstats.
Генерировать diffs с <n> строками контекста вместо стандартных трёх.
Выводить в указанный файл вместо стандартного потока вывода.
Указать символ, используемый для обозначения новых, старых или контекстных строк в генерируемом патче. Обычно это +, - и ' ' соответственно.
Включить эвристику, смещающую границы блоков diff, для улучшения читабельности патчей. По умолчанию включена.
Отключить эвристику смещения.
Потратить дополнительное время на получение самого маленького возможного diff.
Генерировать diff с использованием алгоритма "patience diff".
Генерировать diff с использованием алгоритма "histogram diff".
Генерировать diff с использованием алгоритма "anchored diff".
Этот параметр можно указать несколько раз.
Если строка существует как в исходном, так и в целевом файлах, встречается только один раз и начинается с этого текста, этот алгоритм пытается предотвратить её отображение как удаления или добавления в выходные данные. Внутренне он использует алгоритм "patience diff".
Выбор алгоритма diff. Доступные варианты:
default, myers Базовый жадный алгоритм diff. В настоящее время используется по умолчанию.
minimal Потратить дополнительное время на получение самого маленького возможного diff.
patience Использовать алгоритм "patience diff" при генерации патчей.
histogram Этот алгоритм расширяет алгоритм "patience" для поддержки элементов с низкой частотой.
Например, если вы настроили переменную diff.algorithm на значение отличное от значения по умолчанию и хотите использовать значение по умолчанию, то вам необходимо использовать параметр --diff-algorithm=default.
Генерировать diffstat. По умолчанию используется необходимое пространство для имени файла и остальное для графика. Максимальная ширина по умолчанию соответствует ширине терминала или 80 столбцам, если подключение к терминалу отсутствует, и может быть изменена с помощью <width>. Ширина части имени файла может быть ограничена, указав другую ширину <name-width> после запятой или установив diff.statNameWidth=<width>. Ширина части графика может быть ограничена, используя --stat-graph-width=<width> или установив diff.statGraphWidth=<width>. Использование --stat или --stat-graph-width влияет на все команды, генерирующие график stat, в то время как установка diff.statNameWidth или diff.statGraphWidth не влияет на git format-patch. Указав третий параметр <count>, вы можете ограничить вывод первыми <count> строками, а за ними ... в случае превышения.
Эти параметры также могут быть заданы индивидуально с помощью --stat-width=<width>, --stat-name-width=<name-width> и --stat-count=<count>.
Выводить свёрнутое резюме расширенной информации заголовков, такой как создание или удаление файлов ("new" или "gone", опционально "+l" если это символическая ссылка) и изменения режима ("+x" или "-x" для добавления или удаления бита разрешения на выполнение соответственно) в diffstat. Информация размещается между частью имени файла и частью графика. Подразумевает --stat.
Аналогично --stat, но показывает количество добавленных и удалённых строк в десятичном формате и имя файла без сокращений, чтобы сделать его более машиночитаемым. Для двоичных файлов выводит две - вместо сообщения 0 0.
Выводить только последнюю строку формата --stat, содержащую общее количество изменённых файлов, а также количество добавленных и удалённых строк.
Выводить распределение относительного количества изменений для каждого подкаталога. Поведение --dirstat может быть настроено путём передачи ему списка параметров, разделённых запятыми. Значения по умолчанию контролируются переменной конфигурации diff.dirstat (см. git-config[1]). Доступны следующие параметры:
changes Вычислять значения dirstat, подсчитывая строки, удалённые из исходного файла или добавленные в целевой. Это игнорирует количество чистого перемещения кода внутри файла. Иными словами, перестановка строк в файле не учитывается так сильно, как другие изменения. Это поведение по умолчанию, когда параметры не указаны.
lines Вычислять значения dirstat путём выполнения стандартного анализа diff, основанного на строках, и суммирования количества удалённых/добавлено строк. (Для двоичных файлов вместо строк подсчитываются 64-байтовые блоки, так как двоичные файлы не имеют понятий строк). Это более ресурсоёмкое --dirstat поведение, чем changes поведение, но оно учитывает перестановку строк в файле так же, как и другие изменения. Результат совпадает с тем, что вы получаете с другими --*stat параметрами.
files Вычислять значения dirstat путём подсчёта количества изменённых файлов. Каждый изменённый файл имеет равный вклад в анализ dirstat. Это наименее ресурсоёмкое --dirstat поведение, так как ему не нужно смотреть на содержимое файлов.
cumulative Учитывать изменения в дочернем каталоге для родительского каталога тоже. Обратите внимание, что при использовании cumulative, сумма отчётов о процентах может превышать 100%. По умолчанию (не-кумулятивное) поведение можно указать с параметром noncumulative.
Целое число, задающее порог процента (3% по умолчанию). Каталоги, вносящие менее этого процента изменений, не отображаются в выводе.
Пример: следующее будет подсчитывать изменённые файлы, игнорируя каталоги, вклад которых меньше 10% от общего количества изменённых файлов, и аккумулировать счётчики дочерних каталогов в родительских каталогах: --dirstat=files,10,cumulative.
Синоним для --dirstat=cumulative
Синоним для --dirstat=files,<param1>,<param2>…
Вывести свёрнутое резюме расширенной информации заголовков, такой как создание, переименование и изменения режима.
Отключить обнаружение переименований, даже если файл конфигурации по умолчанию настроен на это.
Использовать пустые объекты blob как источник переименований.
Вместо первых нескольких символов показать полные имена объектов blob предварительного и последующего состояния в строке "index" при генерации вывода в формате патча.
В дополнение к --full-index, выводить двоичный diff, который можно применить с помощью git-apply.
Вместо отображения полного 40-байтового шестнадцатеричного имени объекта в выводе diff-raw и заголовках diff-tree, отображать самый короткий префикс, содержащий как минимум <n> шестнадцатеричных цифр, который однозначно указывает на объект. В формате diff-patch --full-index имеет приоритет, то есть, если --full-index указан, полные имена объектов blob будут показаны независимо от --abbrev. Нестандартное количество цифр можно указать с помощью --abbrev=<n>.
Разбивайте полные переписывания изменений на пары удаления и создания. Это служит двум целям:
Это влияет на то, как изменение, которое сводится к полному переписыванию файла, не как серия удалений и вставок, смешанных вместе с очень небольшим количеством строк, которые случайно совпадают по тексту как контекст, а как одно удаление всего старого, за которым следует одно вставка всего нового, и число m контролирует этот аспект опции -B (по умолчанию 60%). -B/70% указывает, что менее 30% исходного текста должно остаться в результате, чтобы Git посчитал это полным переписыванием (иначе полученный патч будет серией удалений и вставок, смешанных вместе с контекстными строками).
При использовании с -M полностью переписанный файл также рассматривается как исходный файл переименования (обычно -M рассматривает только исчезнувший файл как исходный файл переименования), и число n контролирует этот аспект опции -B (по умолчанию 50%). -B20% указывает, что изменение с добавлением и удалением по сравнению с 20% или более размером файла подходит для того, чтобы быть выбранным как возможный исходный файл переименования в другой файл.
Обнаружение переименований. Если n указано, это порог индекса сходства (т.е. количество добавлений/удалений по сравнению с размером файла). Например, -M90% означает, что Git должен считать пару удаление/добавление переименованием, если более 90% файла не изменилось. Без знака %, число должно читаться как дробь с десятичной точкой перед ним. Например, -M5 становится 0,5 и, таким образом, совпадает с -M50%. Аналогично, -M05 совпадает с -M5%. Чтобы ограничить обнаружение точными переименованиями, используйте -M100%. По умолчанию индекс сходства составляет 50%.
Обнаружение копий, а также переименований. Смотрите также --find-copies-harder. Если n указано, оно имеет то же значение, что и для -M<n>.
По соображениям производительности, по умолчанию опция -C находит копии только в том случае, если исходный файл копии был изменен в том же наборе изменений. Этот флаг заставляет команду проверять неизменённые файлы как кандидаты на источник копии. Это очень дорогостоящая операция для больших проектов, поэтому используйте её с осторожностью. Указание более одной опции -C имеет тот же эффект.
Опустить преизображение для удалений, т.е. вывести только заголовок, но не разницу между преизображением и /dev/null. Полученный патч не предназначен для применения с patch или git apply; это исключительно для тех, кто хочет сосредоточиться на просмотре текста после изменения. Кроме того, вывод очевидно не содержит достаточной информации для применения такого патча в обратном направлении, даже вручную, отсюда и название опции.
При использовании вместе с -B, также опустить преизображение в части удаления пары удаление/создание.
Опции -M и -C включают в себя некоторые предварительные шаги, которые могут дешево обнаружить подмножества переименований/копий, за которыми следует исчерпывающая часть, которая сравнивает все оставшиеся неспаренные пункты назначения со всеми соответствующими источниками. (Для переименований актуальны только оставшиеся неспаренные источники; для копий – все исходные источники). Для N источников и пунктов назначения эта исчерпывающая проверка имеет сложность O(N^2). Эта опция предотвращает выполнение исчерпывающей части обнаружения переименований/копий, если число вовлеченных файлов источника/пункта назначения превышает указанное число. По умолчанию используется diff.renameLimit. Обратите внимание, что значение 0 обрабатывается как неограниченное.
Управление порядком, в котором файлы появляются в выводе. Это переопределяет переменную конфигурации 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".
Отбросить файлы перед указанным файлом <file> из вывода (т.е. skip to), или переместить их в конец вывода (т.е. rotate to). Эти опции были изобретены в первую очередь для использования с командой git difftool, и в других случаях они могут не быть очень полезными.
При запуске из подкаталога проекта ему можно сказать, чтобы он исключал изменения вне каталога и показывал имена путей относительно него с помощью этой опции. Когда вы не находитесь в подкаталоге (например, в голом репозитории), вы можете указать, относительно какого подкаталога должен выводиться результат, указав <path> в качестве аргумента. --no-relative может использоваться для противодействия как опции конфигурации diff.relative, так и предыдущей опции --relative.
Обрабатывать все файлы как текстовые.
Игнорировать возврат каретки в конце строки при сравнении.
Игнорировать изменения в пробелах в конце строки.
Игнорировать изменения в количестве пробелов. Это игнорирует пробелы в конце строки и считает все другие последовательности из одного или более пробелов эквивалентными.
Игнорировать пробелы при сравнении строк. Это игнорирует различия, даже если одна строка содержит пробелы, а другая — нет.
Игнорировать изменения, все строки которых пустые.
Игнорировать изменения, все строки которых соответствуют <regex>. Эту опцию можно указать более одного раза.
Показать контекст между разделами различий до указанного числа строк, тем самым объединяя разделы, которые находятся близко друг к другу. По умолчанию используется diff.interHunkContext или 0, если опция конфигурации не задана.
Показать всю функцию как контекстные строки для каждого изменения. Имена функций определяются так же, как git diff определяет заголовки блоков изменений патча (см. Defining a custom hunk-header в gitattributes[5]).
Разрешить выполнение внешнего помощника по различиям. Если вы установили внешний драйвер различий с помощью gitattributes[5], вам нужно использовать эту опцию с git-log[1] и аналогичными командами.
Запретить внешние драйверы различий.
Разрешить (или запретить) выполнение внешних фильтров преобразования текста при сравнении двоичных файлов. Подробнее см. в gitattributes[5]. Поскольку фильтры textconv обычно являются преобразованиями в одну сторону, полученные различия подходят для просмотра человеком, но не могут быть применены. По этой причине фильтры textconv включены по умолчанию только для git-diff[1] и git-log[1], но не для git-format-patch[1] или команд обработки различий.
Игнорировать изменения в подмодулях при генерации разницы. <when> может принимать значения "none", "untracked", "dirty" или "all" (по умолчанию). Использование "none" будет рассматривать подмодуль как изменённый, если он содержит неотслеженные или изменённые файлы, или его HEAD отличается от коммита, записанного в суперпроекте, и может использоваться для переопределения любых настроек опции ignore в git-config[1] или gitmodules[5]. При использовании "untracked" подмодули не считаются изменёнными, если они содержат только неотслеженные данные (но они всё равно проверяются на изменённые данные). Использование "dirty" игнорирует все изменения в рабочей области подмодулей, отображаются только изменения в коммитах, хранящихся в суперпроекте (таким было поведение до версии 1.7.0). Использование "all" скрывает все изменения в подмодулях.
Показать заданный префикс источника вместо "a/".
Показать заданный префикс назначения вместо "b/".
Не показывать ни префикс источника, ни префикс назначения.
Использовать стандартные префиксы источника и назначения ("a/" и "b/"). Это переопределяет переменные конфигурации, такие как diff.noprefix, diff.srcPrefix, diff.dstPrefix, и diff.mnemonicPrefix (см. git-config(1)).
Добавить дополнительный префикс к каждой строке вывода.
По умолчанию, записи, добавленные командой "git add -N", отображаются как существующий пустой файл в "git diff" и как новый файл в "git diff --cached". Данная опция отображает запись как новый файл в "git diff" и как несуществующий файл в "git diff --cached". Эту опцию можно отменить с помощью --ita-visible-in-index. Обе опции являются экспериментальными и могут быть удалены в будущем.
Для более подробного объяснения этих общих опций, см. также gitdiffcore[7].
Подготовить патчи из самых верхних <n> коммитов.
Использовать <dir> для хранения результирующих файлов вместо текущей рабочей директории.
Назвать вывод в формате [PATCH n/m], даже с одним патчем.
Назвать вывод в формате [PATCH].
Начать нумерацию патчей с <n> вместо 1.
Имена выходных файлов будут простым числовым рядом без стандартной первой строки коммита.
Не удалять/добавлять [PATCH] из первой строки сообщения коммита.
Добавить подпись Signed-off-by в сообщение коммита, используя идентификатор отправителя. См. параметр signoff в git-commit[1] для получения дополнительной информации.
Вывести все коммиты в стандартный вывод в формате mbox, вместо создания файла для каждого.
Создать прикрепленный файл multipart/mixed, первая часть которого — сообщение коммита, а вторая — сам патч с Content-Disposition: attachment.
Отключить создание прикреплённого файла, переопределяя системную настройку.
Создать прикрепленный файл multipart/mixed, первая часть которого — сообщение коммита, а вторая — сам патч с Content-Disposition: inline.
Управляет добавлением 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.
Сделать первое письмо (или все письма с --no-thread) ответом на заданный <message-id>, что предотвращает разрыв цепочки для предоставления новой серии патчей.
Не включать патч, соответствующий коммиту в <until>..<since>. Это проверит все патчи, достижимые от <since>, но не от <until>, и сравнит их с генерируемыми патчами. Любой совпавший патч будет проигнорирован.
Включить патчи для коммитов, не вносящих изменений, которые по умолчанию пропускаются.
Управляет тем, какие части письма будут автоматически заполняться описанием ветви.
Если <mode> равно message или default, тема письма будет заполнена подстановкой. Тело письма будет заполнено описанием ветви. Это режим по умолчанию, если не задана конфигурация или не указан параметр командной строки.
Если <mode> равно subject, первое предложение описания ветви заполнит тему письма. Остальная часть описания заполнит тело письма.
Если <mode> равно auto, если первое предложение описания ветви больше 100 байт, режим будет message, иначе subject.
Если <mode> равно none, и тема письма, и тело письма будут заполнены подстановками.
Использовать содержимое <file> вместо описания ветви для генерации письма.
Вместо стандартного префикса [PATCH] в строке темы, использовать [<subject-prefix>]. Это может быть использовано для именования серии патчей и может быть совмещено с опцией --numbered.
Переменная конфигурации format.subjectPrefix также может использоваться для настройки префикса темы, применимого к данному репозиторию для всех патчей. Это часто полезно на списках рассылки, которые получают патчи для нескольких репозиториев, и может помочь различить патчи (например, с значением «PATCH my-project»).
Вместо стандартных 64 байт, обрезать имена генерируемых выходных файлов до примерно <n> байт (слишком маленькое значение будет молча увеличено до разумной длины). По умолчанию — значение переменной конфигурации format.filenameMaxLength, или 64, если не настроена.
Добавляет строку <rfc> (по умолчанию «RFC») перед префиксом темы. Поскольку префикс темы по умолчанию «PATCH», вы получите «RFC PATCH» по умолчанию.
RFC означает «Request For Comments»; используйте это, когда отправляете экспериментальный патч для обсуждения, а не для применения. «--rfc=WIP» также может быть полезным способом указать, что патч еще не завершён («WIP» означает «Work In Progress»).
Если конвенция сообщества для дополнительной строки заключается в ее after префиксом темы, строка <rfc> может быть добавлена с дефисом («-»), чтобы указать, что остальная часть строки <rfc> должна быть добавлена к префиксу темы, например, --rfc='-(WIP)' даёт «PATCH (WIP»).
Пометить серию как <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» допустимы), но недостатком использования такого reroll-count является то, что различие с предыдущей версией не указывает точно, с какой версией сравнивается новая итерация.
Добавить заголовок To: в заголовки электронных писем. Это дополнительно к любым настроенным заголовкам и может использоваться несколько раз. Отрицательная форма --no-to отбрасывает все добавленные ранее заголовки To: (из конфигурации или командной строки).
Добавить заголовок Cc: в заголовки электронных писем. Это дополнительно к любым настроенным заголовкам и может использоваться несколько раз. Отрицательная форма --no-cc отбрасывает все добавленные ранее заголовки Cc: (из конфигурации или командной строки).
Использовать ident в заголовке From: каждого письма коммита. Если идентификатор автора коммита не совпадает с указанным ident, добавить заголовок From: в тело сообщения с оригинальным автором. Если ident не указан, используется идентификатор отправителя.
Обратите внимание, что этот параметр полезен только если вы фактически отправляете письма и хотите идентифицировать себя как отправителя, но сохранить оригинального автора (и git am правильно подберёт заголовок в теле). Также обратите внимание, что git send-email уже выполняет эту трансформацию за вас, и этот параметр не следует использовать, если вы передаёте результат в git send-email.
При указании отправителя электронной почты с помощью опции --from, по умолчанию, в тело сообщения коммита добавляется «From:», идентифицирующий реального автора коммита, если отправитель отличается от автора. С этим параметром «From:» в теле добавляется даже если отправитель и автор имеют одинаковое имя и адрес, что может быть полезно, если программное обеспечение списка рассылки искажает идентификатор отправителя. По умолчанию — значение переменной конфигурации format.forceInBodyFrom.
Добавьте произвольный заголовок к заголовкам электронного письма. Это дополнительно к любым настроенным заголовкам и может использоваться несколько раз. Например, --add-header="Organization: git-foo". Отрицательная форма --no-add-header отбрасывает все (To:, Cc:, и пользовательские) заголовки, добавленные до этого из конфигурации или командной строки.
В дополнение к патчам, сгенерируйте файл письма с описанием ветки, кратким списком изменений и общим статусом различий. Вы можете заполнить описание в файле перед отправкой.
Кодировать заголовки электронных писем, содержащие не-ASCII символы с помощью "Q-кодирования" (описанного в RFC 2047), вместо вывода заголовков дословно. По умолчанию используется значение переменной конфигурации format.encodeEmailHeaders.
В качестве помощи для ревьюера, вставьте междифференцирование в письмо, или как комментарий к единственному патчу серии из 1 патча, показывая различия между предыдущей версией серии патчей и серией, которая в настоящее время форматируется. previous — это имя единственной ревизии, обозначающей вершину предыдущей серии, которая имеет общую базу с серией, которая форматируется (например, git format-patch
--cover-letter --interdiff=feature/v1 -3 feature/v2).
В качестве помощи для ревьюера, вставьте range-diff (см. git-range-diff[1]) в письмо, или как комментарий к единственному патчу серии из 1 патча, показывая различия между предыдущей версией серии патчей и серией, которая в настоящее время форматируется. previous может быть единственной ревизией, обозначающей вершину предыдущей серии, если она имеет общую базу с серией, которая форматируется (например, git format-patch --cover-letter --range-diff=feature/v1 -3
feature/v2), или диапазоном ревизий, если две версии серии не пересекаются (например, git format-patch --cover-letter
--range-diff=feature/v1~3..feature/v1 -3 feature/v2).
Обратите внимание, что параметры diff, переданные команде, влияют на то, как генерируется основной результат format-patch, и они не передаются в подсистему range-diff, используемой для генерации материалов письма (это может измениться в будущем).
Используется с --range-diff, настраивает эвристику, которая сопоставляет коммиты между предыдущей и текущей серией патчей, регулируя коэффициент корректировки затрат на создание/удаление. См. git-range-diff[1] для получения подробностей.
По умолчанию 999 (в git-range-diff[1] используется 60), так как целевой случай — показать сравнение со старой итерацией одной и той же темы, и инструмент должен найти больше соответствий между двумя наборами патчей.
Добавить заметки (см. git-notes[1]) к коммиту после строки с тремя дефисами.
Ожидаемый случай использования — написать дополнительные объяснения к коммиту, которые не относятся к сообщению коммита, и включить их в отправку патча. Хотя можно просто написать эти объяснения после того, как format-patch выполнится, но перед отправкой, сохранение их как заметки Git позволяет поддерживать их между версиями серии патчей (но см. обсуждение опций конфигурации notes.rewrite в git-notes[1], чтобы использовать этот рабочий процесс).
По умолчанию --no-notes, если не настроено format.notes.
Добавить подпись к каждому сгенерированному сообщению. Согласно RFC 3676 подпись отделена от тела строки с «-- » в ней. Если опция подписи опущена, подпись по умолчанию — номер версии Git.
Работает так же, как --signature, только подпись читается из файла.
Вместо использования .patch в качестве суффикса для сгенерированных имён файлов, используйте указанный суффикс. Распространённая альтернатива — --suffix=.txt. Опущение этого параметра удалит суффикс .patch.
Обратите внимание, что ведущий символ не обязательно должен быть точкой; например, вы можете использовать --suffix=-patch для получения 0001-description-of-my-change-patch.
Не выводить имена сгенерированных файлов в стандартный вывод.
Не выводить содержимое изменений в двоичных файлах, вместо этого выводить уведомление об изменении этих файлов. Сгенерированные с этой опцией патчи не могут быть корректно применены, но они всё ещё полезны для ревью кода.
Выводит нулевой хэш в заголовке From каждого патча вместо хэша коммита.
Записывает информацию о корневом дереве для идентификации состояния, к которому применяется серия патчей. Смотрите раздел ИНФОРМАЦИЯ О КОРНЕВОМ ДЕРЕВЕ ниже для получения подробностей. Если <commit> — «auto», базовый коммит выбирается автоматически. Опция --no-base переопределяет настройку format.useAutoBase.
Обрабатывает аргумент ревизии как <диапазон_ревизий>, даже если это всего один коммит (который обычно обрабатывается как <с>). Обратите внимание, что коммиты корней, включённые в указанный диапазон, всегда форматируются как патчи создания, независимо от этого флага.
Показывать отчёты о ходе выполнения на stderr по мере генерации патчей.
Вы можете указать дополнительные строки заголовков почты для добавления к каждому сообщению, значения по умолчанию для префикса темы и суффикса файла, пронумеровать патчи при выводе более одного патча, добавить заголовки «To:» или «Cc:», настроить вложения, изменить каталог вывода патчей и подписывать патчи с помощью переменных конфигурации.
[format]
headers = "Organization: git-foo\n"
subjectPrefix = CHANGE
suffix = .txt
numbered = auto
to = <email>
cc = <email>
attach [ = mime-boundary-string ]
signOff = true
outputDirectory = <directory>
coverLetter = auto
coverFromDescription = auto Патч, созданный git format-patch, находится в формате почтового ящика UNIX с фиксированным временным отметкой «магического» типа, чтобы указать, что файл выводится из format-patch, а не из реального почтового ящика, как показано ниже:
From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001 From: Tony Luck <tony.luck@intel.com> Date: Tue, 13 Jul 2010 11:42:54 -0700 Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?= =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit arch/arm 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 ...
Обычно он помещается в папку черновиков MUA, редактируется для добавления своевременных комментариев, которые не должны попадать в журнал изменений после трех дефисов, и затем отправляется как сообщение, тело которого, в нашем примере, начинается с «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, не соответствует тому, что вы хотели бы увидеть в сообщении коммита, очень вероятно, что получатель отредактирует сообщение коммита вручную при применении вашего патча. Такие вещи, как «Привет, это мой первый патч.\n» в электронном письме с патчем должны приходить после строки с тремя дефисами, которая сигнализирует об окончании сообщения коммита.
Вот несколько советов о том, как успешно отправлять исправления встраиваемо в сообщения электронной почты с помощью различных почтовых клиентов.
В веб-интерфейсе GMail нет способа отключить перенос строк, поэтому он будет искажать любые отправляемые вами электронные письма. Однако вы можете использовать «git send-email» и отправлять свои исправления через SMTP-сервер GMail или использовать любой почтовый клиент IMAP для подключения к серверу IMAP Google и перенаправлять электронные письма через него.
Чтобы получить подсказки по использованию git send-email для отправки исправлений через SMTP-сервер GMail, см. раздел EXAMPLE в git-send-email[1].
Чтобы получить подсказки по отправке с помощью интерфейса IMAP, см. раздел EXAMPLE в git-imap-send[1].
По умолчанию Thunderbird будет переносить строки в электронных письмах, а также помечать их как format=flowed, что сделает полученное электронное письмо непригодным для использования Git.
Существует три различных подхода: использование дополнения для отключения переноса строк, настройка Thunderbird для того, чтобы он не искажал исправления или использование внешнего редактора, чтобы предотвратить искажение исправлений Thunderbird.
Установите дополнение Toggle Word Wrap, которое доступно по адресу https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/. Оно добавляет пункт меню «Включить перенос слов» в меню «Параметры» окна написания сообщения, который можно выбрать. Теперь вы можете составлять сообщение, как обычно (вырезать + вставить, git format-patch | git imap-send, и т.д.), но вам необходимо вручную вставлять разрывы строк в любой текст, который вы печатаете.
Три шага:
Настройте составление сообщений почтового сервера как простой текст: Открыть…Настройки учетной записи…Составление и адресация, снять флажок «Составлять сообщения в формате HTML».
Настройте общее окно составления сообщения, чтобы оно не переносило строки.
В Thunderbird 2: Редактировать..Настройки..Составление, перенос строк в простых текстовых сообщениях на 0
В Thunderbird 3: Редактировать..Настройки..Дополнительно..Редактор настроек. Найдите «mail.wrap_long_lines». Убедитесь, что он установлен на false. Также найдите «mailnews.wraplength» и установите значение в 0.
Отключить использование format=flowed: Редактировать..Настройки..Дополнительно..Редактор настроек. Найдите «mailnews.send_plaintext_flowed». Убедитесь, что он установлен на false.
После этого вы сможете составлять электронные письма, как обычно (вырезать + вставить, git format-patch | git imap-send, и т.д.), и исправления не будут искажены.
Необходимы следующие расширения Thunderbird: AboutConfig с https://mjg.github.io/AboutConfig/ и External Editor с https://globs.org/articles.php?lng=en&pg=8
Подготовьте исправление в виде текстового файла с помощью своего метода.
Перед открытием окна составления сообщения используйте Редактировать→Настройки учетной записи, чтобы снять флажок «Составлять сообщения в формате HTML» в панели «Составление и адресация» для учетной записи, которая будет использоваться для отправки исправления.
В главном окне Thunderbird, before при открытии окна составления сообщения для исправления, используйте Инструменты→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.
Подготовьте исправление в виде текстового файла.
Нажмите «Новое письмо».
В окне составления сообщения перейдите в «Параметры» и убедитесь, что «Перенос строк» не включен.
Используйте «Сообщение» → «Вставить файл…» и вставьте исправление.
Вернитесь в окно составления сообщения: добавьте любой другой текст, который вы хотите в сообщение, заполните поля адресатов и темы, и нажмите «Отправить».
Блок информации о базовом дереве используется для того, чтобы разработчики или сторонние тестировщики знали точное состояние, к которому применяется серия исправлений. Он состоит из 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 для cherry-picking:
$ 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 исключит коммиты слияния из вывода, даже если они являются частью запрошенного диапазона. Простое «исправление» не содержит достаточной информации для воспроизведения того же коммита слияния на стороне получателя.
© 2005–2024 Linus Torvalds and others
Licensed under the GNU General Public License version 2.
https://git-scm.com/docs/git-format-patch