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