doc/source/en/TortoiseGit/git_doc/git-shortlog.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-shortlog(1)">\r
   5 <articleinfo>\r
   6     <title>git-shortlog(1)</title>\r
   7 <indexterm>\r
   8 <primary>git-shortlog(1)</primary>\r
   9 </indexterm>\r
  10 </articleinfo>\r
  11 <simplesect id="_name">\r
  12 <title>NAME</title>\r
  13 <simpara>git-shortlog - Summarize <emphasis>git log</emphasis> output</simpara>\r
  14 </simplesect>\r
  15 <simplesect id="_synopsis">\r
  16 <title>SYNOPSIS</title>\r
  17 <blockquote>\r
  18 <literallayout>git log --pretty=short | <emphasis>git shortlog</emphasis> [-h] [-n] [-s] [-e] [-w]\r
  19 <emphasis>git shortlog</emphasis> [-n|--numbered] [-s|--summary] [-e|--email] [-w[&lt;width&gt;[,&lt;indent1&gt;[,&lt;indent2&gt;]]]] &lt;commit&gt;&#8230;</literallayout>\r
  20 </blockquote>\r
  21 </simplesect>\r
  22 <simplesect id="_description">\r
  23 <title>DESCRIPTION</title>\r
  24 <simpara>Summarizes <emphasis>git log</emphasis> output in a format suitable for inclusion\r
  25 in release announcements. Each commit will be grouped by author and\r
  26 the first line of the commit message will be shown.</simpara>\r
  27 <simpara>Additionally, "[PATCH]" will be stripped from the commit description.</simpara>\r
  28 <simpara>If no revisions are passed on the command line and either standard input\r
  29 is not a terminal or there is no current branch, <emphasis>git shortlog</emphasis> will\r
  30 output a summary of the log read from standard input, without\r
  31 reference to the current repository.</simpara>\r
  32 </simplesect>\r
  33 <simplesect id="_options">\r
  34 <title>OPTIONS</title>\r
  35 <variablelist>\r
  36 <varlistentry>\r
  37 <term>\r
  38 -h\r
  39 </term>\r
  40 <term>\r
  41 --help\r
  42 </term>\r
  43 <listitem>\r
  44 <simpara>\r
  45         Print a short usage message and exit.\r
  46 </simpara>\r
  47 </listitem>\r
  48 </varlistentry>\r
  49 <varlistentry>\r
  50 <term>\r
  51 -n\r
  52 </term>\r
  53 <term>\r
  54 --numbered\r
  55 </term>\r
  56 <listitem>\r
  57 <simpara>\r
  58         Sort output according to the number of commits per author instead\r
  59         of author alphabetic order.\r
  60 </simpara>\r
  61 </listitem>\r
  62 </varlistentry>\r
  63 <varlistentry>\r
  64 <term>\r
  65 -s\r
  66 </term>\r
  67 <term>\r
  68 --summary\r
  69 </term>\r
  70 <listitem>\r
  71 <simpara>\r
  72         Suppress commit description and provide a commit count summary only.\r
  73 </simpara>\r
  74 </listitem>\r
  75 </varlistentry>\r
  76 <varlistentry>\r
  77 <term>\r
  78 -e\r
  79 </term>\r
  80 <term>\r
  81 --email\r
  82 </term>\r
  83 <listitem>\r
  84 <simpara>\r
  85         Show the email address of each author.\r
  86 </simpara>\r
  87 </listitem>\r
  88 </varlistentry>\r
  89 <varlistentry>\r
  90 <term>\r
  91 --format[=&lt;format&gt;]\r
  92 </term>\r
  93 <listitem>\r
  94 <simpara>\r
  95         Instead of the commit subject, use some other information to\r
  96         describe each commit.  <emphasis>&lt;format&gt;</emphasis> can be any string accepted\r
  97         by the <emphasis>--format</emphasis> option of <emphasis>git log</emphasis>, such as <emphasis>* [%h] %s</emphasis>.\r
  98         (See the "PRETTY FORMATS" section of <xref linkend="git-log(1)" />.)\r
  99 </simpara>\r
 100 <literallayout class="monospaced">Each pretty-printed commit will be rewrapped before it is shown.</literallayout>\r
 101 </listitem>\r
 102 </varlistentry>\r
 103 <varlistentry>\r
 104 <term>\r
 105 -w[&lt;width&gt;[,&lt;indent1&gt;[,&lt;indent2&gt;]]]\r
 106 </term>\r
 107 <listitem>\r
 108 <simpara>\r
 109         Linewrap the output by wrapping each line at <emphasis>width</emphasis>.  The first\r
 110         line of each entry is indented by <emphasis>indent1</emphasis> spaces, and the second\r
 111         and subsequent lines are indented by <emphasis>indent2</emphasis> spaces. <emphasis>width</emphasis>,\r
 112         <emphasis>indent1</emphasis>, and <emphasis>indent2</emphasis> default to 76, 6 and 9 respectively.\r
 113 </simpara>\r
 114 </listitem>\r
 115 </varlistentry>\r
 116 </variablelist>\r
 117 </simplesect>\r
 118 <simplesect id="_mapping_authors">\r
 119 <title>MAPPING AUTHORS</title>\r
 120 <simpara>The <emphasis>.mailmap</emphasis> feature is used to coalesce together commits by the same\r
 121 person in the shortlog, where their name and/or email address was\r
 122 spelled differently.</simpara>\r
 123 <simpara>If the file <emphasis>.mailmap</emphasis> exists at the toplevel of the repository, or at\r
 124 the location pointed to by the mailmap.file configuration option, it\r
 125 is used to map author and committer names and email addresses to\r
 126 canonical real names and email addresses.</simpara>\r
 127 <simpara>In the simple form, each line in the file consists of the canonical\r
 128 real name of an author, whitespace, and an email address used in the\r
 129 commit (enclosed by <emphasis>&lt;</emphasis> and <emphasis>&gt;</emphasis>) to map to the name. For example:</simpara>\r
 130 <literallayout class="monospaced">Proper Name &lt;commit@email.xx&gt;</literallayout>\r
 131 <simpara>The more complex forms are:</simpara>\r
 132 <literallayout class="monospaced">&lt;proper@email.xx&gt; &lt;commit@email.xx&gt;</literallayout>\r
 133 <simpara>which allows mailmap to replace only the email part of a commit, and:</simpara>\r
 134 <literallayout class="monospaced">Proper Name &lt;proper@email.xx&gt; &lt;commit@email.xx&gt;</literallayout>\r
 135 <simpara>which allows mailmap to replace both the name and the email of a\r
 136 commit matching the specified commit email address, and:</simpara>\r
 137 <literallayout class="monospaced">Proper Name &lt;proper@email.xx&gt; Commit Name &lt;commit@email.xx&gt;</literallayout>\r
 138 <simpara>which allows mailmap to replace both the name and the email of a\r
 139 commit matching both the specified commit name and email address.</simpara>\r
 140 <simpara>Example 1: Your history contains commits by two authors, Jane\r
 141 and Joe, whose names appear in the repository under several forms:</simpara>\r
 142 <screen>Joe Developer &lt;joe@example.com&gt;\r
 143 Joe R. Developer &lt;joe@example.com&gt;\r
 144 Jane Doe &lt;jane@example.com&gt;\r
 145 Jane Doe &lt;jane@laptop.(none)&gt;\r
 146 Jane D. &lt;jane@desktop.(none)&gt;</screen>\r
 147 <simpara>Now suppose that Joe wants his middle name initial used, and Jane\r
 148 prefers her family name fully spelled out. A proper <emphasis>.mailmap</emphasis> file\r
 149 would look like:</simpara>\r
 150 <screen>Jane Doe         &lt;jane@desktop.(none)&gt;\r
 151 Joe R. Developer &lt;joe@example.com&gt;</screen>\r
 152 <simpara>Note how there is no need for an entry for &lt;<ulink url="mailto:jane@laptop">jane@laptop</ulink>.(none)&gt;, because the\r
 153 real name of that author is already correct.</simpara>\r
 154 <simpara>Example 2: Your repository contains commits from the following\r
 155 authors:</simpara>\r
 156 <screen>nick1 &lt;bugs@company.xx&gt;\r
 157 nick2 &lt;bugs@company.xx&gt;\r
 158 nick2 &lt;nick2@company.xx&gt;\r
 159 santa &lt;me@company.xx&gt;\r
 160 claus &lt;me@company.xx&gt;\r
 161 CTO &lt;cto@coompany.xx&gt;</screen>\r
 162 <simpara>Then you might want a <emphasis>.mailmap</emphasis> file that looks like:</simpara>\r
 163 <screen>&lt;cto@company.xx&gt;                       &lt;cto@coompany.xx&gt;\r
 164 Some Dude &lt;some@dude.xx&gt;         nick1 &lt;bugs@company.xx&gt;\r
 165 Other Author &lt;other@author.xx&gt;   nick2 &lt;bugs@company.xx&gt;\r
 166 Other Author &lt;other@author.xx&gt;         &lt;nick2@company.xx&gt;\r
 167 Santa Claus &lt;santa.claus@northpole.xx&gt; &lt;me@company.xx&gt;</screen>\r
 168 <simpara>Use hash <emphasis>#</emphasis> for comments that are either on their own line, or after\r
 169 the email address.</simpara>\r
 170 </simplesect>\r
 171 <simplesect id="_git">\r
 172 <title>GIT</title>\r
 173 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
 174 </simplesect>\r
 175 </article>\r