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