summaryrefslogtreecommitdiff
path: root/Documentation/rev-list-options.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/rev-list-options.txt')
-rw-r--r--Documentation/rev-list-options.txt114
1 files changed, 90 insertions, 24 deletions
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 7b273635de..bfd02ade99 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -13,8 +13,6 @@ has a line that matches `<pattern>`), unless otherwise noted.
Note that these are applied before commit
ordering and formatting options, such as `--reverse`.
---
-
-<number>::
-n <number>::
--max-count=<number>::
@@ -60,7 +58,7 @@ endif::git-rev-list[]
`--all-match`).
ifndef::git-rev-list[]
+
-When `--show-notes` is in effect, the message from the notes is
+When `--notes` is in effect, the message from the notes is
matched as if it were part of the log message.
endif::git-rev-list[]
@@ -184,6 +182,14 @@ explicitly.
Pretend as if all objects mentioned by reflogs are listed on the
command line as `<commit>`.
+--alternate-refs::
+ Pretend as if all objects mentioned as ref tips of alternate
+ repositories were listed on the command line. An alternate
+ repository is any repository whose object directory is specified
+ in `objects/info/alternates`. The set of included objects may
+ be modified by `core.alternateRefsCommand`, etc. See
+ linkgit:git-config[1].
+
--single-worktree::
By default, all working trees will be examined by the
following options when there are more than one (see
@@ -263,7 +269,7 @@ list.
exclude (that is, '{caret}commit', 'commit1..commit2',
and 'commit1\...commit2' notations cannot be used).
+
-With `--pretty` format other than `oneline` (for obvious reasons),
+With `--pretty` format other than `oneline` and `reference` (for obvious reasons),
this causes the output to have two extra lines of information
taken from the reflog. The reflog designator in the output may be shown
as `ref@{Nth}` (where `Nth` is the reverse-chronological index in the
@@ -272,13 +278,13 @@ depending on a few rules:
+
--
1. If the starting point is specified as `ref@{Nth}`, show the index
-format.
+ format.
+
2. If the starting point was specified as `ref@{now}`, show the
-timestamp format.
+ timestamp format.
+
3. If neither was used, but `--date` was given on the command line, show
-the timestamp in the format requested by `--date`.
+ the timestamp in the format requested by `--date`.
+
4. Otherwise, show the index format.
--
@@ -287,6 +293,8 @@ Under `--pretty=oneline`, the commit message is
prefixed with this information on the same line.
This option cannot be combined with `--reverse`.
See also linkgit:git-reflog[1].
++
+Under `--pretty=reference`, this information will not be shown at all.
--merge::
After a failed merge, show refs that touch files having a
@@ -308,8 +316,6 @@ ifdef::git-rev-list[]
`<header>` text will be printed with each progress update.
endif::git-rev-list[]
---
-
History Simplification
~~~~~~~~~~~~~~~~~~~~~~
@@ -575,6 +581,7 @@ above) if (1) they are referenced by tags, or (2) they change the
contents of the paths given on the command line. All other
commits are marked as TREESAME (subject to be simplified away).
+ifndef::git-shortlog[]
ifdef::git-rev-list[]
Bisection Helpers
~~~~~~~~~~~~~~~~~
@@ -630,8 +637,9 @@ This option can be used along with `--bisect-vars`, in this case,
after all the sorted commit objects, there will be the same text as if
`--bisect-vars` had been used alone.
endif::git-rev-list[]
+endif::git-shortlog[]
-
+ifndef::git-shortlog[]
Commit Ordering
~~~~~~~~~~~~~~~
@@ -673,7 +681,9 @@ together.
Output the commits chosen to be shown (see Commit Limiting
section above) in reverse order. Cannot be combined with
`--walk-reflogs`.
+endif::git-shortlog[]
+ifndef::git-shortlog[]
Object Traversal
~~~~~~~~~~~~~~~~
@@ -712,6 +722,16 @@ ifdef::git-rev-list[]
Only useful with `--objects`; print the object IDs that are not
in packs.
+--object-names::
+ Only useful with `--objects`; print the names of the object IDs
+ that are found. This is the default behavior.
+
+--no-object-names::
+ Only useful with `--objects`; does not print the names of the object
+ IDs that are found. This inverts `--object-names`. This flag allows
+ the output to be more easily parsed by commands such as
+ linkgit:git-cat-file[1].
+
--filter=<filter-spec>::
Only useful with one of the `--objects*`; omits objects (usually
blobs) from the list of printed objects. The '<filter-spec>'
@@ -729,15 +749,42 @@ specification contained in the blob (or blob-expression) '<blob-ish>'
to omit blobs that would not be not required for a sparse checkout on
the requested refs.
+
-The form '--filter=sparse:path=<path>' similarly uses a sparse-checkout
-specification contained in <path>.
+The form '--filter=tree:<depth>' omits all blobs and trees whose depth
+from the root tree is >= <depth> (minimum depth if an object is located
+at multiple depths in the commits traversed). <depth>=0 will not include
+any trees or blobs unless included explicitly in the command-line (or
+standard input when --stdin is used). <depth>=1 will include only the
+tree and blobs which are referenced directly by a commit reachable from
+<commit> or an explicitly-given object. <depth>=2 is like <depth>=1
+while also including trees and blobs one more level removed from an
+explicitly-given commit or tree.
++
+Note that the form '--filter=sparse:path=<path>' that wants to read
+from an arbitrary path on the filesystem has been dropped for security
+reasons.
++
+Multiple '--filter=' flags can be specified to combine filters. Only
+objects which are accepted by every filter are included.
++
+The form '--filter=combine:<filter1>+<filter2>+...<filterN>' can also be
+used to combined several filters, but this is harder than just repeating
+the '--filter' flag and is usually not necessary. Filters are joined by
+'{plus}' and individual filters are %-encoded (i.e. URL-encoded).
+Besides the '{plus}' and '%' characters, the following characters are
+reserved and also must be encoded: `~!@#$^&*()[]{}\;",<>?`+&#39;&#96;+
+as well as all characters with ASCII code &lt;= `0x20`, which includes
+space and newline.
++
+Other arbitrary characters can also be encoded. For instance,
+'combine:tree:3+blob:none' and 'combine:tree%3A3+blob%3Anone' are
+equivalent.
--no-filter::
Turn off any previous `--filter=` argument.
--filter-print-omitted::
Only useful with `--filter=`; prints a list of the objects omitted
- by the filter. Object IDs are prefixed with a ``~'' character.
+ by the filter. Object IDs are prefixed with a ``~'' character.
--missing=<missing-action>::
A debug option to help with future "partial clone" development.
@@ -756,7 +803,6 @@ Unexpected missing objects will raise an error.
+
The form '--missing=print' is like 'allow-any', but will also print a
list of the missing objects. Object IDs are prefixed with a ``?'' character.
-endif::git-rev-list[]
--exclude-promisor-objects::
(For internal use only.) Prefilter object traversal at
@@ -764,6 +810,7 @@ endif::git-rev-list[]
stronger than `--missing=allow-promisor` because it limits the
traversal, rather than just silencing errors about missing
objects.
+endif::git-rev-list[]
--no-walk[=(sorted|unsorted)]::
Only show the given commits, but do not traverse their ancestors.
@@ -776,7 +823,9 @@ endif::git-rev-list[]
--do-walk::
Overrides a previous `--no-walk`.
+endif::git-shortlog[]
+ifndef::git-shortlog[]
Commit Formatting
~~~~~~~~~~~~~~~~~
@@ -799,12 +848,13 @@ include::pretty-options.txt[]
author's). If `-local` is appended to the format (e.g.,
`iso-local`), the user's local time zone is used instead.
+
+--
`--date=relative` shows dates relative to the current time,
e.g. ``2 hours ago''. The `-local` option has no effect for
`--date=relative`.
-+
+
`--date=local` is an alias for `--date=default-local`.
-+
+
`--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format.
The differences to the strict ISO 8601 format are:
@@ -812,15 +862,14 @@ The differences to the strict ISO 8601 format are:
- a space between time and time zone
- no colon between hours and minutes of the time zone
-+
`--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict
ISO 8601 format.
-+
+
`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822
format, often found in email messages.
-+
+
`--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format.
-+
+
`--date=raw` shows the date as seconds since the epoch (1970-01-01
00:00:00 UTC), followed by a space, and then the timezone as an offset
from UTC (a `+` or `-` with four digits; the first two are hours, and
@@ -829,21 +878,28 @@ with `strftime("%s %z")`).
Note that the `-local` option does not affect the seconds-since-epoch
value (which is always measured in UTC), but does switch the accompanying
timezone value.
-+
+
+`--date=human` shows the timezone if the timezone does not match the
+current time-zone, and doesn't print the whole date if that matches
+(ie skip printing year for dates that are "this year", but also skip
+the whole date itself if it's in the last few days and we can just say
+what weekday it was). For older dates the hour and minute is also
+omitted.
+
`--date=unix` shows the date as a Unix epoch timestamp (seconds since
1970). As with `--raw`, this is always in UTC and therefore `-local`
has no effect.
-+
+
`--date=format:...` feeds the format `...` to your system `strftime`,
except for %z and %Z, which are handled internally.
Use `--date=format:%c` to show the date in your system locale's
preferred format. See the `strftime` manual for a complete list of
format placeholders. When using `-local`, the correct syntax is
`--date=format-local:...`.
-+
+
`--date=default` is the default format, and is similar to
`--date=rfc2822`, with a few exceptions:
-
+--
- there is no comma after the day-of-week
- the time zone is omitted when the local time zone is used
@@ -925,7 +981,9 @@ ifdef::git-rev-list[]
counts and print the count for equivalent commits separated
by a tab.
endif::git-rev-list[]
+endif::git-shortlog[]
+ifndef::git-shortlog[]
ifndef::git-rev-list[]
Diff Formatting
~~~~~~~~~~~~~~~
@@ -947,6 +1005,13 @@ options may be given. See linkgit:git-diff-files[1] for more options.
the parents have only two variants and the merge result picks
one of them without modification.
+--combined-all-paths::
+ This flag causes combined diffs (used for merge commits) to
+ list the name of the file from all parents. It thus only has
+ effect when -c or --cc are specified, and is likely only
+ useful if filename changes are detected (i.e. when either
+ rename or copy detection have been requested).
+
-m::
This flag makes the merge commits show the full diff like
regular commits; for each merge parent, a separate log entry
@@ -961,3 +1026,4 @@ options may be given. See linkgit:git-diff-files[1] for more options.
-t::
Show the tree objects in the diff output. This implies `-r`.
endif::git-rev-list[]
+endif::git-shortlog[]