diff options
Diffstat (limited to 'Documentation/git-log.adoc')
| -rw-r--r-- | Documentation/git-log.adoc | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/Documentation/git-log.adoc b/Documentation/git-log.adoc new file mode 100644 index 0000000000..b6f3d92c43 --- /dev/null +++ b/Documentation/git-log.adoc @@ -0,0 +1,226 @@ +git-log(1) +========== + +NAME +---- +git-log - Show commit logs + + +SYNOPSIS +-------- +[synopsis] +git log [<options>] [<revision-range>] [[--] <path>...] + +DESCRIPTION +----------- +Shows the commit logs. + +:git-log: 1 +include::rev-list-description.adoc[] + +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 linkgit:git-diff[1] command to control how the changes +each commit introduces are shown. + + +OPTIONS +------- + +`--follow`:: + Continue listing the history of a file beyond renames + (works only for a single file). + +`--no-decorate`:: +`--decorate[=(short|full|auto|no)]`:: + Print out the ref names of any commits that are shown. Possible values + are: ++ +---- +`short`;; the ref name prefixes `refs/heads/`, `refs/tags/` and + `refs/remotes/` are not printed. +`full`;; the full ref name (including prefix) is printed. +`auto`:: 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>`:: + For each candidate reference, do not use it for decoration if it + matches any of the _<pattern>_ parameters given to + `--decorate-refs-exclude` or if it doesn't match any of the + _<pattern>_ parameters 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`. ++ +If none of these options or config settings are given, then references are +used as decoration if they match `HEAD`, `refs/heads/`, `refs/remotes/`, +`refs/stash/`, or `refs/tags/`. + +`--clear-decorations`:: + When specified, this option clears all previous `--decorate-refs` + or `--decorate-refs-exclude` options and relaxes the default + decoration filter to include all references. This option is + assumed if the config value `log.initialDecorationSet` is set to + `all`. + +`--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 + 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. + +`--log-size`:: + 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.adoc[] + +_<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 + modes. ++ +Paths may need to be prefixed with `--` to separate them from +options or the revision range, when confusion arises. + +include::rev-list-options.adoc[] + +include::pretty-formats.adoc[] + +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`, `--cc`, and `--dd` 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 for merge commits. + +:git-log: 1 +:diff-merges-default: `off` +include::diff-options.adoc[] + +include::diff-generate-patch.adoc[] + +EXAMPLES +-------- +`git log --no-merges`:: + + Show the whole commit history, but skip any merges + +`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 + +`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 + `gitk` + +`git log --name-status release..test`:: + + Show the commits that are in the "`test`" branch but not yet + in the "`release`" branch, along with the list of paths + each commit modifies. + +`git log --follow builtin/rev-list.c`:: + + Shows the commits that changed `builtin/rev-list.c`, including + those commits that occurred before the file was given its + present name. + +`git log --branches --not --remotes=origin`:: + + Shows all commits that are in any of local branches but not in + any of remote-tracking branches for `origin` (what you have that + origin doesn't). + +`git log master --not --remotes=*/master`:: + + Shows all commits that are in local master but not in any remote + repository master branches. + +`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 + 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 +---------- + +include::i18n.adoc[] + +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`. + +`i18n.logOutputEncoding`:: + Encoding to use when displaying logs. (See 'Discussion' above.) + Defaults to the value of `i18n.commitEncoding` if set, and UTF-8 + otherwise. + +include::includes/cmd-config-section-rest.adoc[] + +include::config/log.adoc[] + +include::config/notes.adoc[] + +GIT +--- +Part of the linkgit:git[1] suite |