path: root/Documentation/git-rev-list.txt
AgeCommit message (Collapse)Author
2021-02-18docs/rev-list: add some examples of --disk-usageJeff King
It's not immediately obvious why --disk-usage might be a useful thing. These examples show off a few of the real-world cases I've used it for. Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
2021-02-18docs/rev-list: add an examples sectionJeff King
We currently don't show any examples of using git-rev-list at all. Let's add some pretty elementary examples. They likely seem obvious to anybody who has worked with the tool for a while, but my purpose here is two-fold: - they may be enlightening to people who haven't used the tool a lot to give a general flavor of how it is meant to be used - they can serve as a starting point for adding more interesting examples (we can do that without the basic ones, of course, but I think it makes sense to show off the building blocks) This set is far from exhaustive, but again, the purpose is to be a starting point for further additions. Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
2020-07-09git-log.txt: include rev-list-description.txtPhilippe Blain
The `git log` synopsis mentions `<revision range>`, and the description of this option links to gitrevisions(7), but a nice explanation of how a revision range can be constructed from individual commits, optionnally prefixed with `^`, also exists in `rev-list-description.txt`. Include this description in the man page for `git log`. Add Asciidoc 'ifdef's to `rev-list-description.txt` so that either `git rev-list` or `git log` appears in the respective man pages. Signed-off-by: Philippe Blain <> Signed-off-by: Junio C Hamano <>
2020-07-09git-rev-list.txt: move description to separate filePhilippe Blain
A following commit will reuse the description of the `git rev-list` command in the `git log` manpage. Move this description to a separate file. Signed-off-by: Philippe Blain <> Signed-off-by: Junio C Hamano <>
2020-07-09git-rev-list.txt: tweak wording in set operationsPhilippe Blain
Tweak a sentence to make it a little more readable. Signed-off-by: Philippe Blain <> Signed-off-by: Junio C Hamano <>
2020-07-09git-rev-list.txt: fix Asciidoc syntaxPhilippe Blain
Using '{caret}' inside double quotes and immediately following with a single quoted word does not create the desired output: '<commit1>' appears verbatim instead of being emphasized. Use a litteral caret ('^') instead. Also, remove the leading tabs in shell examples to bring them more in line with the rest of the documentation. Signed-off-by: Philippe Blain <> Signed-off-by: Junio C Hamano <>
2019-10-06git-rev-list.txt: prune options in synopsisDenton Liu
The synopsis section in git-rev-list.txt has grown to be a huge list that probably needs its own synopsis. Since the list is huge, users may be given the false impression that the list is complete, however it is not. It is missing many of the available options. Since the list of options in the synopsis is not only annoying but actively harmful, replace it with `[<options>]` so users know to explicitly look through the documentation for further information. While we're at it, update the optional path notation so that it is more modern. Signed-off-by: Denton Liu <> Signed-off-by: Junio C Hamano <>
2019-06-20rev-list: teach --no-object-names to enable pipingEmily Shaffer
Allow easier parsing by cat-file by giving rev-list an option to print only the OID of a non-commit object without any additional information. This is a short-term shim; later on, rev-list should be taught how to print the types of objects it finds in a format similar to cat-file's. Before this commit, the output from rev-list needed to be massaged before being piped to cat-file, like so: git rev-list --objects HEAD | cut -f 1 -d ' ' | git cat-file --batch-check This was especially unexpected when dealing with root trees, as an invisible whitespace exists at the end of the OID: git rev-list --objects --filter=tree:1 --max-count=1 HEAD | xargs -I% echo "AA%AA" Now, it can be piped directly, as in the added test case: git rev-list --objects --no-object-names HEAD | git cat-file --batch-check Signed-off-by: Emily Shaffer <> Change-Id: I489bdf0a8215532e540175188883ff7541d70e1b Signed-off-by: Junio C Hamano <>
2017-11-22rev-list: add list-objects filtering supportJeff Hostetler
Teach rev-list to use the filtering provided by the traverse_commit_list_filtered() interface to omit unwanted objects from the result. Object filtering is only allowed when one of the "--objects*" options are used. When the "--filter-print-omitted" option is used, the omitted objects are printed at the end. These are marked with a "~". This option can be combined with "--quiet" to get a list of just the omitted objects. Add t6112 test. In the future, we will introduce a "partial clone" mechanism wherein an object in a repo, obtained from a remote, may reference a missing object that can be dynamically fetched from that remote once needed. This "partial clone" mechanism will have a way, sometimes slow, of determining if a missing link is one of the links expected to be produced by this mechanism. This patch introduces handling of missing objects to help debugging and development of the "partial clone" mechanism, and once the mechanism is implemented, for a power user to perform operations that are missing-object aware without incurring the cost of checking if a missing link is expected. Signed-off-by: Jeff Hostetler <> Reviewed-by: Jonathan Tan <> Signed-off-by: Junio C Hamano <>
2015-10-05Merge branch 'jk/date-local'Junio C Hamano
"git log --date=local" used to only show the normal (default) format in the local timezone. The command learned to take 'local' as an instruction to use the local timezone with other formats, e.g. "git show --date=rfc-local". * jk/date-local: t6300: add tests for "-local" date formats t6300: make UTC and local dates different date: make "local" orthogonal to date format date: check for "local" before anything else t6300: add test for "raw" date format t6300: introduce test_date() helper fast-import: switch crash-report date to iso8601 Documentation/rev-list: don't list date formats Documentation/git-for-each-ref: don't list date formats Documentation/config: don't list date formats Documentation/blame-options: don't list date formats
2015-09-03Documentation/rev-list: don't list date formatsJohn Keeping
We are about to add several new date formats which will make this list too long to display in a single line. Signed-off-by: John Keeping <> Signed-off-by: Junio C Hamano <>
2015-07-01rev-list: add --count to usage guideLawrence Siebert
--count should be mentioned in the usage guide, this updates code and documentation. Signed-off-by: Lawrence Siebert <> Signed-off-by: Junio C Hamano <>
2015-05-13doc: convert \--option to --optionJeff King
Older versions of AsciiDoc would convert the "--" in "--option" into an emdash. According to 565e135 (Documentation: quote double-dash for AsciiDoc, 2011-06-29), this is fixed in AsciiDoc 8.3.0. According to bf17126, we don't support anything older than 8.4.1 anyway, so we no longer need to worry about quoting. Even though this does not change the output at all, there are a few good reasons to drop the quoting: 1. It makes the source prettier to read. 2. We don't quote consistently, which may be confusing when reading the source. 3. Asciidoctor does not like the quoting, and renders a literal backslash. Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
2014-12-29rev-list: add an option to mark fewer edges as uninterestingbrian m. carlson
In commit fbd4a70 (list-objects: mark more commits as edges in mark_edges_uninteresting - 2013-08-16), we marked an increasing number of edges uninteresting. This change, and the subsequent change to make this conditional on --objects-edge, are used by --thin to make much smaller packs for shallow clones. Unfortunately, they cause a significant performance regression when pushing non-shallow clones with lots of refs (23.322 seconds vs. 4.785 seconds with 22400 refs). Add an option to git rev-list, --objects-edge-aggressive, that preserves this more aggressive behavior, while leaving --objects-edge to provide more performant behavior. Preserve the current behavior for the moment by using the aggressive option. Signed-off-by: brian m. carlson <> Signed-off-by: Junio C Hamano <>
2014-08-29pretty: provide a strict ISO 8601 date formatBeat Bolli
Git's "ISO" date format does not really conform to the ISO 8601 standard due to small differences, and it cannot be parsed by ISO 8601-only parsers, e.g. those of XML toolchains. The output from "--date=iso" deviates from ISO 8601 in these ways: - a space instead of the `T` date/time delimiter - a space between time and time zone - no colon between hours and minutes of the time zone Add a strict ISO 8601 date format for displaying committer and author dates. Use the '%aI' and '%cI' format specifiers and add '--date=iso-strict' or '--date=iso8601-strict' date format names. See and for discussion. Signed-off-by: Beat Bolli <> Signed-off-by: Junio C Hamano <>
2013-12-30rev-list: add bitmap mode to speed up object listsVicent Marti
The bitmap reachability index used to speed up the counting objects phase during `pack-objects` can also be used to optimize a normal rev-list if the only thing required are the SHA1s of the objects during the list (i.e., not the path names at which trees and blobs were found). Calling `git rev-list --objects --use-bitmap-index [committish]` will perform an object iteration based on a bitmap result instead of actually walking the object graph. These are some example timings for `torvalds/linux` (warm cache, best-of-five): $ time git rev-list --objects master > /dev/null real 0m34.191s user 0m33.904s sys 0m0.268s $ time git rev-list --objects --use-bitmap-index master > /dev/null real 0m1.041s user 0m0.976s sys 0m0.064s Likewise, using `git rev-list --count --use-bitmap-index` will speed up the counting operation by building the resulting bitmap and performing a fast popcount (number of bits set on the bitmap) on the result. Here are some sample timings of different ways to count commits in `torvalds/linux`: $ time git rev-list master | wc -l 399882 real 0m6.524s user 0m6.060s sys 0m3.284s $ time git rev-list --count master 399882 real 0m4.318s user 0m4.236s sys 0m0.076s $ time git rev-list --use-bitmap-index --count master 399882 real 0m0.217s user 0m0.176s sys 0m0.040s This also respects negative refs, so you can use it to count a slice of history: $ time git rev-list --count v3.0..master 144843 real 0m1.971s user 0m1.932s sys 0m0.036s $ time git rev-list --use-bitmap-index --count v3.0..master real 0m0.280s user 0m0.220s sys 0m0.056s Though note that the closer the endpoints, the less it helps. In the traversal case, we have fewer commits to cross, so we take less time. But the bitmap time is dominated by generating the pack revindex, which is constant with respect to the refs given. Note that you cannot yet get a fast --left-right count of a symmetric difference (e.g., "--count --left-right master...topic"). The slow part of that walk actually happens during the merge-base determination when we parse "master...topic". Even though a count does not actually need to know the real merge base (it only needs to take the symmetric difference of the bitmaps), the revision code would require some refactoring to handle this case. Additionally, a `--test-bitmap` flag has been added that will perform the same rev-list manually (i.e. using a normal revwalk) and using bitmaps, and verify that the results are the same. This can be used to exercise the bitmap code, and also to verify that the contents of the .bitmap file are sane. Signed-off-by: Vicent Marti <> Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
2013-08-05log doc: the argument to --encoding is not optionalJonathan Nieder
$ git log --encoding fatal: Option '--encoding' requires a value $ git rev-list --encoding fatal: Option '--encoding' requires a value The argument to --encoding has always been mandatory. Unfortunately manpages like git-rev-list(1), git-log(1), and git-show(1) have described the option's syntax as "--encoding[=<encoding>]" since it was first documented. Clarify by removing the extra brackets. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2013-02-01Documentation: the name of the system is 'Git', not 'git'Thomas Ackermann
Signed-off-by: Thomas Ackermann <> Signed-off-by: Junio C Hamano <>
2011-05-19show: --ignore-missingJunio C Hamano
Instead of barfing, simply ignore bad object names seen in the input. This is useful when reading from "git notes list" output that may refer to objects that have already been garbage collected. Signed-off-by: Junio C Hamano <>
2011-03-27Merge branch 'mg/rev-list-n-parents'Junio C Hamano
* mg/rev-list-n-parents: tests: avoid nonportable {foo,bar} glob rev-list --min-parents,--max-parents: doc, test and completion revision.c: introduce --min-parents and --max-parents options t6009: use test_commit() from
2011-03-23rev-list --min-parents,--max-parents: doc, test and completionMichael J Gruber
This also adds test for "--merges" and "--no-merges" which we did not have so far. Signed-off-by: Michael J Gruber <> Signed-off-by: Junio C Hamano <>
2011-03-23Merge branch 'mg/rev-list-one-side-only'Junio C Hamano
* mg/rev-list-one-side-only: git-log: put space after commit mark t6007: test rev-list --cherry log --cherry: a synonym rev-list: documentation and test for --cherry-mark revision.c: introduce --cherry-mark rev-list/log: factor out revision mark generation rev-list: --left/right-only are mutually exclusive rev-list: documentation and test for --left/right-only t6007: Make sure we test --cherry-pick revlist.c: introduce --left/right-only for unsymmetric picking
2011-03-11doc: drop author/documentation sections from most pagesJeff King
The point of these sections is generally to: 1. Give credit where it is due. 2. Give the reader an idea of where to ask questions or file bug reports. But they don't do a good job of either case. For (1), they are out of date and incomplete. A much more accurate answer can be gotten through shortlog or blame. For (2), the correct contact point is generally git@vger, and even if you wanted to cc the contact point, the out-of-date and incomplete fields mean you're likely sending to somebody useless. So let's drop the fields entirely from all manpages except git(1) itself. We already point people to the mailing list for bug reports there, and we can update the Authors section to give credit to the major contributors and point to shortlog and blame for more information. Each page has a "This is part of git" footer, so people can follow that to the main git manpage.
2011-03-09rev-list: documentation and test for --cherry-markMichael J Gruber
Signed-off-by: Michael J Gruber <> Signed-off-by: Junio C Hamano <>
2011-02-22rev-list: documentation and test for --left/right-onlyMichael J Gruber
Signed-off-by: Michael J Gruber <> Signed-off-by: Junio C Hamano <>
2010-10-08Use parentheses and `...' where appropriateŠtěpán Němec
Remove some stray usage of other bracket types and asterisks for the same purpose. Signed-off-by: Štěpán Němec <> Acked-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2010-10-08Use angles for placeholders consistentlyŠtěpán Němec
Signed-off-by: Štěpán Němec <> Acked-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2010-01-23Documentation: rev-list: fix synopsys for --tags and and --remotesChristian Couder
Signed-off-by: Christian Couder <> Signed-off-by: Junio C Hamano <>
2010-01-23Merge branch 'il/rev-glob'Junio C Hamano
* il/rev-glob: Documentation: improve description of --glob=pattern and friends rev-parse --branches/--tags/--remotes=pattern rev-parse --glob
2010-01-20rev-parse --branches/--tags/--remotes=patternIlari Liusvaara
Since local branch, tags and remote tracking branch namespaces are most often used, add shortcut notations for globbing those in manner similar to --glob option. With this, one can express the "what I have but origin doesn't?" as: 'git log --branches --not --remotes=origin' Original-idea-by: Johannes Sixt <> Signed-off-by: Ilari Liusvaara <> Signed-off-by: Junio C Hamano <>
2010-01-20rev-parse --globIlari Liusvaara
Add --glob=<glob-pattern> option to rev-parse and everything that accepts its options. This option matches all refs that match given shell glob pattern (complete with some DWIM logic). Example: 'git log --branches --not --glob=remotes/origin' To show what you have that origin doesn't. Signed-off-by: Ilari Liusvaara <> Signed-off-by: Junio C Hamano <>
2010-01-10Documentation: spell 'git cmd' without dash throughoutThomas Rast
The documentation was quite inconsistent when spelling 'git cmd' if it only refers to the program, not to some specific invocation syntax: both 'git-cmd' and 'git cmd' spellings exist. The current trend goes towards dashless forms, and there is precedent in 647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07) to actively eliminate the dashed variants. Replace 'git-cmd' with 'git cmd' throughout, except where git-shell, git-cvsserver, git-upload-pack, git-receive-pack, and git-upload-archive are concerned, because those really live in the $PATH.
2009-08-12Merge branch 'maint'Junio C Hamano
* maint: push: point to 'git pull' and 'git push --force' in case of non-fast forward Documentation: add: <filepattern>... is optional Change mentions of "git programs" to "git commands" Documentation: merge: one <remote> is required help.c: give correct structure's size to memset()
2009-08-12Merge branch 'maint-1.6.3' into maintJunio C Hamano
* maint-1.6.3: Change mentions of "git programs" to "git commands" Documentation: merge: one <remote> is required help.c: give correct structure's size to memset()
2009-08-12Change mentions of "git programs" to "git commands"Ori Avtalion
Most of the docs and printouts refer to "commands" when discussing what the end users call via the "git" top-level program. We should refer them as "git programs" when we discuss the fact that the commands are implemented as separate programs, but in other contexts, it is better to use the term "git commands" consistently. Signed-off-by: Ori Avtalion <> Signed-off-by: Nanako Shiraishi <> Signed-off-by: Junio C Hamano <>
2009-08-06git-rev-list.txt: Clarify the use of multiple revision argumentsJunio C Hamano
If one thinks of a revision as the set of commits which can be reached from the rev, and of ^rev as the complement, then multiple arguments to git rev-list can be neither understood as the intersection nor the union of the individual sets. But set language is the natural as well as logical language in which to phrase this. So, add a paragraph which explains multiple arguments using set language. Suggested-by: Michael J Gruber <> Signed-off-by: Junio C Hamano <>
2009-07-13Document 'git (rev-list|log) --merges'SZEDER Gábor
Signed-off-by: SZEDER Gábor <> Signed-off-by: Junio C Hamano <>
2008-10-01Documentation: remove '\' in front of short optionsSZEDER Gábor
... because they show up in the man and html outputs. This escaping is only needed for double dashes to be compatible with older asciidoc versions; see commit e1ccf53 ([PATCH] Escape asciidoc's built-in em-dash replacement, 2005-09-12). Signed-off-by: SZEDER Gábor <> Signed-off-by: Shawn O. Pearce <>
2008-07-05manpages: italicize git command names (which were in teletype font)Jonathan Nieder
The names of git commands are not meant to be entered at the commandline; they are just names. So we render them in italics, as is usual for command names in manpages. Using doit () { perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }' } for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \ merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt do doit <"$i" >"$i+" && mv "$i+" "$i" done git diff . Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-07-02Documentation formatting and cleanupJonathan Nieder
Following what appears to be the predominant style, format names of commands and commandlines both as `teletype text`. While we're at it, add articles ("a" and "the") in some places, italicize the name of the command in the manual page synopsis line, and add a comma or two where it seems appropriate. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-07-02Documentation: be consistent about "git-" versus "git "Jonathan Nieder
Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2008-06-06documentation: move git(7) to git(1)Christian Couder
As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder <> Signed-off-by: Junio C Hamano <>
2008-02-29rev-list: add --branches, --tags and --remotesUwe Kleine-König
These flags are already known to rev-parse and have the same meaning. This patch allows to run gitk as follows: gitk --branches --not --remotes to show only your local work. Signed-off-by: Uwe Kleine-König <> Signed-off-by: Junio C Hamano <>
2008-02-27Add '--fixed-strings' option to "git log --grep" and friendsJakub Narebski
Add support for -F | --fixed-strings option to "git log --grep" and friends: "git log --author", "git log --committer=<pattern>". Code is based on implementation of this option in "git grep". Signed-off-by: Jakub Narebski <> Signed-off-by: Junio C Hamano <>
2008-01-18Include rev-list options in git-log manpage.Miklos Vajna
Replace the "This manual page describes only the most frequently used options." text with the list of rev-list options in git-log manpage. (The git-diff-tree options are already included.) Move these options to a separate file and include it from both git-rev-list.txt and git-log.txt. Signed-off-by: Miklos Vajna <> Signed-off-by: Junio C Hamano <>
2008-01-07Documentation: rename gitlink macro to linkgitDan McGee
Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <> Signed-off-by: Junio C Hamano <>
2007-12-27Fix documentation of --first-parent in git-log and copy it to git-rev-listJunio C Hamano
Credit goes to Avi Kivity for noticing the lack of description in rev-list manual page. Signed-off-by: Junio C Hamano <>
2007-12-18Fix some documentation typos.Ralf Wildenhues
Signed-off-by: Ralf Wildenhues <> Signed-off-by: Junio C Hamano <>
2007-11-12rev-list: Introduce --quiet to avoid /dev/null redirectsShawn O. Pearce
Some uses of git-rev-list are to run it with --objects to see if a range of objects between two or more commits is fully connected or not. In such a case the caller doesn't care about the actual object names or hash hints so formatting this data only for it to be dumped to /dev/null by a redirect is a waste of CPU time. If all the caller needs is the exit status then --quiet can be used to bypass the commit and object formatting. Signed-off-by: Shawn O. Pearce <>
2007-10-27rev-list documentation: add "--bisect-all".Christian Couder
Signed-off-by: Christian Couder <> Signed-off-by: Shawn O. Pearce <>