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=<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 include::rerere-options.txt[]
 116
 117 --ignore-space-change::
 118 --ignore-whitespace::
 119 --whitespace=<option>::
 120 -C<n>::
 121 -p<n>::
 122 --directory=<dir>::
 123 --exclude=<path>::
 124 --include=<path>::
 125 --reject::
 126         These flags are passed to the 'git apply' (see linkgit:git-apply[1])
 127         program that applies
 128         the patch.
 129
 130 --patch-format::
 131         By default the command will try to detect the patch format
 132         automatically. This option allows the user to bypass the automatic
 133         detection and specify the patch format that the patch(es) should be
 134         interpreted as. Valid formats are mbox, mboxrd,
 135         stgit, stgit-series and hg.
 136
 137 -i::
 138 --interactive::
 139         Run interactively.
 140
 141 -n::
 142 --no-verify::
 143         By default, the pre-applypatch and applypatch-msg hooks are run.
 144         When any of `--no-verify` or `-n` is given, these are bypassed.
 145         See also linkgit:githooks[5].
 146
 147 --committer-date-is-author-date::
 148         By default the command records the date from the e-mail
 149         message as the commit author date, and uses the time of
 150         commit creation as the committer date. This allows the
 151         user to lie about the committer date by using the same
 152         value as the author date.
 153
 154 --ignore-date::
 155         By default the command records the date from the e-mail
 156         message as the commit author date, and uses the time of
 157         commit creation as the committer date. This allows the
 158         user to lie about the author date by using the same
 159         value as the committer date.
 160
 161 --skip::
 162         Skip the current patch.  This is only meaningful when
 163         restarting an aborted patch.
 164
 165 -S[<keyid>]::
 166 --gpg-sign[=<keyid>]::
 167 --no-gpg-sign::
 168         GPG-sign commits. The `keyid` argument is optional and
 169         defaults to the committer identity; if specified, it must be
 170         stuck to the option without a space. `--no-gpg-sign` is useful to
 171         countermand both `commit.gpgSign` configuration variable, and
 172         earlier `--gpg-sign`.
 173
 174 --continue::
 175 -r::
 176 --resolved::
 177         After a patch failure (e.g. attempting to apply
 178         conflicting patch), the user has applied it by hand and
 179         the index file stores the result of the application.
 180         Make a commit using the authorship and commit log
 181         extracted from the e-mail message and the current index
 182         file, and continue.
 183
 184 --resolvemsg=<msg>::
 185         When a patch failure occurs, <msg> will be printed
 186         to the screen before exiting.  This overrides the
 187         standard message informing you to use `--continue`
 188         or `--skip` to handle the failure.  This is solely
 189         for internal use between 'git rebase' and 'git am'.
 190
 191 --abort::
 192         Restore the original branch and abort the patching operation.
 193         Revert contents of files involved in the am operation to their
 194         pre-am state.
 195
 196 --quit::
 197         Abort the patching operation but keep HEAD and the index
 198         untouched.
 199
 200 --show-current-patch[=(diff|raw)]::
 201         Show the message at which `git am` has stopped due to
 202         conflicts.  If `raw` is specified, show the raw contents of
 203         the e-mail message; if `diff`, show the diff portion only.
 204         Defaults to `raw`.
 205
 206 --allow-empty::
 207         After a patch failure on an input e-mail message lacking a patch,
 208         create an empty commit with the contents of the e-mail message
 209         as its log message.
 210
 211 DISCUSSION
 212 ----------
 213
 214 The commit author name is taken from the "From: " line of the
 215 message, and commit author date is taken from the "Date: " line
 216 of the message.  The "Subject: " line is used as the title of
 217 the commit, after stripping common prefix "[PATCH <anything>]".
 218 The "Subject: " line is supposed to concisely describe what the
 219 commit is about in one line of text.
 220
 221 "From: ", "Date: ", and "Subject: " lines starting the body override the
 222 respective commit author name and title values taken from the headers.
 223
 224 The commit message is formed by the title taken from the
 225 "Subject: ", a blank line and the body of the message up to
 226 where the patch begins.  Excess whitespace at the end of each
 227 line is automatically stripped.
 228
 229 The patch is expected to be inline, directly following the
 230 message.  Any line that is of the form:
 231
 232 * three-dashes and end-of-line, or
 233 * a line that begins with "diff -", or
 234 * a line that begins with "Index: "
 235
 236 is taken as the beginning of a patch, and the commit log message
 237 is terminated before the first occurrence of such a line.
 238
 239 When initially invoking `git am`, you give it the names of the mailboxes
 240 to process.  Upon seeing the first patch that does not apply, it
 241 aborts in the middle.  You can recover from this in one of two ways:
 242
 243 . skip the current patch by re-running the command with the `--skip`
 244   option.
 245
 246 . hand resolve the conflict in the working directory, and update
 247   the index file to bring it into a state that the patch should
 248   have produced.  Then run the command with the `--continue` option.
 249
 250 The command refuses to process new mailboxes until the current
 251 operation is finished, so if you decide to start over from scratch,
 252 run `git am --abort` before running the command with mailbox
 253 names.
 254
 255 Before any patches are applied, ORIG_HEAD is set to the tip of the
 256 current branch.  This is useful if you have problems with multiple
 257 commits, like running 'git am' on the wrong branch or an error in the
 258 commits that is more easily fixed by changing the mailbox (e.g.
 259 errors in the "From:" lines).
 260
 261 HOOKS
 262 -----
 263 This command can run `applypatch-msg`, `pre-applypatch`,
 264 and `post-applypatch` hooks.  See linkgit:githooks[5] for more
 265 information.
 266
 267 CONFIGURATION
 268 -------------
 269
 270 include::includes/cmd-config-section-all.txt[]
 271
 272 include::config/am.txt[]
 273
 274 SEE ALSO
 275 --------
 276 linkgit:git-apply[1].
 277
 278 GIT
 279 ---
 280 Part of the linkgit:git[1] suite