doc: convert [\--] to [--]
[git/git.git] / Documentation / git-log.txt
CommitLineData
215a7ad1
JH
1git-log(1)
2==========
3f971fc4
JH
3
4NAME
5----
215a7ad1 6git-log - Show commit logs
3f971fc4
JH
7
8
9SYNOPSIS
10--------
7791a1d9 11[verse]
933c758c 12'git log' [<options>] [<revision range>] [[--] <path>...]
3f971fc4
JH
13
14DESCRIPTION
15-----------
e51c3b50
JH
16Shows the commit logs.
17
b20cc13e 18The command takes options applicable to the `git rev-list`
e51c3b50 19command to control what is shown and how, and options applicable to
b20cc13e 20the `git diff-*` commands to control how the changes
e51c3b50
JH
21each commit introduces are shown.
22
3f971fc4
JH
23
24OPTIONS
25-------
5d1faf87 26
4ded6916
EB
27--follow::
28 Continue listing the history of a file beyond renames
29 (works only for a single file).
30
8a3d203b 31--no-decorate::
462cbb41 32--decorate[=short|full|auto|no]::
33e7018c
LH
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
462cbb41
RJ
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'.
56822cc9 40
65516f58
RA
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`.
47
30c4d7a7
NS
48--source::
49 Print out the ref name given on the command line by which each
50 commit was reached.
51
ea57bc0d
AP
52--use-mailmap::
53 Use mailmap file to map author and committer names and email
b20cc13e 54 addresses to canonical real names and email addresses. See
ea57bc0d
AP
55 linkgit:git-shortlog[1].
56
2e88c266 57--full-diff::
b20cc13e 58 Without this flag, `git log -p <path>...` shows commits that
2e88c266
JN
59 touch the specified paths, and diffs about the same specified
60 paths. With this, the full diff is shown for commits that touch
f448e24e 61 the specified paths; this means that "<path>..." limits only
2e88c266 62 commits, and doesn't limit diff for those commits.
b1c7946d
MG
63+
64Note that this affects all diff-based output types, e.g. those
b20cc13e 65produced by `--stat`, etc.
2e88c266 66
9fa3465d 67--log-size::
c20e6fb1
JSJ
68 Include a line ``log size <number>'' in the output for each commit,
69 where <number> is the length of that commit's message in bytes.
70 Intended to speed up tools that read log messages from `git log`
71 output by allowing them to allocate space in advance.
9fa3465d 72
1e159833 73-L <start>,<end>:<file>::
d349e0ee 74-L :<funcname>:<file>::
12da1d1f 75 Trace the evolution of the line range given by "<start>,<end>"
d349e0ee 76 (or the function name regex <funcname>) within the <file>. You may
13b8f68c
TR
77 not give any pathspec limiters. This is currently limited to
78 a walk starting from a single revision, i.e., you may only
79 give zero or one positive revision arguments.
0f483436
JH
80 You can specify this option more than once.
81+
12da1d1f 82include::line-range-format.txt[]
12da1d1f 83
21a40b90
RR
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
b20cc13e 90 ways to spell <revision range>, see the 'Specifying Ranges'
21a40b90 91 section of linkgit:gitrevisions[7].
a682187e 92
933c758c 93[--] <path>...::
b15b5b10 94 Show only commits that are enough to explain how the files
b20cc13e
JSJ
95 that match the specified paths came to be. See 'History
96 Simplification' below for details and other simplification
b15b5b10
TR
97 modes.
98+
b20cc13e 99Paths may need to be prefixed with ``\-- '' to separate them from
00200e9e 100options or the revision range, when confusion arises.
e51c3b50 101
f98fd436
MG
102include::rev-list-options.txt[]
103
104include::pretty-formats.txt[]
105
4ba258b7 106COMMON DIFF OPTIONS
f98fd436 107-------------------
4ded6916
EB
108
109:git-log: 1
110include::diff-options.txt[]
331b51d2 111
272bd3cf 112include::diff-generate-patch.txt[]
331b51d2 113
4ba258b7 114EXAMPLES
bd663611 115--------
5d2fc913 116`git log --no-merges`::
bd663611
LT
117
118 Show the whole commit history, but skip any merges
119
5d2fc913 120`git log v2.6.12.. include/scsi drivers/scsi`::
bd663611
LT
121
122 Show all commits since version 'v2.6.12' that changed any file
b20cc13e 123 in the `include/scsi` or `drivers/scsi` subdirectories
bd663611 124
6cf378f0 125`git log --since="2 weeks ago" -- gitk`::
bd663611
LT
126
127 Show the changes during the last two weeks to the file 'gitk'.
b20cc13e 128 The ``--'' is necessary to avoid confusion with the *branch* named
bd663611
LT
129 'gitk'
130
5d2fc913 131`git log --name-status release..test`::
e51c3b50
JH
132
133 Show the commits that are in the "test" branch but not yet
134 in the "release" branch, along with the list of paths
135 each commit modifies.
bd663611 136
09b7e220 137`git log --follow builtin/rev-list.c`::
4f50f6a9 138
b20cc13e 139 Shows the commits that changed `builtin/rev-list.c`, including
4f50f6a9
SW
140 those commits that occurred before the file was given its
141 present name.
142
5d2fc913 143`git log --branches --not --remotes=origin`::
d08bae7e
IL
144
145 Shows all commits that are in any of local branches but not in
0e615b25 146 any of remote-tracking branches for 'origin' (what you have that
d08bae7e
IL
147 origin doesn't).
148
5d2fc913 149`git log master --not --remotes=*/master`::
d08bae7e
IL
150
151 Shows all commits that are in local master but not in any remote
152 repository master branches.
153
5d2fc913 154`git log -p -m --first-parent`::
88d9d45d
PB
155
156 Shows the history including change diffs, but only from the
b20cc13e 157 ``main branch'' perspective, skipping commits that come from merged
88d9d45d
PB
158 branches, and showing full diffs of changes introduced by the merges.
159 This makes sense only when following a strict policy of merging all
160 topic branches when staying on a single integration branch.
161
001b0976 162`git log -L '/int main/',/^}/:main.c`::
12da1d1f 163
b20cc13e 164 Shows how the function `main()` in the file `main.c` evolved
12da1d1f
TR
165 over time.
166
70c2a258 167`git log -3`::
b20cc13e 168
70c2a258 169 Limits the number of commits to show to 3.
88d9d45d 170
4ba258b7 171DISCUSSION
5dc7bcc2
JH
172----------
173
174include::i18n.txt[]
175
4ba258b7 176CONFIGURATION
59893a88
JN
177-------------
178
179See linkgit:git-config[1] for core variables and linkgit:git-diff[1]
180for settings related to diff generation.
181
182format.pretty::
b20cc13e
JSJ
183 Default for the `--format` option. (See 'Pretty Formats' above.)
184 Defaults to `medium`.
59893a88
JN
185
186i18n.logOutputEncoding::
b20cc13e
JSJ
187 Encoding to use when displaying logs. (See 'Discussion' above.)
188 Defaults to the value of `i18n.commitEncoding` if set, and UTF-8
59893a88
JN
189 otherwise.
190
191log.date::
192 Default format for human-readable dates. (Compare the
193 `--date` option.) Defaults to "default", which means to write
194 dates like `Sat May 8 19:35:34 2010 -0500`.
195
076c9837 196log.follow::
fd8d07ef
EVW
197 If `true`, `git log` will act as if the `--follow` option was used when
198 a single <path> is given. This has the same limitations as `--follow`,
199 i.e. it cannot be used to follow multiple files and does not work well
200 on non-linear history.
076c9837 201
da0005b8 202log.showRoot::
b20cc13e 203 If `false`, `git log` and related commands will not treat the
59893a88
JN
204 initial commit as a big creation event. Any root commits in
205 `git log -p` output would be shown without a diff attached.
206 The default is `true`.
207
fce04c3c
MJ
208log.showSignature::
209 If `true`, `git log` and related commands will act as if the
210 `--show-signature` option was passed to them.
211
d5422b0c 212mailmap.*::
59893a88
JN
213 See linkgit:git-shortlog[1].
214
215notes.displayRef::
216 Which refs, in addition to the default set by `core.notesRef`
eee7f4a2 217 or `GIT_NOTES_REF`, to read notes from when showing commit
b20cc13e 218 messages with the `log` family of commands. See
59893a88
JN
219 linkgit:git-notes[1].
220+
221May be an unabbreviated ref name or a glob and may be specified
222multiple times. A warning will be issued for refs that do not exist,
223but a glob that does not match any refs is silently ignored.
224+
ab18b2c0 225This setting can be disabled by the `--no-notes` option,
eee7f4a2 226overridden by the `GIT_NOTES_DISPLAY_REF` environment variable,
ab18b2c0 227and overridden by the `--notes=<ref>` option.
5dc7bcc2 228
3f971fc4
JH
229GIT
230---
9e1f0a85 231Part of the linkgit:git[1] suite