README

   1 git-log-compact
   2 ===============
   3
   4 A compact alternative to `git log --oneline` that includes dates, times
   5 and author and/or committer initials in a space efficient output format.
   6
   7 The `git-log-compact` script is intended to fill the gap between the
   8 `--oneline` log output format and the `--pretty=short`/`--pretty=medium`
   9 output formats.  It is not strictly a one line per commit output format
  10 (but almost) and while it only shows the title of each commit (like the
  11 `--pretty=short` format) it does include author and date information
  12 (like the `--pretty=medium` format) except that timestamps are shown
  13 very compactly and author/committer names are shown as initials.
  14
  15 This allows one to get a complete view of repository activity in a very
  16 compact output format that can show many commits per screen full and is
  17 fully compatible with the `--graph` option.
  18
  19 The `--notes`, `--pretty` and `--format` options are not allowed but any
  20 other `git log` options should work fine (especially `--graph`).
  21
  22 In both `--graph` and non `--graph` modes:
  23
  24    * Root commits are identified by `_` on either side of the hash
  25
  26 When `--graph` mode is enabled, the graph output is enhanced as follows:
  27
  28    * Breaks are inserted when necessary to avoid parent/child ambiguity
  29
  30
  31 Installation
  32 ------------
  33
  34 Put the `git-log-compact` executable file in one of the directories
  35 included in the `PATH` environment variable.
  36
  37 Optionally set a global alias to save typing such as `lc` like so:
  38
  39     git config --global alias.lc log-compact
  40
  41 Optionally set global default options such as `--two-initials` and
  42 `--abbrev=8` like so:
  43
  44     git config --global log-compact.defaults "--two-initials --abbrev=8"
  45
  46
  47 Dates & Times
  48 -------------
  49
  50 Dates and times are shown in the local timezone.  Set the TZ variable
  51 before running `git log-compact` (e.g. `TZ=UTC git log-compact` to show
  52 dates and times in UTC) or use the `--time-zone=` option (e.g.
  53 `git log-compact --time-zone=UTC`) to change that.
  54
  55 Dates are shown on a date line all by themselves like so:
  56
  57     === 2015-11-13 ===
  58
  59 The date line indicates that the times on all the following lines
  60 (regardless of whether or not `--reverse` is being used) up until
  61 the next date line take place on the indicated date.  For example
  62 this output:
  63
  64     === 2015-09-28 ===
  65     be08dee9 13:18 jc (tag: v2.6.0) Git 2.6
  66     === 2015-09-21 ===
  67     8d530c4d 13:26 jc (tag: v2.6.0-rc3) Git 2.6-rc3
  68     904f6e7c 10:51 bn send-email: fix uninitialized var warning for $
  69     === 2015-09-20 ===
  70     18a21c19 09:49 ps l10n: de.po: better language for one string
  71     2e0f3663 09:49 rt l10n: de.po: translate 2 messages
  72     5fc31c1f 09:44 tq l10n: Update and review Vietnamese translation
  73
  74 shows one commit on 2015-09-28, two commits on 2015-09-21 and three
  75 commits on 2015-09-20.
  76
  77 Note that a date line may appear more than once for the same date
  78 (this is especially common when using `--graph` with its default
  79 `--topo-order`).
  80
  81 The purpose of a date line is to indicate what date has been elided
  82 from the following lines, nothing more.
  83
  84
  85 Examples
  86 --------
  87
  88 For example, running `git log-compact --decorate --graph -n 17 v2.6.1`
  89 on the Git repository produces this output (which will be colorized
  90 on the terminal if color is enabled):
  91
  92       === 2015-09-28 ===
  93     * 22f698cb 19:19 jch (tag: v2.6.1) Git 2.6.1
  94     *   3adc4ec7 19:16 jch Sync with v2.5.4
  95     |\
  96     | * 24358560 15:34 jch (tag: v2.5.4) Git 2.5.4
  97     | *   11a458be 15:33 jch Sync with 2.4.10
  98     | |\
  99     | | * a2558fb8 15:30 jch (tag: v2.4.10) Git 2.4.10
 100     | | *   6343e2f6 15:28 jch Sync with 2.3.10
 101     | | |\
 102     | | | * 18b58f70 15:26 jch (tag: v2.3.10) Git 2.3.10
 103     | | | *   92cdfd21 14:59 jch Merge branch 'jk/xdiff-memory-limits
 104     | | | |\
 105     | | | | * 83c4d380 14:58 jk  merge-file: enforce MAX_XDIFF_SIZE o
 106     | | | | * dcd1742e 14:57 jk  xdiff: reject files larger than ~1GB
 107     | | | | * 3efb9880 14:57 jk  react to errors in xdi_diff
 108     | | | * |   f2df3104 14:46 jch Merge branch 'jk/transfer-limit-re
 109     | | | |\ \
 110     | | | | | | === 2015-09-25 ===
 111     | | | | * | b2581164 15:32 bb  http: limit redirection depth
 112     | | | | * | f4113cac 15:30 bb  http: limit redirection to protoco
 113     | | | | * | 5088d3b3 15:28 jk  transport: refactor protocol white
 114     | | | | | |   === 2015-09-28 ===
 115     | | | * | |   df37727a 14:33 jch Merge branch 'jk/transfer-limit-
 116     | | | |\ \ \
 117     | | | | |/ /
 118     | | | | | /
 119     | | | | |/
 120     | | | |/|
 121     | | | | | === 2015-09-23 ===
 122     | | | | * 33cfccbb 11:35 jk  submodule: allow only certain protoc
 123
 124 The output will be colorized according to the same settings used to enable/
 125 disable color for git log output.
 126
 127 Additionally, the color of the three new items (dates, times and
 128 initials) can be controlled with the `color.log-compact.date`,
 129 `color.log-compact.time` and `color.log-compact.initials` config options.
 130
 131 Running `git log-compact --graph --max-parents=0` on the Git repository gives:
 132
 133       === 2009-04-24 ===
 134     *_0ca71b37_11:13 ap  basic options parsing and whatnot.
 135       === 2007-01-30 ===
 136     *_16d6b8ab_15:16 sh  Initial import of a python script to import ch
 137       === 2006-11-06 ===
 138     *_cb07fc2a_11:20 sop git-gui: Initial revision.
 139       === 2005-08-07 ===
 140     *_161332a5_10:49 ks  first working version
 141       === 2005-04-11 ===
 142     *_2744b234_23:46 lt  Start of early patch applicator tools for git.
 143       === 2005-05-08 ===
 144     *_1db95b00_21:08 pm  Add initial version of gitk to the CVS reposit
 145       === 2005-04-07 ===
 146     *_e83c5163_15:13 lt  Initial revision of "git", the information man
 147
 148 Notice the `_` on either side of the hash identifying those commits
 149 as root commits.  The `_` will only appear on the left side of the
 150 hash if the selected output format would have normally included a
 151 space there.  In `--graph` mode, all the spaces between the commit mark
 152 (e.g. `*`) and the hash are turned into `_`.
 153
 154 Running `git log-compact --decorate --graph --no-merges -n 13 v2.6.1`
 155 on the Git repository results in this output:
 156
 157       === 2015-09-28 ===
 158     * 22f698cb 19:19 jch (tag: v2.6.1) Git 2.6.1
 159                          ..........
 160     * 24358560 15:34 jch (tag: v2.5.4) Git 2.5.4
 161                          ..........
 162     * a2558fb8 15:30 jch (tag: v2.4.10) Git 2.4.10
 163                          ..........
 164     * 18b58f70 15:26 jch (tag: v2.3.10) Git 2.3.10
 165                          ..........
 166     * 83c4d380 14:58 jk  merge-file: enforce MAX_XDIFF_SIZE on incomi
 167     * dcd1742e 14:57 jk  xdiff: reject files larger than ~1GB
 168     * 3efb9880 14:57 jk  react to errors in xdi_diff
 169     |   === 2015-09-25 ===
 170     | * b2581164 15:32 bb  http: limit redirection depth
 171     | * f4113cac 15:30 bb  http: limit redirection to protocol-whitel
 172     | * 5088d3b3 15:28 jk  transport: refactor protocol whitelist cod
 173     | | === 2015-09-23 ===
 174     | * 33cfccbb 11:35 jk  submodule: allow only certain protocols fo
 175     | * a5adaced 11:35 jk  transport: add a protocol-whitelist enviro
 176     |/
 177     |   === 2015-09-28 ===
 178     | * be08dee9 13:18 jch (tag: v2.6.0) Git 2.6
 179
 180 Notice how four linear breaks (`..........`) were automatically
 181 inserted to avoid parent child relationship confusion.
 182
 183 In non `--graph` mode, linear breaks are NOT automatically inserted.
 184 They must be requested with the usual `--show-linear-break` option.
 185
 186
 187 Options
 188 -------
 189
 190 In addition to allowing all the normal `git log` options except for
 191 `--notes`, `--format` and `--pretty` (`--oneline` is allowed and
 192 silently ignored), the following additional options may be utilized:
 193
 194    * `--seconds`
 195      include seconds in the time (i.e. HH:MM:SS instead of just HH:MM)
 196
 197    * `--minutes`
 198      include minutes but not seconds in the time (i.e. HH:MM not HH:MM:SS)
 199      This is the default
 200
 201    * `--no-times`
 202      omit the time field entirely
 203
 204    * `--two-initials`
 205      only show at most two initials instead of the usual three
 206      This is the default if `--initials=author,committer` or
 207      `--initials=committer,author` is used.
 208
 209    * `--three-initials`
 210      show at most three initials
 211      This is the default unless `--initials=author,committer` or
 212      `--initials=committer,author` is used.
 213
 214    * `--no-initials`
 215      omit the initials field entirely
 216
 217    * `--commit-message`
 218      when using `--walk-reflogs` show commit message not reflog message
 219
 220    * `--author-date`
 221      force use of author dates and times
 222      The default is to use committer dates and times unless
 223      `--author-date-order` is in effect.  This option forces author
 224      dates and times to always be used and overrides `--committer-date`.
 225
 226    * `--committer-date`
 227      force use of committer dates and times
 228      The default is to use committer dates and times if `--date-order` or
 229      `--topo-order` is in effect or `--author-date-order` is NOT in effect.
 230      This option forces committer dates and times to always be used and
 231      overrides a previous `--author-date` option.
 232
 233    * `--initials=author`
 234      show author initials
 235      This is the default behavior
 236
 237    * `--initials=committer`
 238      show committer initials instead of author initials
 239
 240    * `--initials=author,committer`
 241      show author and commiter initials separated by a `/`
 242      This changes the initials width default from three to two.
 243
 244    * `--initials=committer,author`
 245      show commiter and author initials separated by a `/`
 246      This changes the initials width default from three to two.
 247
 248    * `--time-zone=zone`
 249      set the TZ environment variable to `zone`
 250      This is an alterative to setting TZ before running `git log-compact`
 251      and will affect the time zone dates and times are displayed in.
 252
 253    * `--weekday`
 254      show the weekday with the date
 255
 256    * `--no-weekday`
 257      do not show the weekday with the date
 258      This is the default behavior
 259
 260 In addition to the above options, color output is controlled as normal
 261 for `git log` with the addition of `color.log-compact.date`,
 262 `color.log-compact.time` and `color.log-compact.initials` config options
 263 to alter the default colors for dates, times and initials respectively.
 264
 265 Furthermore, default options may be set in the `log-compact.defaults`
 266 config value and they will be treated as though they appeared at
 267 the very beginning of the `git log-compact` command line option list
 268 (e.g. `git config log-compact.defaults "--abbrev=8 --seconds"`).