doc/source/en/TortoiseGit/git_doc/git-annotate.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-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> [options] file [revision]</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\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.\r
 154 </simpara>\r
 155 </listitem>\r
 156 </varlistentry>\r
 157 <varlistentry>\r
 158 <term>\r
 159 -p\r
 160 </term>\r
 161 <term>\r
 162 --porcelain\r
 163 </term>\r
 164 <listitem>\r
 165 <simpara>\r
 166         Show in a format designed for machine consumption.\r
 167 </simpara>\r
 168 </listitem>\r
 169 </varlistentry>\r
 170 <varlistentry>\r
 171 <term>\r
 172 --line-porcelain\r
 173 </term>\r
 174 <listitem>\r
 175 <simpara>\r
 176         Show the porcelain format, but output commit information for\r
 177         each line, not just the first time a commit is referenced.\r
 178         Implies --porcelain.\r
 179 </simpara>\r
 180 </listitem>\r
 181 </varlistentry>\r
 182 <varlistentry>\r
 183 <term>\r
 184 --incremental\r
 185 </term>\r
 186 <listitem>\r
 187 <simpara>\r
 188         Show the result incrementally in a format designed for\r
 189         machine consumption.\r
 190 </simpara>\r
 191 </listitem>\r
 192 </varlistentry>\r
 193 <varlistentry>\r
 194 <term>\r
 195 --encoding=&lt;encoding&gt;\r
 196 </term>\r
 197 <listitem>\r
 198 <simpara>\r
 199         Specifies the encoding used to output author names\r
 200         and commit summaries. Setting it to <emphasis>none</emphasis> makes blame\r
 201         output unconverted data. For more information see the\r
 202         discussion about encoding in the <xref linkend="git-log(1)" />\r
 203         manual page.\r
 204 </simpara>\r
 205 </listitem>\r
 206 </varlistentry>\r
 207 <varlistentry>\r
 208 <term>\r
 209 --contents &lt;file&gt;\r
 210 </term>\r
 211 <listitem>\r
 212 <simpara>\r
 213         When &lt;rev&gt; is not specified, the command annotates the\r
 214         changes starting backwards from the working tree copy.\r
 215         This flag makes the command pretend as if the working\r
 216         tree copy has the contents of the named file (specify\r
 217         <emphasis>-</emphasis> to make the command read from the standard input).\r
 218 </simpara>\r
 219 </listitem>\r
 220 </varlistentry>\r
 221 <varlistentry>\r
 222 <term>\r
 223 --date &lt;format&gt;\r
 224 </term>\r
 225 <listitem>\r
 226 <simpara>\r
 227         Specifies the format used to output dates. If --date is not\r
 228         provided, the value of the blame.date config variable is\r
 229         used. If the blame.date config variable is also not set, the\r
 230         iso format is used. For supported values, see the discussion\r
 231         of the --date option at <xref linkend="git-log(1)" />.\r
 232 </simpara>\r
 233 </listitem>\r
 234 </varlistentry>\r
 235 <varlistentry>\r
 236 <term>\r
 237 --[no-]progress\r
 238 </term>\r
 239 <listitem>\r
 240 <simpara>\r
 241         Progress status is reported on the standard error stream\r
 242         by default when it is attached to a terminal. This flag\r
 243         enables progress reporting even if not attached to a\r
 244         terminal. Can't use <emphasis>--progress</emphasis> together with <emphasis>--porcelain</emphasis>\r
 245         or <emphasis>--incremental</emphasis>.\r
 246 </simpara>\r
 247 </listitem>\r
 248 </varlistentry>\r
 249 <varlistentry>\r
 250 <term>\r
 251 -M|&lt;num&gt;|\r
 252 </term>\r
 253 <listitem>\r
 254 <simpara>\r
 255         Detect moved or copied lines within a file. When a commit\r
 256         moves or copies a block of lines (e.g. the original file\r
 257         has A and then B, and the commit changes it to B and then\r
 258         A), the traditional <emphasis>blame</emphasis> algorithm notices only half of\r
 259         the movement and typically blames the lines that were moved\r
 260         up (i.e. B) to the parent and assigns blame to the lines that\r
 261         were moved down (i.e. A) to the child commit.  With this\r
 262         option, both groups of lines are blamed on the parent by\r
 263         running extra passes of inspection.\r
 264 </simpara>\r
 265 <simpara>&lt;num&gt; is optional but it is the lower bound on the number of\r
 266 alphanumeric characters that Git must detect as moving/copying\r
 267 within a file for it to associate those lines with the parent\r
 268 commit. The default value is 20.</simpara>\r
 269 </listitem>\r
 270 </varlistentry>\r
 271 <varlistentry>\r
 272 <term>\r
 273 -C|&lt;num&gt;|\r
 274 </term>\r
 275 <listitem>\r
 276 <simpara>\r
 277         In addition to <emphasis>-M</emphasis>, detect lines moved or copied from other\r
 278         files that were modified in the same commit.  This is\r
 279         useful when you reorganize your program and move code\r
 280         around across files.  When this option is given twice,\r
 281         the command additionally looks for copies from other\r
 282         files in the commit that creates the file. When this\r
 283         option is given three times, the command additionally\r
 284         looks for copies from other files in any commit.\r
 285 </simpara>\r
 286 <simpara>&lt;num&gt; is optional but it is the lower bound on the number of\r
 287 alphanumeric characters that Git must detect as moving/copying\r
 288 between files for it to associate those lines with the parent\r
 289 commit. And the default value is 40. If there are more than one\r
 290 <emphasis>-C</emphasis> options given, the &lt;num&gt; argument of the last <emphasis>-C</emphasis> will\r
 291 take effect.</simpara>\r
 292 </listitem>\r
 293 </varlistentry>\r
 294 <varlistentry>\r
 295 <term>\r
 296 -h\r
 297 </term>\r
 298 <listitem>\r
 299 <simpara>\r
 300         Show help message.\r
 301 </simpara>\r
 302 </listitem>\r
 303 </varlistentry>\r
 304 </variablelist>\r
 305 </simplesect>\r
 306 <simplesect id="git-annotate(1)__see_also">\r
 307 <title>SEE ALSO</title>\r
 308 <simpara><xref linkend="git-blame(1)" /></simpara>\r
 309 </simplesect>\r
 310 <simplesect id="git-annotate(1)__git">\r
 311 <title>GIT</title>\r
 312 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
 313 </simplesect>\r
 314 </sect2>\r