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 | --retry | --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 --retry::
 212         Try to apply the last conflicting patch again. This is generally
 213         only useful for passing extra options to the retry attempt
 214         (e.g., `--3way`), since otherwise you'll just see the same
 215         failure again.
 216
 217 --show-current-patch[=(diff|raw)]::
 218         Show the message at which `git am` has stopped due to
 219         conflicts.  If `raw` is specified, show the raw contents of
 220         the e-mail message; if `diff`, show the diff portion only.
 221         Defaults to `raw`.
 222
 223 --allow-empty::
 224         After a patch failure on an input e-mail message lacking a patch,
 225         create an empty commit with the contents of the e-mail message
 226         as its log message.
 227
 228 DISCUSSION
 229 ----------
 230
 231 The commit author name is taken from the "From: " line of the
 232 message, and commit author date is taken from the "Date: " line
 233 of the message.  The "Subject: " line is used as the title of
 234 the commit, after stripping common prefix "[PATCH <anything>]".
 235 The "Subject: " line is supposed to concisely describe what the
 236 commit is about in one line of text.
 237
 238 "From: ", "Date: ", and "Subject: " lines starting the body override the
 239 respective commit author name and title values taken from the headers.
 240
 241 The commit message is formed by the title taken from the
 242 "Subject: ", a blank line and the body of the message up to
 243 where the patch begins.  Excess whitespace at the end of each
 244 line is automatically stripped.
 245
 246 The patch is expected to be inline, directly following the
 247 message.  Any line that is of the form:
 248
 249 * three-dashes and end-of-line, or
 250 * a line that begins with "diff -", or
 251 * a line that begins with "Index: "
 252
 253 is taken as the beginning of a patch, and the commit log message
 254 is terminated before the first occurrence of such a line.
 255
 256 When initially invoking `git am`, you give it the names of the mailboxes
 257 to process.  Upon seeing the first patch that does not apply, it
 258 aborts in the middle.  You can recover from this in one of two ways:
 259
 260 . skip the current patch by re-running the command with the `--skip`
 261   option.
 262
 263 . hand resolve the conflict in the working directory, and update
 264   the index file to bring it into a state that the patch should
 265   have produced.  Then run the command with the `--continue` option.
 266
 267 The command refuses to process new mailboxes until the current
 268 operation is finished, so if you decide to start over from scratch,
 269 run `git am --abort` before running the command with mailbox
 270 names.
 271
 272 Before any patches are applied, ORIG_HEAD is set to the tip of the
 273 current branch.  This is useful if you have problems with multiple
 274 commits, like running 'git am' on the wrong branch or an error in the
 275 commits that is more easily fixed by changing the mailbox (e.g.
 276 errors in the "From:" lines).
 277
 278 HOOKS
 279 -----
 280 This command can run `applypatch-msg`, `pre-applypatch`,
 281 and `post-applypatch` hooks.  See linkgit:githooks[5] for more
 282 information.
 283
 284 CONFIGURATION
 285 -------------
 286
 287 include::includes/cmd-config-section-all.txt[]
 288
 289 include::config/am.txt[]
 290
 291 SEE ALSO
 292 --------
 293 linkgit:git-apply[1],
 294 linkgit:git-format-patch[1].
 295
 296 GIT
 297 ---
 298 Part of the linkgit:git[1] suite