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

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