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

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.dtd">\r
   3 \r
   4 <sect2 lang="en" id="git-annotate(1)">\r
   5     <title>git-annotate(1)</title>\r
   6 <indexterm>\r
   7 <primary>git-annotate(1)</primary>\r
   8 </indexterm>\r
   9 <simplesect id="git-annotate(1)__name">\r
  10 <title>NAME</title>\r
  11 <simpara>git-annotate - Annotate file lines with commit information</simpara>\r
  12 </simplesect>\r
  13 <simplesect id="git-annotate(1)__synopsis">\r
  14 <title>SYNOPSIS</title>\r
  15 <blockquote>\r
  16 <literallayout><emphasis>git annotate</emphasis> [&lt;options&gt;] &lt;file&gt; [&lt;revision&gt;]</literallayout>\r
  17 </blockquote>\r
  18 </simplesect>\r
  19 <simplesect id="git-annotate(1)__description">\r
  20 <title>DESCRIPTION</title>\r
  21 <simpara>Annotates each line in the given file with information from the commit\r
  22 which introduced the line. Optionally annotates from a given revision.</simpara>\r
  23 <simpara>The only difference between this command and <xref linkend="git-blame(1)" /> is that\r
  24 they use slightly different output formats, and this command exists only\r
  25 for backward compatibility to support existing scripts, and provide a more\r
  26 familiar command name for people coming from other SCM systems.</simpara>\r
  27 </simplesect>\r
  28 <simplesect id="git-annotate(1)__options">\r
  29 <title>OPTIONS</title>\r
  30 <variablelist>\r
  31 <varlistentry>\r
  32 <term>\r
  33 -b\r
  34 </term>\r
  35 <listitem>\r
  36 <simpara>\r
  37         Show blank SHA-1 for boundary commits.  This can also\r
  38         be controlled via the <emphasis>blame.blankboundary</emphasis> config option.\r
  39 </simpara>\r
  40 </listitem>\r
  41 </varlistentry>\r
  42 <varlistentry>\r
  43 <term>\r
  44 --root\r
  45 </term>\r
  46 <listitem>\r
  47 <simpara>\r
  48         Do not treat root commits as boundaries.  This can also be\r
  49         controlled via the <emphasis>blame.showRoot</emphasis> config option.\r
  50 </simpara>\r
  51 </listitem>\r
  52 </varlistentry>\r
  53 <varlistentry>\r
  54 <term>\r
  55 --show-stats\r
  56 </term>\r
  57 <listitem>\r
  58 <simpara>\r
  59         Include additional statistics at the end of blame output.\r
  60 </simpara>\r
  61 </listitem>\r
  62 </varlistentry>\r
  63 <varlistentry>\r
  64 <term>\r
  65 -L &lt;start&gt;,&lt;end&gt;\r
  66 </term>\r
  67 <term>\r
  68 -L :&lt;funcname&gt;\r
  69 </term>\r
  70 <listitem>\r
  71 <simpara>\r
  72         Annotate only the given line range. May be specified multiple times.\r
  73         Overlapping ranges are allowed.\r
  74 </simpara>\r
  75 <simpara>&lt;start&gt; and &lt;end&gt; are optional. -L &lt;start&gt; or -L &lt;start&gt;, spans from\r
  76 &lt;start&gt; to end of file. -L ,&lt;end&gt; spans from start of file to &lt;end&gt;.</simpara>\r
  77 <simpara>&lt;start&gt; and &lt;end&gt; can take one of these forms:</simpara>\r
  78 <itemizedlist>\r
  79 <listitem>\r
  80 <simpara>\r
  81 number\r
  82 </simpara>\r
  83 <simpara>If &lt;start&gt; or &lt;end&gt; is a number, it specifies an\r
  84 absolute line number (lines count from 1).</simpara>\r
  85 </listitem>\r
  86 <listitem>\r
  87 <simpara>\r
  88 /regex/\r
  89 </simpara>\r
  90 <simpara>This form will use the first line matching the given\r
  91 POSIX regex. If &lt;start&gt; is a regex, it will search from the end of\r
  92 the previous <emphasis>-L</emphasis> range, if any, otherwise from the start of file.\r
  93 If &lt;start&gt; is ^/regex/, it will search from the start of file.\r
  94 If &lt;end&gt; is a regex, it will search\r
  95 starting at the line given by &lt;start&gt;.</simpara>\r
  96 </listitem>\r
  97 <listitem>\r
  98 <simpara>\r
  99 +offset or -offset\r
 100 </simpara>\r
 101 <simpara>This is only valid for &lt;end&gt; and will specify a number\r
 102 of lines before or after the line given by &lt;start&gt;.</simpara>\r
 103 </listitem>\r
 104 </itemizedlist>\r
 105 <simpara>If :&lt;funcname&gt; is given in place of &lt;start&gt; and &lt;end&gt;, it is a\r
 106 regular expression that denotes the range from the first funcname line\r
 107 that matches &lt;funcname&gt;, up to the next funcname line. :&lt;funcname&gt;\r
 108 searches from the end of the previous <emphasis>-L</emphasis> range, if any, otherwise\r
 109 from the start of file. ^:&lt;funcname&gt; searches from the start of\r
 110 file.</simpara>\r
 111 </listitem>\r
 112 </varlistentry>\r
 113 <varlistentry>\r
 114 <term>\r
 115 -l\r
 116 </term>\r
 117 <listitem>\r
 118 <simpara>\r
 119         Show long rev (Default: off).\r
 120 </simpara>\r
 121 </listitem>\r
 122 </varlistentry>\r
 123 <varlistentry>\r
 124 <term>\r
 125 -t\r
 126 </term>\r
 127 <listitem>\r
 128 <simpara>\r
 129         Show raw timestamp (Default: off).\r
 130 </simpara>\r
 131 </listitem>\r
 132 </varlistentry>\r
 133 <varlistentry>\r
 134 <term>\r
 135 -S &lt;revs-file&gt;\r
 136 </term>\r
 137 <listitem>\r
 138 <simpara>\r
 139         Use revisions from revs-file instead of calling <xref linkend="git-rev-list(1)" />.\r
 140 </simpara>\r
 141 </listitem>\r
 142 </varlistentry>\r
 143 <varlistentry>\r
 144 <term>\r
 145 --reverse &lt;rev&gt;..&lt;rev&gt;\r
 146 </term>\r
 147 <listitem>\r
 148 <simpara>\r
 149         Walk history forward instead of backward. Instead of showing\r
 150         the revision in which a line appeared, this shows the last\r
 151         revision in which a line has existed. This requires a range of\r
 152         revision like START..END where the path to blame exists in\r
 153         START.  <emphasis>git blame --reverse START</emphasis> is taken as <emphasis>git blame\r
 154         --reverse START..HEAD</emphasis> for convenience.\r
 155 </simpara>\r
 156 </listitem>\r
 157 </varlistentry>\r
 158 <varlistentry>\r
 159 <term>\r
 160 -p\r
 161 </term>\r
 162 <term>\r
 163 --porcelain\r
 164 </term>\r
 165 <listitem>\r
 166 <simpara>\r
 167         Show in a format designed for machine consumption.\r
 168 </simpara>\r
 169 </listitem>\r
 170 </varlistentry>\r
 171 <varlistentry>\r
 172 <term>\r
 173 --line-porcelain\r
 174 </term>\r
 175 <listitem>\r
 176 <simpara>\r
 177         Show the porcelain format, but output commit information for\r
 178         each line, not just the first time a commit is referenced.\r
 179         Implies --porcelain.\r
 180 </simpara>\r
 181 </listitem>\r
 182 </varlistentry>\r
 183 <varlistentry>\r
 184 <term>\r
 185 --incremental\r
 186 </term>\r
 187 <listitem>\r
 188 <simpara>\r
 189         Show the result incrementally in a format designed for\r
 190         machine consumption.\r
 191 </simpara>\r
 192 </listitem>\r
 193 </varlistentry>\r
 194 <varlistentry>\r
 195 <term>\r
 196 --encoding=&lt;encoding&gt;\r
 197 </term>\r
 198 <listitem>\r
 199 <simpara>\r
 200         Specifies the encoding used to output author names\r
 201         and commit summaries. Setting it to <emphasis>none</emphasis> makes blame\r
 202         output unconverted data. For more information see the\r
 203         discussion about encoding in the <xref linkend="git-log(1)" />\r
 204         manual page.\r
 205 </simpara>\r
 206 </listitem>\r
 207 </varlistentry>\r
 208 <varlistentry>\r
 209 <term>\r
 210 --contents &lt;file&gt;\r
 211 </term>\r
 212 <listitem>\r
 213 <simpara>\r
 214         When &lt;rev&gt; is not specified, the command annotates the\r
 215         changes starting backwards from the working tree copy.\r
 216         This flag makes the command pretend as if the working\r
 217         tree copy has the contents of the named file (specify\r
 218         <emphasis>-</emphasis> to make the command read from the standard input).\r
 219 </simpara>\r
 220 </listitem>\r
 221 </varlistentry>\r
 222 <varlistentry>\r
 223 <term>\r
 224 --date &lt;format&gt;\r
 225 </term>\r
 226 <listitem>\r
 227 <simpara>\r
 228         Specifies the format used to output dates. If --date is not\r
 229         provided, the value of the blame.date config variable is\r
 230         used. If the blame.date config variable is also not set, the\r
 231         iso format is used. For supported values, see the discussion\r
 232         of the --date option at <xref linkend="git-log(1)" />.\r
 233 </simpara>\r
 234 </listitem>\r
 235 </varlistentry>\r
 236 <varlistentry>\r
 237 <term>\r
 238 --[no-]progress\r
 239 </term>\r
 240 <listitem>\r
 241 <simpara>\r
 242         Progress status is reported on the standard error stream\r
 243         by default when it is attached to a terminal. This flag\r
 244         enables progress reporting even if not attached to a\r
 245         terminal. Can't use <emphasis>--progress</emphasis> together with <emphasis>--porcelain</emphasis>\r
 246         or <emphasis>--incremental</emphasis>.\r
 247 </simpara>\r
 248 </listitem>\r
 249 </varlistentry>\r
 250 <varlistentry>\r
 251 <term>\r
 252 -M[&lt;num&gt;]\r
 253 </term>\r
 254 <listitem>\r
 255 <simpara>\r
 256         Detect moved or copied lines within a file. When a commit\r
 257         moves or copies a block of lines (e.g. the original file\r
 258         has A and then B, and the commit changes it to B and then\r
 259         A), the traditional <emphasis>blame</emphasis> algorithm notices only half of\r
 260         the movement and typically blames the lines that were moved\r
 261         up (i.e. B) to the parent and assigns blame to the lines that\r
 262         were moved down (i.e. A) to the child commit.  With this\r
 263         option, both groups of lines are blamed on the parent by\r
 264         running extra passes of inspection.\r
 265 </simpara>\r
 266 <simpara>&lt;num&gt; is optional but it is the lower bound on the number of\r
 267 alphanumeric characters that Git must detect as moving/copying\r
 268 within a file for it to associate those lines with the parent\r
 269 commit. The default value is 20.</simpara>\r
 270 </listitem>\r
 271 </varlistentry>\r
 272 <varlistentry>\r
 273 <term>\r
 274 -C[&lt;num&gt;]\r
 275 </term>\r
 276 <listitem>\r
 277 <simpara>\r
 278         In addition to <emphasis>-M</emphasis>, detect lines moved or copied from other\r
 279         files that were modified in the same commit.  This is\r
 280         useful when you reorganize your program and move code\r
 281         around across files.  When this option is given twice,\r
 282         the command additionally looks for copies from other\r
 283         files in the commit that creates the file. When this\r
 284         option is given three times, the command additionally\r
 285         looks for copies from other files in any commit.\r
 286 </simpara>\r
 287 <simpara>&lt;num&gt; is optional but it is the lower bound on the number of\r
 288 alphanumeric characters that Git must detect as moving/copying\r
 289 between files for it to associate those lines with the parent\r
 290 commit. And the default value is 40. If there are more than one\r
 291 <emphasis>-C</emphasis> options given, the &lt;num&gt; argument of the last <emphasis>-C</emphasis> will\r
 292 take effect.</simpara>\r
 293 </listitem>\r
 294 </varlistentry>\r
 295 <varlistentry>\r
 296 <term>\r
 297 --ignore-rev &lt;rev&gt;\r
 298 </term>\r
 299 <listitem>\r
 300 <simpara>\r
 301         Ignore changes made by the revision when assigning blame, as if the\r
 302         change never happened.  Lines that were changed or added by an ignored\r
 303         commit will be blamed on the previous commit that changed that line or\r
 304         nearby lines.  This option may be specified multiple times to ignore\r
 305         more than one revision.  If the <emphasis>blame.markIgnoredLines</emphasis> config option\r
 306         is set, then lines that were changed by an ignored commit and attributed to\r
 307         another commit will be marked with a <emphasis>?</emphasis> in the blame output.  If the\r
 308         <emphasis>blame.markUnblamableLines</emphasis> config option is set, then those lines touched\r
 309         by an ignored commit that we could not attribute to another revision are\r
 310         marked with a <emphasis>*</emphasis>.\r
 311 </simpara>\r
 312 </listitem>\r
 313 </varlistentry>\r
 314 <varlistentry>\r
 315 <term>\r
 316 --ignore-revs-file &lt;file&gt;\r
 317 </term>\r
 318 <listitem>\r
 319 <simpara>\r
 320         Ignore revisions listed in <emphasis>file</emphasis>, which must be in the same format as an\r
 321         <emphasis>fsck.skipList</emphasis>.  This option may be repeated, and these files will be\r
 322         processed after any files specified with the <emphasis>blame.ignoreRevsFile</emphasis> config\r
 323         option.  An empty file name, <emphasis>""</emphasis>, will clear the list of revs from\r
 324         previously processed files.\r
 325 </simpara>\r
 326 </listitem>\r
 327 </varlistentry>\r
 328 <varlistentry>\r
 329 <term>\r
 330 -h\r
 331 </term>\r
 332 <listitem>\r
 333 <simpara>\r
 334         Show help message.\r
 335 </simpara>\r
 336 </listitem>\r
 337 </varlistentry>\r
 338 </variablelist>\r
 339 </simplesect>\r
 340 <simplesect id="git-annotate(1)__see_also">\r
 341 <title>SEE ALSO</title>\r
 342 <simpara><xref linkend="git-blame(1)" /></simpara>\r
 343 </simplesect>\r
 344 <simplesect id="git-annotate(1)__git">\r
 345 <title>GIT</title>\r
 346 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
 347 </simplesect>\r
 348 </sect2>\r