Documentation/git-log.txt

   1 git-log(1)
   2 ==========
   3
   4 NAME
   5 ----
   6 git-log - Show commit logs
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git log' [<options>] [<revision-range>] [[--] <path>...]
  13
  14 DESCRIPTION
  15 -----------
  16 Shows the commit logs.
  17
  18 :git-log: 1
  19 include::rev-list-description.txt[]
  20
  21 The command takes options applicable to the linkgit:git-rev-list[1]
  22 command to control what is shown and how, and options applicable to
  23 the linkgit:git-diff[1] command to control how the changes
  24 each commit introduces are shown.
  25
  26
  27 OPTIONS
  28 -------
  29
  30 --follow::
  31         Continue listing the history of a file beyond renames
  32         (works only for a single file).
  33
  34 --no-decorate::
  35 --decorate[=short|full|auto|no]::
  36         Print out the ref names of any commits that are shown. If 'short' is
  37         specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and
  38         'refs/remotes/' will not be printed. If 'full' is specified, the
  39         full ref name (including prefix) will be printed. If 'auto' is
  40         specified, then if the output is going to a terminal, the ref names
  41         are shown as if 'short' were given, otherwise no ref names are
  42         shown. The option `--decorate` is short-hand for `--decorate=short`.
  43         Default to configuration value of `log.decorate` if configured,
  44         otherwise, `auto`.
  45
  46 --decorate-refs=<pattern>::
  47 --decorate-refs-exclude=<pattern>::
  48         If no `--decorate-refs` is given, pretend as if all refs were
  49         included.  For each candidate, do not use it for decoration if it
  50         matches any patterns given to `--decorate-refs-exclude` or if it
  51         doesn't match any of the patterns given to `--decorate-refs`. The
  52         `log.excludeDecoration` config option allows excluding refs from
  53         the decorations, but an explicit `--decorate-refs` pattern will
  54         override a match in `log.excludeDecoration`.
  55
  56 --source::
  57         Print out the ref name given on the command line by which each
  58         commit was reached.
  59
  60 --[no-]mailmap::
  61 --[no-]use-mailmap::
  62         Use mailmap file to map author and committer names and email
  63         addresses to canonical real names and email addresses. See
  64         linkgit:git-shortlog[1].
  65
  66 --full-diff::
  67         Without this flag, `git log -p <path>...` shows commits that
  68         touch the specified paths, and diffs about the same specified
  69         paths.  With this, the full diff is shown for commits that touch
  70         the specified paths; this means that "<path>..." limits only
  71         commits, and doesn't limit diff for those commits.
  72 +
  73 Note that this affects all diff-based output types, e.g. those
  74 produced by `--stat`, etc.
  75
  76 --log-size::
  77         Include a line ``log size <number>'' in the output for each commit,
  78         where <number> is the length of that commit's message in bytes.
  79         Intended to speed up tools that read log messages from `git log`
  80         output by allowing them to allocate space in advance.
  81
  82 include::line-range-options.txt[]
  83
  84 <revision-range>::
  85         Show only commits in the specified revision range.  When no
  86         <revision-range> is specified, it defaults to `HEAD` (i.e. the
  87         whole history leading to the current commit).  `origin..HEAD`
  88         specifies all the commits reachable from the current commit
  89         (i.e. `HEAD`), but not from `origin`. For a complete list of
  90         ways to spell <revision-range>, see the 'Specifying Ranges'
  91         section of linkgit:gitrevisions[7].
  92
  93 [--] <path>...::
  94         Show only commits that are enough to explain how the files
  95         that match the specified paths came to be.  See 'History
  96         Simplification' below for details and other simplification
  97         modes.
  98 +
  99 Paths may need to be prefixed with `--` to separate them from
 100 options or the revision range, when confusion arises.
 101
 102 include::rev-list-options.txt[]
 103
 104 include::pretty-formats.txt[]
 105
 106 DIFF FORMATTING
 107 ---------------
 108
 109 By default, `git log` does not generate any diff output. The options
 110 below can be used to show the changes made by each commit.
 111
 112 Note that unless one of `--diff-merges` variants (including short
 113 `-m`, `-c`, and `--cc` options) is explicitly given, merge commits
 114 will not show a diff, even if a diff format like `--patch` is
 115 selected, nor will they match search options like `-S`. The exception
 116 is when `--first-parent` is in use, in which case `first-parent` is
 117 the default format.
 118
 119 :git-log: 1
 120 :diff-merges-default: `off`
 121 include::diff-options.txt[]
 122
 123 include::diff-generate-patch.txt[]
 124
 125 EXAMPLES
 126 --------
 127 `git log --no-merges`::
 128
 129         Show the whole commit history, but skip any merges
 130
 131 `git log v2.6.12.. include/scsi drivers/scsi`::
 132
 133         Show all commits since version 'v2.6.12' that changed any file
 134         in the `include/scsi` or `drivers/scsi` subdirectories
 135
 136 `git log --since="2 weeks ago" -- gitk`::
 137
 138         Show the changes during the last two weeks to the file 'gitk'.
 139         The `--` is necessary to avoid confusion with the *branch* named
 140         'gitk'
 141
 142 `git log --name-status release..test`::
 143
 144         Show the commits that are in the "test" branch but not yet
 145         in the "release" branch, along with the list of paths
 146         each commit modifies.
 147
 148 `git log --follow builtin/rev-list.c`::
 149
 150         Shows the commits that changed `builtin/rev-list.c`, including
 151         those commits that occurred before the file was given its
 152         present name.
 153
 154 `git log --branches --not --remotes=origin`::
 155
 156         Shows all commits that are in any of local branches but not in
 157         any of remote-tracking branches for 'origin' (what you have that
 158         origin doesn't).
 159
 160 `git log master --not --remotes=*/master`::
 161
 162         Shows all commits that are in local master but not in any remote
 163         repository master branches.
 164
 165 `git log -p -m --first-parent`::
 166
 167         Shows the history including change diffs, but only from the
 168         ``main branch'' perspective, skipping commits that come from merged
 169         branches, and showing full diffs of changes introduced by the merges.
 170         This makes sense only when following a strict policy of merging all
 171         topic branches when staying on a single integration branch.
 172
 173 `git log -L '/int main/',/^}/:main.c`::
 174
 175         Shows how the function `main()` in the file `main.c` evolved
 176         over time.
 177
 178 `git log -3`::
 179
 180         Limits the number of commits to show to 3.
 181
 182 DISCUSSION
 183 ----------
 184
 185 include::i18n.txt[]
 186
 187 CONFIGURATION
 188 -------------
 189
 190 See linkgit:git-config[1] for core variables and linkgit:git-diff[1]
 191 for settings related to diff generation.
 192
 193 format.pretty::
 194         Default for the `--format` option.  (See 'Pretty Formats' above.)
 195         Defaults to `medium`.
 196
 197 i18n.logOutputEncoding::
 198         Encoding to use when displaying logs.  (See 'Discussion' above.)
 199         Defaults to the value of `i18n.commitEncoding` if set, and UTF-8
 200         otherwise.
 201
 202 log.date::
 203         Default format for human-readable dates.  (Compare the
 204         `--date` option.)  Defaults to "default", which means to write
 205         dates like `Sat May 8 19:35:34 2010 -0500`.
 206 +
 207 If the format is set to "auto:foo" and the pager is in use, format
 208 "foo" will be the used for the date format. Otherwise "default" will
 209 be used.
 210
 211 log.follow::
 212         If `true`, `git log` will act as if the `--follow` option was used when
 213         a single <path> is given.  This has the same limitations as `--follow`,
 214         i.e. it cannot be used to follow multiple files and does not work well
 215         on non-linear history.
 216
 217 log.showRoot::
 218         If `false`, `git log` and related commands will not treat the
 219         initial commit as a big creation event.  Any root commits in
 220         `git log -p` output would be shown without a diff attached.
 221         The default is `true`.
 222
 223 log.showSignature::
 224         If `true`, `git log` and related commands will act as if the
 225         `--show-signature` option was passed to them.
 226
 227 mailmap.*::
 228         See linkgit:git-shortlog[1].
 229
 230 notes.displayRef::
 231         Which refs, in addition to the default set by `core.notesRef`
 232         or `GIT_NOTES_REF`, to read notes from when showing commit
 233         messages with the `log` family of commands.  See
 234         linkgit:git-notes[1].
 235 +
 236 May be an unabbreviated ref name or a glob and may be specified
 237 multiple times.  A warning will be issued for refs that do not exist,
 238 but a glob that does not match any refs is silently ignored.
 239 +
 240 This setting can be disabled by the `--no-notes` option,
 241 overridden by the `GIT_NOTES_DISPLAY_REF` environment variable,
 242 and overridden by the `--notes=<ref>` option.
 243
 244 GIT
 245 ---
 246 Part of the linkgit:git[1] suite