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