1f010d6bdf
We presently use the ".txt" extension for our AsciiDoc files. While not wrong, most editors do not associate this extension with AsciiDoc, meaning that contributors don't get automatic editor functionality that could be useful, such as syntax highlighting and prose linting. It is much more common to use the ".adoc" extension for AsciiDoc files, since this helps editors automatically detect files and also allows various forges to provide rich (HTML-like) rendering. Let's do that here, renaming all of the files and updating the includes where relevant. Adjust the various build scripts and makefiles to use the new extension as well. Note that this should not result in any user-visible changes to the documentation. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
221 lines
6.7 KiB
Plaintext
221 lines
6.7 KiB
Plaintext
git-log(1)
|
|
==========
|
|
|
|
NAME
|
|
----
|
|
git-log - Show commit logs
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'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. 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. 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>::
|
|
For each candidate reference, 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`.
|
|
+
|
|
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
|