doc/source/en/TortoiseGit/git_doc/git-am.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">\r
   3 \r
   4 <sect2 lang="en" id="git-am(1)">\r
   5     <title>git-am(1)</title>\r
   6 <indexterm>\r
   7 <primary>git-am(1)</primary>\r
   8 </indexterm>\r
   9 <simplesect id="git-am(1)__name">\r
  10 <title>NAME</title>\r
  11 <simpara>git-am - Apply a series of patches from a mailbox</simpara>\r
  12 </simplesect>\r
  13 <simplesect id="git-am(1)__synopsis">\r
  14 <title>SYNOPSIS</title>\r
  15 <blockquote>\r
  16 <literallayout><emphasis>git am</emphasis> [--signoff] [--keep] [--keep-cr | --no-keep-cr] [--utf8 | --no-utf8]\r
  17          [--3way] [--interactive] [--committer-date-is-author-date]\r
  18          [--ignore-date] [--ignore-space-change | --ignore-whitespace]\r
  19          [--whitespace=&lt;option&gt;] [-C&lt;n&gt;] [-p&lt;n&gt;] [--directory=&lt;dir&gt;]\r
  20          [--exclude=&lt;path&gt;] [--include=&lt;path&gt;] [--reject] [-q | --quiet]\r
  21          [--scissors | --no-scissors]\r
  22          [(&lt;mbox&gt; | &lt;Maildir&gt;)&#8230;]\r
  23 <emphasis>git am</emphasis> (--continue | --skip | --abort)</literallayout>\r
  24 </blockquote>\r
  25 </simplesect>\r
  26 <simplesect id="git-am(1)__description">\r
  27 <title>DESCRIPTION</title>\r
  28 <simpara>Splits mail messages in a mailbox into commit log message,\r
  29 authorship information and patches, and applies them to the\r
  30 current branch.</simpara>\r
  31 </simplesect>\r
  32 <simplesect id="git-am(1)__options">\r
  33 <title>OPTIONS</title>\r
  34 <variablelist>\r
  35 <varlistentry>\r
  36 <term>\r
  37 (&lt;mbox&gt;|&lt;Maildir&gt;)&#8230;\r
  38 </term>\r
  39 <listitem>\r
  40 <simpara>\r
  41         The list of mailbox files to read patches from. If you do not\r
  42         supply this argument, the command reads from the standard input.\r
  43         If you supply directories, they will be treated as Maildirs.\r
  44 </simpara>\r
  45 </listitem>\r
  46 </varlistentry>\r
  47 <varlistentry>\r
  48 <term>\r
  49 -s\r
  50 </term>\r
  51 <term>\r
  52 --signoff\r
  53 </term>\r
  54 <listitem>\r
  55 <simpara>\r
  56         Add a <emphasis>Signed-off-by:</emphasis> line to the commit message, using\r
  57         the committer identity of yourself.\r
  58 </simpara>\r
  59 </listitem>\r
  60 </varlistentry>\r
  61 <varlistentry>\r
  62 <term>\r
  63 -k\r
  64 </term>\r
  65 <term>\r
  66 --keep\r
  67 </term>\r
  68 <listitem>\r
  69 <simpara>\r
  70         Pass <emphasis>-k</emphasis> flag to <emphasis>git mailinfo</emphasis> (see <xref linkend="git-mailinfo(1)" />).\r
  71 </simpara>\r
  72 </listitem>\r
  73 </varlistentry>\r
  74 <varlistentry>\r
  75 <term>\r
  76 --keep-non-patch\r
  77 </term>\r
  78 <listitem>\r
  79 <simpara>\r
  80         Pass <emphasis>-b</emphasis> flag to <emphasis>git mailinfo</emphasis> (see <xref linkend="git-mailinfo(1)" />).\r
  81 </simpara>\r
  82 </listitem>\r
  83 </varlistentry>\r
  84 <varlistentry>\r
  85 <term>\r
  86 --keep-cr\r
  87 </term>\r
  88 <term>\r
  89 --no-keep-cr\r
  90 </term>\r
  91 <listitem>\r
  92 <simpara>\r
  93         With <emphasis>--keep-cr</emphasis>, call <emphasis>git mailsplit</emphasis> (see <xref linkend="git-mailsplit(1)" />)\r
  94         with the same option, to prevent it from stripping CR at the end of\r
  95         lines. <emphasis>am.keepcr</emphasis> configuration variable can be used to specify the\r
  96         default behaviour.  <emphasis>--no-keep-cr</emphasis> is useful to override <emphasis>am.keepcr</emphasis>.\r
  97 </simpara>\r
  98 </listitem>\r
  99 </varlistentry>\r
 100 <varlistentry>\r
 101 <term>\r
 102 -c\r
 103 </term>\r
 104 <term>\r
 105 --scissors\r
 106 </term>\r
 107 <listitem>\r
 108 <simpara>\r
 109         Remove everything in body before a scissors line (see\r
 110         <xref linkend="git-mailinfo(1)" />).\r
 111 </simpara>\r
 112 </listitem>\r
 113 </varlistentry>\r
 114 <varlistentry>\r
 115 <term>\r
 116 --no-scissors\r
 117 </term>\r
 118 <listitem>\r
 119 <simpara>\r
 120         Ignore scissors lines (see <xref linkend="git-mailinfo(1)" />).\r
 121 </simpara>\r
 122 </listitem>\r
 123 </varlistentry>\r
 124 <varlistentry>\r
 125 <term>\r
 126 -q\r
 127 </term>\r
 128 <term>\r
 129 --quiet\r
 130 </term>\r
 131 <listitem>\r
 132 <simpara>\r
 133         Be quiet. Only print error messages.\r
 134 </simpara>\r
 135 </listitem>\r
 136 </varlistentry>\r
 137 <varlistentry>\r
 138 <term>\r
 139 -u\r
 140 </term>\r
 141 <term>\r
 142 --utf8\r
 143 </term>\r
 144 <listitem>\r
 145 <simpara>\r
 146         Pass <emphasis>-u</emphasis> flag to <emphasis>git mailinfo</emphasis> (see <xref linkend="git-mailinfo(1)" />).\r
 147         The proposed commit log message taken from the e-mail\r
 148         is re-coded into UTF-8 encoding (configuration variable\r
 149         <emphasis>i18n.commitencoding</emphasis> can be used to specify project's\r
 150         preferred encoding if it is not UTF-8).\r
 151 </simpara>\r
 152 <simpara>This was optional in prior versions of git, but now it is the\r
 153 default.   You can use <emphasis>--no-utf8</emphasis> to override this.</simpara>\r
 154 </listitem>\r
 155 </varlistentry>\r
 156 <varlistentry>\r
 157 <term>\r
 158 --no-utf8\r
 159 </term>\r
 160 <listitem>\r
 161 <simpara>\r
 162         Pass <emphasis>-n</emphasis> flag to <emphasis>git mailinfo</emphasis> (see\r
 163         <xref linkend="git-mailinfo(1)" />).\r
 164 </simpara>\r
 165 </listitem>\r
 166 </varlistentry>\r
 167 <varlistentry>\r
 168 <term>\r
 169 -3\r
 170 </term>\r
 171 <term>\r
 172 --3way\r
 173 </term>\r
 174 <listitem>\r
 175 <simpara>\r
 176         When the patch does not apply cleanly, fall back on\r
 177         3-way merge if the patch records the identity of blobs\r
 178         it is supposed to apply to and we have those blobs\r
 179         available locally.\r
 180 </simpara>\r
 181 </listitem>\r
 182 </varlistentry>\r
 183 <varlistentry>\r
 184 <term>\r
 185 --ignore-date\r
 186 </term>\r
 187 <term>\r
 188 --ignore-space-change\r
 189 </term>\r
 190 <term>\r
 191 --ignore-whitespace\r
 192 </term>\r
 193 <term>\r
 194 --whitespace=&lt;option&gt;\r
 195 </term>\r
 196 <term>\r
 197 -C&lt;n&gt;\r
 198 </term>\r
 199 <term>\r
 200 -p&lt;n&gt;\r
 201 </term>\r
 202 <term>\r
 203 --directory=&lt;dir&gt;\r
 204 </term>\r
 205 <term>\r
 206 --exclude=&lt;path&gt;\r
 207 </term>\r
 208 <term>\r
 209 --include=&lt;path&gt;\r
 210 </term>\r
 211 <term>\r
 212 --reject\r
 213 </term>\r
 214 <listitem>\r
 215 <simpara>\r
 216         These flags are passed to the <emphasis>git apply</emphasis> (see <xref linkend="git-apply(1)" />)\r
 217         program that applies\r
 218         the patch.\r
 219 </simpara>\r
 220 </listitem>\r
 221 </varlistentry>\r
 222 <varlistentry>\r
 223 <term>\r
 224 -i\r
 225 </term>\r
 226 <term>\r
 227 --interactive\r
 228 </term>\r
 229 <listitem>\r
 230 <simpara>\r
 231         Run interactively.\r
 232 </simpara>\r
 233 </listitem>\r
 234 </varlistentry>\r
 235 <varlistentry>\r
 236 <term>\r
 237 --committer-date-is-author-date\r
 238 </term>\r
 239 <listitem>\r
 240 <simpara>\r
 241         By default the command records the date from the e-mail\r
 242         message as the commit author date, and uses the time of\r
 243         commit creation as the committer date. This allows the\r
 244         user to lie about the committer date by using the same\r
 245         value as the author date.\r
 246 </simpara>\r
 247 </listitem>\r
 248 </varlistentry>\r
 249 <varlistentry>\r
 250 <term>\r
 251 --ignore-date\r
 252 </term>\r
 253 <listitem>\r
 254 <simpara>\r
 255         By default the command records the date from the e-mail\r
 256         message as the commit author date, and uses the time of\r
 257         commit creation as the committer date. This allows the\r
 258         user to lie about the author date by using the same\r
 259         value as the committer date.\r
 260 </simpara>\r
 261 </listitem>\r
 262 </varlistentry>\r
 263 <varlistentry>\r
 264 <term>\r
 265 --skip\r
 266 </term>\r
 267 <listitem>\r
 268 <simpara>\r
 269         Skip the current patch.  This is only meaningful when\r
 270         restarting an aborted patch.\r
 271 </simpara>\r
 272 </listitem>\r
 273 </varlistentry>\r
 274 <varlistentry>\r
 275 <term>\r
 276 --continue\r
 277 </term>\r
 278 <term>\r
 279 -r\r
 280 </term>\r
 281 <term>\r
 282 --resolved\r
 283 </term>\r
 284 <listitem>\r
 285 <simpara>\r
 286         After a patch failure (e.g. attempting to apply\r
 287         conflicting patch), the user has applied it by hand and\r
 288         the index file stores the result of the application.\r
 289         Make a commit using the authorship and commit log\r
 290         extracted from the e-mail message and the current index\r
 291         file, and continue.\r
 292 </simpara>\r
 293 </listitem>\r
 294 </varlistentry>\r
 295 <varlistentry>\r
 296 <term>\r
 297 --resolvemsg=&lt;msg&gt;\r
 298 </term>\r
 299 <listitem>\r
 300 <simpara>\r
 301         When a patch failure occurs, &lt;msg&gt; will be printed\r
 302         to the screen before exiting.  This overrides the\r
 303         standard message informing you to use <emphasis>--resolved</emphasis>\r
 304         or <emphasis>--skip</emphasis> to handle the failure.  This is solely\r
 305         for internal use between <emphasis>git rebase</emphasis> and <emphasis>git am</emphasis>.\r
 306 </simpara>\r
 307 </listitem>\r
 308 </varlistentry>\r
 309 <varlistentry>\r
 310 <term>\r
 311 --abort\r
 312 </term>\r
 313 <listitem>\r
 314 <simpara>\r
 315         Restore the original branch and abort the patching operation.\r
 316 </simpara>\r
 317 </listitem>\r
 318 </varlistentry>\r
 319 </variablelist>\r
 320 </simplesect>\r
 321 <simplesect id="git-am(1)__discussion">\r
 322 <title>DISCUSSION</title>\r
 323 <simpara>The commit author name is taken from the "From: " line of the\r
 324 message, and commit author date is taken from the "Date: " line\r
 325 of the message.  The "Subject: " line is used as the title of\r
 326 the commit, after stripping common prefix "[PATCH &lt;anything&gt;]".\r
 327 The "Subject: " line is supposed to concisely describe what the\r
 328 commit is about in one line of text.</simpara>\r
 329 <simpara>"From: " and "Subject: " lines starting the body override the respective\r
 330 commit author name and title values taken from the headers.</simpara>\r
 331 <simpara>The commit message is formed by the title taken from the\r
 332 "Subject: ", a blank line and the body of the message up to\r
 333 where the patch begins.  Excess whitespace at the end of each\r
 334 line is automatically stripped.</simpara>\r
 335 <simpara>The patch is expected to be inline, directly following the\r
 336 message.  Any line that is of the form:</simpara>\r
 337 <itemizedlist>\r
 338 <listitem>\r
 339 <simpara>\r
 340 three-dashes and end-of-line, or\r
 341 </simpara>\r
 342 </listitem>\r
 343 <listitem>\r
 344 <simpara>\r
 345 a line that begins with "diff -", or\r
 346 </simpara>\r
 347 </listitem>\r
 348 <listitem>\r
 349 <simpara>\r
 350 a line that begins with "Index: "\r
 351 </simpara>\r
 352 </listitem>\r
 353 </itemizedlist>\r
 354 <simpara>is taken as the beginning of a patch, and the commit log message\r
 355 is terminated before the first occurrence of such a line.</simpara>\r
 356 <simpara>When initially invoking <emphasis>git am</emphasis>, you give it the names of the mailboxes\r
 357 to process.  Upon seeing the first patch that does not apply, it\r
 358 aborts in the middle.  You can recover from this in one of two ways:</simpara>\r
 359 <orderedlist numeration="arabic">\r
 360 <listitem>\r
 361 <simpara>\r
 362 skip the current patch by re-running the command with the <emphasis>--skip</emphasis>\r
 363   option.\r
 364 </simpara>\r
 365 </listitem>\r
 366 <listitem>\r
 367 <simpara>\r
 368 hand resolve the conflict in the working directory, and update\r
 369   the index file to bring it into a state that the patch should\r
 370   have produced.  Then run the command with the <emphasis>--resolved</emphasis> option.\r
 371 </simpara>\r
 372 </listitem>\r
 373 </orderedlist>\r
 374 <simpara>The command refuses to process new mailboxes until the current\r
 375 operation is finished, so if you decide to start over from scratch,\r
 376 run <emphasis>git am --abort</emphasis> before running the command with mailbox\r
 377 names.</simpara>\r
 378 <simpara>Before any patches are applied, ORIG_HEAD is set to the tip of the\r
 379 current branch.  This is useful if you have problems with multiple\r
 380 commits, like running <emphasis>git am</emphasis> on the wrong branch or an error in the\r
 381 commits that is more easily fixed by changing the mailbox (e.g.\r
 382 errors in the "From:" lines).</simpara>\r
 383 </simplesect>\r
 384 <simplesect id="git-am(1)__see_also">\r
 385 <title>SEE ALSO</title>\r
 386 <simpara><xref linkend="git-apply(1)" />.</simpara>\r
 387 </simplesect>\r
 388 <simplesect id="git-am(1)__git">\r
 389 <title>GIT</title>\r
 390 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
 391 </simplesect>\r
 392 </sect2>\r