diff options
Diffstat (limited to 'Documentation/git-log.txt')
| -rw-r--r-- | Documentation/git-log.txt | 151 |
1 files changed, 104 insertions, 47 deletions
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 585dac40ba..0498e7bacb 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -9,83 +9,120 @@ git-log - Show commit logs SYNOPSIS -------- [verse] -'git log' [<options>] [<since>..<until>] [[\--] <path>...] +'git log' [<options>] [<revision range>] [[--] <path>...] DESCRIPTION ----------- Shows the commit logs. -The command takes options applicable to the 'git rev-list' +:git-log: 1 +include::rev-list-description.txt[] + +The command takes options applicable to the linkgit:git-rev-list[1] command to control what is shown and how, and options applicable to -the 'git diff-*' commands to control how the changes +the linkgit:git-diff[1] command to control how the changes each commit introduces are shown. OPTIONS ------- -<since>..<until>:: - Show only commits between the named two commits. When - either <since> or <until> is omitted, it defaults to - `HEAD`, i.e. the tip of the current branch. - For a more complete list of ways to spell <since> - and <until>, see linkgit:gitrevisions[7]. - --follow:: Continue listing the history of a file beyond renames (works only for a single file). --no-decorate:: ---decorate[=short|full|no]:: +--decorate[=short|full|auto|no]:: Print out the ref names of any commits that are shown. If 'short' is specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and 'refs/remotes/' will not be printed. If 'full' is specified, the - full ref name (including prefix) will be printed. The default option - is 'short'. + full ref name (including prefix) will be printed. If 'auto' is + specified, then if the output is going to a terminal, the ref names + are shown as if 'short' were given, otherwise no ref names are + shown. The option `--decorate` is short-hand for `--decorate=short`. + Default to configuration value of `log.decorate` if configured, + otherwise, `auto`. + +--decorate-refs=<pattern>:: +--decorate-refs-exclude=<pattern>:: + If no `--decorate-refs` is given, pretend as if all refs were + included. For each candidate, do not use it for decoration if it + matches any patterns given to `--decorate-refs-exclude` or if it + doesn't match any of the patterns given to `--decorate-refs`. The + `log.excludeDecoration` config option allows excluding refs from + the decorations, but an explicit `--decorate-refs` pattern will + override a match in `log.excludeDecoration`. --source:: Print out the ref name given on the command line by which each commit was reached. +--[no-]mailmap:: +--[no-]use-mailmap:: + Use mailmap file to map author and committer names and email + addresses to canonical real names and email addresses. See + linkgit:git-shortlog[1]. + --full-diff:: - Without this flag, "git log -p <path>..." shows commits that + Without this flag, `git log -p <path>...` shows commits that touch the specified paths, and diffs about the same specified paths. With this, the full diff is shown for commits that touch the specified paths; this means that "<path>..." limits only commits, and doesn't limit diff for those commits. + Note that this affects all diff-based output types, e.g. those -produced by --stat etc. +produced by `--stat`, etc. --log-size:: - Before the log message print out its size in bytes. Intended - mainly for porcelain tools consumption. If git is unable to - produce a valid value size is set to zero. - Note that only message is considered, if also a diff is shown - its size is not included. - -[\--] <path>...:: + Include a line ``log size <number>'' in the output for each commit, + where <number> is the length of that commit's message in bytes. + Intended to speed up tools that read log messages from `git log` + output by allowing them to allocate space in advance. + +include::line-range-options.txt[] + +<revision range>:: + Show only commits in the specified revision range. When no + <revision range> is specified, it defaults to `HEAD` (i.e. the + whole history leading to the current commit). `origin..HEAD` + specifies all the commits reachable from the current commit + (i.e. `HEAD`), but not from `origin`. For a complete list of + ways to spell <revision range>, see the 'Specifying Ranges' + section of linkgit:gitrevisions[7]. + +[--] <path>...:: Show only commits that are enough to explain how the files - that match the specified paths came to be. See "History - Simplification" below for details and other simplification + that match the specified paths came to be. See 'History + Simplification' below for details and other simplification modes. + -To prevent confusion with options and branch names, paths may need to -be prefixed with "\-- " to separate them from options or refnames. +Paths may need to be prefixed with `--` to separate them from +options or the revision range, when confusion arises. include::rev-list-options.txt[] include::pretty-formats.txt[] -Common diff options -------------------- +DIFF FORMATTING +--------------- + +By default, `git log` does not generate any diff output. The options +below can be used to show the changes made by each commit. + +Note that unless one of `--diff-merges` variants (including short +`-m`, `-c`, and `--cc` options) is explicitly given, merge commits +will not show a diff, even if a diff format like `--patch` is +selected, nor will they match search options like `-S`. The exception +is when `--first-parent` is in use, in which case `first-parent` is +the default format. :git-log: 1 +:diff-merges-default: `off` include::diff-options.txt[] include::diff-generate-patch.txt[] -Examples +EXAMPLES -------- `git log --no-merges`:: @@ -94,12 +131,12 @@ Examples `git log v2.6.12.. include/scsi drivers/scsi`:: Show all commits since version 'v2.6.12' that changed any file - in the include/scsi or drivers/scsi subdirectories + in the `include/scsi` or `drivers/scsi` subdirectories `git log --since="2 weeks ago" -- gitk`:: Show the changes during the last two weeks to the file 'gitk'. - The "--" is necessary to avoid confusion with the *branch* named + The `--` is necessary to avoid confusion with the *branch* named 'gitk' `git log --name-status release..test`:: @@ -108,9 +145,9 @@ Examples in the "release" branch, along with the list of paths each commit modifies. -`git log --follow builtin-rev-list.c`:: +`git log --follow builtin/rev-list.c`:: - Shows the commits that changed builtin-rev-list.c, including + Shows the commits that changed `builtin/rev-list.c`, including those commits that occurred before the file was given its present name. @@ -128,52 +165,72 @@ Examples `git log -p -m --first-parent`:: Shows the history including change diffs, but only from the - "main branch" perspective, skipping commits that come from merged + ``main branch'' perspective, skipping commits that come from merged branches, and showing full diffs of changes introduced by the merges. This makes sense only when following a strict policy of merging all topic branches when staying on a single integration branch. +`git log -L '/int main/',/^}/:main.c`:: + + Shows how the function `main()` in the file `main.c` evolved + over time. + `git log -3`:: + Limits the number of commits to show to 3. -Discussion +DISCUSSION ---------- include::i18n.txt[] -Configuration +CONFIGURATION ------------- See linkgit:git-config[1] for core variables and linkgit:git-diff[1] for settings related to diff generation. format.pretty:: - Default for the `--format` option. (See "PRETTY FORMATS" above.) - Defaults to "medium". + Default for the `--format` option. (See 'Pretty Formats' above.) + Defaults to `medium`. i18n.logOutputEncoding:: - Encoding to use when displaying logs. (See "Discussion", above.) - Defaults to the value of `i18n.commitEncoding` if set, UTF-8 + Encoding to use when displaying logs. (See 'Discussion' above.) + Defaults to the value of `i18n.commitEncoding` if set, and UTF-8 otherwise. log.date:: Default format for human-readable dates. (Compare the `--date` option.) Defaults to "default", which means to write dates like `Sat May 8 19:35:34 2010 -0500`. - -log.showroot:: - If `false`, 'git log' and related commands will not treat the ++ +If the format is set to "auto:foo" and the pager is in use, format +"foo" will be the used for the date format. Otherwise "default" will +be used. + +log.follow:: + If `true`, `git log` will act as if the `--follow` option was used when + a single <path> is given. This has the same limitations as `--follow`, + i.e. it cannot be used to follow multiple files and does not work well + on non-linear history. + +log.showRoot:: + If `false`, `git log` and related commands will not treat the initial commit as a big creation event. Any root commits in `git log -p` output would be shown without a diff attached. The default is `true`. -mailmap.file:: +log.showSignature:: + If `true`, `git log` and related commands will act as if the + `--show-signature` option was passed to them. + +mailmap.*:: See linkgit:git-shortlog[1]. notes.displayRef:: Which refs, in addition to the default set by `core.notesRef` - or 'GIT_NOTES_REF', to read notes from when showing commit - messages with the 'log' family of commands. See + or `GIT_NOTES_REF`, to read notes from when showing commit + messages with the `log` family of commands. See linkgit:git-notes[1]. + May be an unabbreviated ref name or a glob and may be specified @@ -181,7 +238,7 @@ multiple times. A warning will be issued for refs that do not exist, but a glob that does not match any refs is silently ignored. + This setting can be disabled by the `--no-notes` option, -overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable, +overridden by the `GIT_NOTES_DISPLAY_REF` environment variable, and overridden by the `--notes=<ref>` option. GIT |