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.txt138
1 files changed, 118 insertions, 20 deletions
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index f39cb6d..7b27363 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -91,9 +91,14 @@ endif::git-rev-list[]
Consider the limiting patterns to be fixed strings (don't interpret
pattern as a regular expression).
+-P::
--perl-regexp::
- Consider the limiting patterns to be Perl-compatible regular expressions.
- Requires libpcre to be compiled in.
+ Consider the limiting patterns to be Perl-compatible regular
+ expressions.
++
+Support for these types of regular expressions is an optional
+compile-time dependency. If Git wasn't compiled with support for them
+providing this option will cause it to die.
--remove-empty::
Stop when a given path disappears from the tree.
@@ -133,8 +138,8 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit).
for all following revision specifiers, up to the next `--not`.
--all::
- Pretend as if all the refs in `refs/` are listed on the
- command line as '<commit>'.
+ Pretend as if all the refs in `refs/`, along with `HEAD`, are
+ listed on the command line as '<commit>'.
--branches[=<pattern>]::
Pretend as if all the refs in `refs/heads` are listed
@@ -179,6 +184,14 @@ explicitly.
Pretend as if all objects mentioned by reflogs are listed on the
command line as `<commit>`.
+--single-worktree::
+ By default, all working trees will be examined by the
+ following options when there are more than one (see
+ linkgit:git-worktree[1]): `--all`, `--reflog` and
+ `--indexed-objects`.
+ This option forces them to examine the current working tree
+ only.
+
--ignore-missing::
Upon seeing an invalid object name in the input, pretend as if
the bad input was not given.
@@ -225,7 +238,7 @@ excluded from the output.
--left-only::
--right-only::
- List only commits on the respective side of a symmetric range,
+ List only commits on the respective side of a symmetric difference,
i.e. only those which would be marked `<` resp. `>` by
`--left-right`.
+
@@ -252,10 +265,25 @@ list.
+
With `--pretty` format other than `oneline` (for obvious reasons),
this causes the output to have two extra lines of information
-taken from the reflog. By default, 'commit@\{Nth}' notation is
-used in the output. When the starting commit is specified as
-'commit@\{now}', output also uses 'commit@\{timestamp}' notation
-instead. Under `--pretty=oneline`, the commit message is
+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
+reflog) or as `ref@{timestamp}` (with the timestamp for that entry),
+depending on a few rules:
++
+--
+1. If the starting point is specified as `ref@{Nth}`, show the index
+format.
++
+2. If the starting point was specified as `ref@{now}`, show the
+timestamp format.
++
+3. If neither was used, but `--date` was given on the command line, show
+the timestamp in the format requested by `--date`.
++
+4. Otherwise, show the index format.
+--
++
+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].
@@ -642,8 +670,9 @@ avoid showing the commits from two parallel development track mixed
together.
--reverse::
- Output the commits in reverse order.
- Cannot be combined with `--walk-reflogs`.
+ Output the commits chosen to be shown (see Commit Limiting
+ section above) in reverse order. Cannot be combined with
+ `--walk-reflogs`.
Object Traversal
~~~~~~~~~~~~~~~~
@@ -657,6 +686,11 @@ ifdef::git-rev-list[]
all object IDs which I need to download if I have the commit
object _bar_ but not _foo_''.
+--in-commit-order::
+ Print tree and blob ids in order of the commits. The tree
+ and blob ids are printed after they are first referenced
+ by a commit.
+
--objects-edge::
Similar to `--objects`, but also print the IDs of excluded
commits prefixed with a ``-'' character. This is used by
@@ -677,8 +711,60 @@ ifdef::git-rev-list[]
--unpacked::
Only useful with `--objects`; print the object IDs that are not
in packs.
+
+--filter=<filter-spec>::
+ Only useful with one of the `--objects*`; omits objects (usually
+ blobs) from the list of printed objects. The '<filter-spec>'
+ may be one of the following:
++
+The form '--filter=blob:none' omits all blobs.
++
+The form '--filter=blob:limit=<n>[kmg]' omits blobs larger than n bytes
+or units. n may be zero. The suffixes k, m, and g can be used to name
+units in KiB, MiB, or GiB. For example, 'blob:limit=1k' is the same
+as 'blob:limit=1024'.
++
+The form '--filter=sparse:oid=<blob-ish>' uses a sparse-checkout
+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>.
+
+--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.
+
+--missing=<missing-action>::
+ A debug option to help with future "partial clone" development.
+ This option specifies how missing objects are handled.
++
+The form '--missing=error' requests that rev-list stop with an error if
+a missing object is encountered. This is the default action.
++
+The form '--missing=allow-any' will allow object traversal to continue
+if a missing object is encountered. Missing objects will silently be
+omitted from the results.
++
+The form '--missing=allow-promisor' is like 'allow-any', but will only
+allow object traversal to continue for EXPECTED promisor missing objects.
+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
+ promisor boundary. This is used with partial clone. This is
+ stronger than `--missing=allow-promisor` because it limits the
+ traversal, rather than just silencing errors about missing
+ objects.
+
--no-walk[=(sorted|unsorted)]::
Only show the given commits, but do not traverse their ancestors.
This has no effect if a range is specified. If the argument
@@ -714,8 +800,8 @@ include::pretty-options.txt[]
`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 cannot be used with
-`--raw` or `--relative`.
+e.g. ``2 hours ago''. The `-local` option has no effect for
+`--date=relative`.
+
`--date=local` is an alias for `--date=default-local`.
+
@@ -735,9 +821,21 @@ 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 in the internal raw Git format `%s %z` format.
-+
-`--date=format:...` feeds the format `...` to your system `strftime`.
+`--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
+the second two are minutes). I.e., as if the timestamp were formatted
+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=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
@@ -758,11 +856,11 @@ endif::git-rev-list[]
--parents::
Print also the parents of the commit (in the form "commit parent...").
- Also enables parent rewriting, see 'History Simplification' below.
+ Also enables parent rewriting, see 'History Simplification' above.
--children::
Print also the children of the commit (in the form "commit child...").
- Also enables parent rewriting, see 'History Simplification' below.
+ Also enables parent rewriting, see 'History Simplification' above.
ifdef::git-rev-list[]
--timestamp::
@@ -770,7 +868,7 @@ ifdef::git-rev-list[]
endif::git-rev-list[]
--left-right::
- Mark which side of a symmetric diff a commit is reachable from.
+ Mark which side of a symmetric difference a commit is reachable from.
Commits from the left side are prefixed with `<` and those from
the right with `>`. If combined with `--boundary`, those
commits are prefixed with `-`.
@@ -805,7 +903,7 @@ you would get an output like this:
to be drawn properly.
Cannot be combined with `--no-walk`.
+
-This enables parent rewriting, see 'History Simplification' below.
+This enables parent rewriting, see 'History Simplification' above.
+
This implies the `--topo-order` option by default, but the
`--date-order` option may also be specified.