Documentation/git-am.txt

   1 git-am(1)
   2 =========
   3
   4 NAME
   5 ----
   6 git-am - Apply a series of patches from a mailbox
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8]
  13          [--[no-]3way] [--interactive] [--committer-date-is-author-date]
  14          [--ignore-date] [--ignore-space-change | --ignore-whitespace]
  15          [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>]
  16          [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet]
  17          [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>]
  18          [--quoted-cr=<action>]
  19          [--empty=(stop|drop|keep)]
  20          [(<mbox> | <Maildir>)...]
  21 'git am' (--continue | --skip | --abort | --quit | --show-current-patch[=(diff|raw)] | --allow-empty)
  22
  23 DESCRIPTION
  24 -----------
  25 Splits mail messages in a mailbox into commit log message,
  26 authorship information and patches, and applies them to the
  27 current branch.
  28
  29 OPTIONS
  30 -------
  31 (<mbox>|<Maildir>)...::
  32         The list of mailbox files to read patches from. If you do not
  33         supply this argument, the command reads from the standard input.
  34         If you supply directories, they will be treated as Maildirs.
  35
  36 -s::
  37 --signoff::
  38         Add a `Signed-off-by` trailer to the commit message, using
  39         the committer identity of yourself.
  40         See the signoff option in linkgit:git-commit[1] for more information.
  41
  42 -k::
  43 --keep::
  44         Pass `-k` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
  45
  46 --keep-non-patch::
  47         Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
  48
  49 --[no-]keep-cr::
  50         With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1])
  51         with the same option, to prevent it from stripping CR at the end of
  52         lines. `am.keepcr` configuration variable can be used to specify the
  53         default behaviour.  `--no-keep-cr` is useful to override `am.keepcr`.
  54
  55 -c::
  56 --scissors::
  57         Remove everything in body before a scissors line (see
  58         linkgit:git-mailinfo[1]). Can be activated by default using
  59         the `mailinfo.scissors` configuration variable.
  60
  61 --no-scissors::
  62         Ignore scissors lines (see linkgit:git-mailinfo[1]).
  63
  64 --quoted-cr=<action>::
  65         This flag will be passed down to 'git mailinfo' (see linkgit:git-mailinfo[1]).
  66
  67 --empty=(stop|drop|keep)::
  68         By default, or when the option is set to 'stop', the command
  69         errors out on an input e-mail message lacking a patch
  70         and stops into the middle of the current am session. When this
  71         option is set to 'drop', skip such an e-mail message instead.
  72         When this option is set to 'keep', create an empty commit,
  73         recording the contents of the e-mail message as its log.
  74
  75 -m::
  76 --message-id::
  77         Pass the `-m` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]),
  78         so that the Message-ID header is added to the commit message.
  79         The `am.messageid` configuration variable can be used to specify
  80         the default behaviour.
  81
  82 --no-message-id::
  83         Do not add the Message-ID header to the commit message.
  84         `no-message-id` is useful to override `am.messageid`.
  85
  86 -q::
  87 --quiet::
  88         Be quiet. Only print error messages.
  89
  90 -u::
  91 --utf8::
  92         Pass `-u` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
  93         The proposed commit log message taken from the e-mail
  94         is re-coded into UTF-8 encoding (configuration variable
  95         `i18n.commitEncoding` can be used to specify project's
  96         preferred encoding if it is not UTF-8).
  97 +
  98 This was optional in prior versions of git, but now it is the
  99 default.   You can use `--no-utf8` to override this.
 100
 101 --no-utf8::
 102         Pass `-n` flag to 'git mailinfo' (see
 103         linkgit:git-mailinfo[1]).
 104
 105 -3::
 106 --3way::
 107 --no-3way::
 108         When the patch does not apply cleanly, fall back on
 109         3-way merge if the patch records the identity of blobs
 110         it is supposed to apply to and we have those blobs
 111         available locally. `--no-3way` can be used to override
 112         am.threeWay configuration variable. For more information,
 113         see am.threeWay in linkgit:git-config[1].
 114
 115 --rerere-autoupdate::
 116 --no-rerere-autoupdate::
 117         Allow the rerere mechanism to update the index with the
 118         result of auto-conflict resolution if possible.
 119
 120 --ignore-space-change::
 121 --ignore-whitespace::
 122 --whitespace=<option>::
 123 -C<n>::
 124 -p<n>::
 125 --directory=<dir>::
 126 --exclude=<path>::
 127 --include=<path>::
 128 --reject::
 129         These flags are passed to the 'git apply' (see linkgit:git-apply[1])
 130         program that applies
 131         the patch.
 132
 133 --patch-format::
 134         By default the command will try to detect the patch format
 135         automatically. This option allows the user to bypass the automatic
 136         detection and specify the patch format that the patch(es) should be
 137         interpreted as. Valid formats are mbox, mboxrd,
 138         stgit, stgit-series and hg.
 139
 140 -i::
 141 --interactive::
 142         Run interactively.
 143
 144 --committer-date-is-author-date::
 145         By default the command records the date from the e-mail
 146         message as the commit author date, and uses the time of
 147         commit creation as the committer date. This allows the
 148         user to lie about the committer date by using the same
 149         value as the author date.
 150
 151 --ignore-date::
 152         By default the command records the date from the e-mail
 153         message as the commit author date, and uses the time of
 154         commit creation as the committer date. This allows the
 155         user to lie about the author date by using the same
 156         value as the committer date.
 157
 158 --skip::
 159         Skip the current patch.  This is only meaningful when
 160         restarting an aborted patch.
 161
 162 -S[<keyid>]::
 163 --gpg-sign[=<keyid>]::
 164 --no-gpg-sign::
 165         GPG-sign commits. The `keyid` argument is optional and
 166         defaults to the committer identity; if specified, it must be
 167         stuck to the option without a space. `--no-gpg-sign` is useful to
 168         countermand both `commit.gpgSign` configuration variable, and
 169         earlier `--gpg-sign`.
 170
 171 --continue::
 172 -r::
 173 --resolved::
 174         After a patch failure (e.g. attempting to apply
 175         conflicting patch), the user has applied it by hand and
 176         the index file stores the result of the application.
 177         Make a commit using the authorship and commit log
 178         extracted from the e-mail message and the current index
 179         file, and continue.
 180
 181 --resolvemsg=<msg>::
 182         When a patch failure occurs, <msg> will be printed
 183         to the screen before exiting.  This overrides the
 184         standard message informing you to use `--continue`
 185         or `--skip` to handle the failure.  This is solely
 186         for internal use between 'git rebase' and 'git am'.
 187
 188 --abort::
 189         Restore the original branch and abort the patching operation.
 190         Revert contents of files involved in the am operation to their
 191         pre-am state.
 192
 193 --quit::
 194         Abort the patching operation but keep HEAD and the index
 195         untouched.
 196
 197 --show-current-patch[=(diff|raw)]::
 198         Show the message at which `git am` has stopped due to
 199         conflicts.  If `raw` is specified, show the raw contents of
 200         the e-mail message; if `diff`, show the diff portion only.
 201         Defaults to `raw`.
 202
 203 --allow-empty::
 204         After a patch failure on an input e-mail message lacking a patch,
 205         create an empty commit with the contents of the e-mail message
 206         as its log message.
 207
 208 DISCUSSION
 209 ----------
 210
 211 The commit author name is taken from the "From: " line of the
 212 message, and commit author date is taken from the "Date: " line
 213 of the message.  The "Subject: " line is used as the title of
 214 the commit, after stripping common prefix "[PATCH <anything>]".
 215 The "Subject: " line is supposed to concisely describe what the
 216 commit is about in one line of text.
 217
 218 "From: ", "Date: ", and "Subject: " lines starting the body override the
 219 respective commit author name and title values taken from the headers.
 220
 221 The commit message is formed by the title taken from the
 222 "Subject: ", a blank line and the body of the message up to
 223 where the patch begins.  Excess whitespace at the end of each
 224 line is automatically stripped.
 225
 226 The patch is expected to be inline, directly following the
 227 message.  Any line that is of the form:
 228
 229 * three-dashes and end-of-line, or
 230 * a line that begins with "diff -", or
 231 * a line that begins with "Index: "
 232
 233 is taken as the beginning of a patch, and the commit log message
 234 is terminated before the first occurrence of such a line.
 235
 236 When initially invoking `git am`, you give it the names of the mailboxes
 237 to process.  Upon seeing the first patch that does not apply, it
 238 aborts in the middle.  You can recover from this in one of two ways:
 239
 240 . skip the current patch by re-running the command with the `--skip`
 241   option.
 242
 243 . hand resolve the conflict in the working directory, and update
 244   the index file to bring it into a state that the patch should
 245   have produced.  Then run the command with the `--continue` option.
 246
 247 The command refuses to process new mailboxes until the current
 248 operation is finished, so if you decide to start over from scratch,
 249 run `git am --abort` before running the command with mailbox
 250 names.
 251
 252 Before any patches are applied, ORIG_HEAD is set to the tip of the
 253 current branch.  This is useful if you have problems with multiple
 254 commits, like running 'git am' on the wrong branch or an error in the
 255 commits that is more easily fixed by changing the mailbox (e.g.
 256 errors in the "From:" lines).
 257
 258 HOOKS
 259 -----
 260 This command can run `applypatch-msg`, `pre-applypatch`,
 261 and `post-applypatch` hooks.  See linkgit:githooks[5] for more
 262 information.
 263
 264 SEE ALSO
 265 --------
 266 linkgit:git-apply[1].
 267
 268 GIT
 269 ---
 270 Part of the linkgit:git[1] suite