git-am

Название

git-am — применяет последовательность исправлений из почтового ящика

Краткое описание

git am [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--[no-]verify]
         [--[no-]3way] [--interactive] [--committer-date-is-author-date]
         [--ignore-date] [--ignore-space-change | --ignore-whitespace]
         [--whitespace=<action>] [-C<n>] [-p<n>] [--directory=<dir>]
         [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet]
         [--[no-]scissors] [-S[<key-id>]] [--patch-format=<format>]
         [--quoted-cr=<action>]
         [--empty=(stop|drop|keep)]
         [(<mbox> | <Maildir>)…]
git am (--continue | --skip | --abort | --quit | --retry | --show-current-patch[=(diff|raw)] | --allow-empty)

Описание

Разбивает почтовые сообщения в почтовом ящике на сообщения журнала коммитов, сведения об авторстве и исправления, а затем применяет их к текущей ветке. Это можно считать обратной операцией по отношению к git-format-patch[1], выполненной для ветки с линейной историей без слияний.

Параметры

(<mbox>|<Maildir>)...

Список файлов почтовых ящиков, из которых нужно прочитать исправления. Если этот аргумент не указан, команда читает данные из стандартного ввода. Если указаны каталоги, они будут считаться каталогами Maildir.

-s

--signoff

Добавляет в сообщение коммита завершающую строку Signed-off-by (см. git-interpret-trailers[1]), используя идентификатор коммитера. Дополнительные сведения см. в описании параметра signoff команды git-commit[1].

-k

--keep

Передаёт флаг -k команде git-mailinfo[1].

--keep-non-patch

Передаёт флаг -b команде git-mailinfo[1].

--keep-cr

--no-keep-cr

С параметром --keep-cr передаёт тот же параметр команде git-mailsplit[1], чтобы она не удаляла CR в конце строк. Переменная конфигурации am.keepcr позволяет задать поведение по умолчанию. Параметр --no-keep-cr полезен для переопределения am.keepcr.

-c

--scissors

Удаляет всё содержимое тела сообщения перед строкой с ножницами (см. git-mailinfo[1]). Можно включить по умолчанию с помощью переменной конфигурации mailinfo.scissors.

--no-scissors

Игнорирует строки с ножницами (см. git-mailinfo[1]).

--quoted-cr=<action>

Этот флаг будет передан команде git-mailinfo[1].

--empty=(drop|keep|stop)

Определяет, как обрабатывать электронное письмо без исправления:

drop: Электронное письмо будет пропущено.
keep: Будет создан пустой коммит, сообщением журнала которого станет содержимое электронного письма.
stop: Команда завершится с ошибкой, остановившись посреди текущего сеанса am. Это поведение используется по умолчанию.

-m

--message-id

Передаёт флаг -m команде git-mailinfo[1], чтобы заголовок Message-ID был добавлен в сообщение коммита. Переменная конфигурации am.messageid позволяет задать поведение по умолчанию.

--no-message-id

Не добавляет заголовок Message-ID в сообщение коммита. Параметр --no-message-id полезен для переопределения am.messageid.

-q

--quiet

Не выводит лишних сообщений. Печатает только сообщения об ошибках.

-u

--utf8

Передаёт флаг -u команде git-mailinfo[1]. Предлагаемое сообщение журнала коммита, взятое из электронного письма, перекодируется в UTF-8 (переменная конфигурации i18n.commitEncoding позволяет задать предпочтительную кодировку проекта, если это не UTF-8).

В предыдущих версиях Git это было необязательным, но теперь используется по умолчанию. Чтобы отменить это поведение, можно использовать --no-utf8.

--no-utf8

Передаёт флаг -n команде git-mailinfo[1].

-3

--3way

--no-3way

Если исправление не применяется без конфликтов, выполняет слияние в три стороны, если в исправлении записаны идентификаторы применяемых объектов blob и эти объекты доступны локально. Параметр --no-3way позволяет переопределить переменную конфигурации am.threeWay. Дополнительные сведения см. в описании am.threeWay в git-config[1].

--rerere-autoupdate

--no-rerere-autoupdate

После того как механизм rerere повторно использует сохранённое разрешение текущего конфликта для обновления файлов в рабочем дереве, позволяет ему также обновить индекс результатом разрешения. Параметр --no-rerere-autoupdate — хороший способ проверить, что сделала команда git-rerere[1], и обнаружить возможные ошибки слияния до фиксации результата в индексе отдельной командой git-add[1].

--ignore-space-change

--ignore-whitespace

--whitespace=<action>

-C<n>

-p<n>

--directory=<dir>

--exclude=<path>

--include=<path>

--reject

Эти флаги передаются программе git-apply[1], которая применяет исправление.

Допустимые значения <action> для параметра --whitespace: nowarn, warn, fix, error и error-all.

--patch-format

По умолчанию команда пытается автоматически определить формат исправления. Этот параметр позволяет отключить автоматическое определение и явно указать формат, в котором следует интерпретировать исправления. Допустимые форматы: mbox, mboxrd, stgit, stgit-series и hg.

-i

--interactive

Запускает команду в интерактивном режиме.

--verify

-n

--no-verify

Запускает хуки pre-applypatch и applypatch-msg. Это поведение используется по умолчанию. Чтобы пропустить эти хуки, используйте -n или --no-verify. См. также githooks[5].

Обратите внимание, что пропустить post-applypatch нельзя.

--committer-date-is-author-date

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

Предупреждение

Алгоритмы обхода истории предполагают, что временные метки коммитов не убывают. Подумайте, действительно ли вам нужен этот параметр. Используйте его для переопределения даты коммитера только при применении коммитов поверх базового коммита, который старше (по дате коммита), чем самое раннее применяемое исправление.

--ignore-date

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

--skip

Пропускает текущее исправление. Имеет смысл только при возобновлении прерванного применения исправлений.

-S[<key-id>]

--gpg-sign[=<key-id>]

--no-gpg-sign

Подписывает коммиты с помощью GPG. Параметр <key-id> необязателен и по умолчанию соответствует идентификатору коммитера; если он указан, его нужно присоединить к параметру без пробела. Параметр --no-gpg-sign полезен для отмены как переменной конфигурации commit.gpgSign, так и предыдущих параметров --gpg-sign.

--continue

-r

--resolved

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

--resolvemsg=<msg>

При сбое применения исправления перед выходом на экран будет выведено сообщение <msg>. Оно заменяет стандартное сообщение с рекомендацией использовать --continue или --skip для обработки сбоя. Этот параметр предназначен исключительно для внутреннего взаимодействия между git-rebase[1] и git-am[1].

--abort

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

--quit

Прерывает операцию применения исправлений, но оставляет HEAD и индекс без изменений.

--retry

Повторно пытается применить последнее конфликтующее исправление. Обычно этот параметр полезен только для передачи дополнительных параметров при повторной попытке (например, --3way), поскольку в противном случае ошибка просто повторится.

--show-current-patch[=(diff|raw)]

Показывает сообщение, на котором git-am[1] остановилась из-за конфликтов. Если указан параметр raw, выводится исходное содержимое электронного письма; если diff — только часть с разницей. По умолчанию используется raw.

--allow-empty

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

Обсуждение

Имя автора коммита берётся из строки "From: " сообщения, а дата автора коммита — из строки "Date: ". Строка "Subject: " используется в качестве заголовка коммита после удаления распространённого префикса "[PATCH <anything>]". Предполагается, что строка "Subject: " кратко описывает суть коммита в одной строке.

Строки "From: ", "Date: " и "Subject: " в начале тела сообщения переопределяют соответствующие значения имени автора коммита и заголовка, взятые из заголовков письма.

Сообщение коммита формируется из заголовка, взятого из "Subject: ", пустой строки и тела сообщения до начала исправления. Лишние пробелы в конце каждой строки автоматически удаляются.

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

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

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

Это означает, что содержимое сообщения коммита может случайно прервать обработку (см. раздел ПРЕДОСТЕРЕЖЕНИЯ ниже).

При первоначальном запуске git-am[1] вы указываете имена обрабатываемых почтовых ящиков. При обнаружении первого исправления, которое не удаётся применить, выполнение прерывается. Восстановить работу можно одним из двух способов:

пропустить текущее исправление, повторно запустив команду с параметром --skip.
вручную разрешить конфликт в рабочем каталоге и обновить файл индекса, приведя его в состояние, которое должно было получиться после применения исправления. Затем запустить команду с параметром --continue.

Команда отказывается обрабатывать новые почтовые ящики, пока не завершена текущая операция. Поэтому, если вы решили начать заново, выполните git am --abort, прежде чем запускать команду с именами почтовых ящиков.

Перед применением исправлений ORIG_HEAD устанавливается на вершину текущей ветки. Это полезно, если возникают проблемы с несколькими коммитами, например если команда git-am[1] запущена не в той ветке или в коммитах есть ошибка, которую проще исправить, изменив почтовый ящик (например, ошибки в строках From:).

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

При применении с помощью git-am[1] вывод команды git-format-patch[1] может привести к другому сообщению коммита. Применённое исправление также может отличаться от созданного, либо его применение может завершиться ошибкой. Синтаксические правила описаны выше в разделе ОБСУЖДЕНИЕ.

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

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

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

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

Хуки

Эта команда может запускать хуки applypatch-msg, pre-applypatch и post-applypatch. Дополнительные сведения см. в githooks[5].

См. параметры --verify/-n/--no-verify.

Настройка

Всё содержимое ниже этой строки в данном разделе выборочно включено из документации git-config[1]. Оно совпадает с содержимым соответствующего раздела:

am.keepcr: Если значение равно true, git-am[1] вызовет git-mailsplit[1] для исправлений в формате mbox с параметром --keep-cr. В этом случае git-mailsplit[1] не будет удалять \r из строк, заканчивающихся на \r\n. Это поведение можно переопределить, указав --no-keep-cr в командной строке.
am.threeWay: По умолчанию git-am[1] завершится с ошибкой, если исправление не удастся применить без конфликтов. Если значение равно true, этот параметр указывает git-am[1] выполнить слияние в три стороны, если в исправлении записаны идентификаторы применяемых объектов blob и эти объекты доступны локально (что эквивалентно указанию параметра --3way в командной строке). По умолчанию установлено значение false.
am.messageId: При использовании git-am[1] добавляет в коммит завершающую строку Message-ID, сформированную на основе заголовка электронного письма (см. git-interpret-trailers[1]). См. также параметры --message-id и --no-message-id.

См. также

git-apply[1], git-format-patch[1].

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