X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Frev-list-options.txt;h=b9f6e4d1b7564480fac9c4e355fdc4936f6fa3db;hb=3ea95d2b0e6fa63e66de24a5084e217102ab9e8a;hp=5df35ce519e27e3fa20a0f3732ac4ddb58d9ab69;hpb=7756ba74c04caf03d47718d581439a48bae7ed73;p=git.git diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 5df35ce51..b9f6e4d1b 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -222,6 +222,21 @@ endif::git-rev-list[] Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the command line as ''. +--branches:: + + Pretend as if all the refs in `$GIT_DIR/refs/heads` are listed + on the command line as ''. + +--tags:: + + Pretend as if all the refs in `$GIT_DIR/refs/tags` are listed + on the command line as ''. + +--remotes:: + + Pretend as if all the refs in `$GIT_DIR/refs/remotes` are listed + on the command line as ''. + ifdef::git-rev-list[] --stdin:: @@ -285,8 +300,52 @@ See also linkgit:git-reflog[1]. History Simplification ~~~~~~~~~~~~~~~~~~~~~~ -When optional paths are given, 'git-rev-list' simplifies commits with -various strategies, according to the options you have selected. +Sometimes you are only interested in parts of the history, for example the +commits modifying a particular . But there are two parts of +'History Simplification', one part is selecting the commits and the other +is how to do it, as there are various strategies to simplify the history. + +The following options select the commits to be shown: + +:: + + Commits modifying the given are selected. + +--simplify-by-decoration:: + + Commits that are referred by some branch or tag are selected. + +Note that extra commits can be shown to give a meaningful history. + +The following options affect the way the simplification is performed: + +Default mode:: + + Simplifies the history to the simplest history explaining the + final state of the tree. Simplest because it prunes some side + branches if the end result is the same (i.e. merging branches + with the same content) + +--full-history:: + + As the default mode but does not prune some history. + +--dense:: + + Only the selected commits are shown, plus some to have a + meaningful history. + +--sparse:: + + All commits in the simplified history are shown. + +--simplify-merges:: + + Additional option to '--full-history' to remove some needless + merges from the resulting history, as there are no selected + commits contributing to this merge. + +A more detailed explanation follows. Suppose you specified `foo` as the . We shall call commits that modify `foo` !TREESAME, and the rest TREESAME. (In a diff @@ -413,6 +472,56 @@ Note that without '\--full-history', this still simplifies merges: if one of the parents is TREESAME, we follow only that one, so the other sides of the merge are never walked. +Finally, there is a fourth simplification mode available: + +--simplify-merges:: + + First, build a history graph in the same way that + '\--full-history' with parent rewriting does (see above). ++ +Then simplify each commit `C` to its replacement `C'` in the final +history according to the following rules: ++ +-- +* Set `C'` to `C`. ++ +* Replace each parent `P` of `C'` with its simplification `P'`. In + the process, drop parents that are ancestors of other parents, and + remove duplicates. ++ +* If after this parent rewriting, `C'` is a root or merge commit (has + zero or >1 parents), a boundary commit, or !TREESAME, it remains. + Otherwise, it is replaced with its only parent. +-- ++ +The effect of this is best shown by way of comparing to +'\--full-history' with parent rewriting. The example turns into: ++ +----------------------------------------------------------------------- + .-A---M---N---O + / / / + I B D + \ / / + `---------' +----------------------------------------------------------------------- ++ +Note the major differences in `N` and `P` over '\--full-history': ++ +-- +* `N`'s parent list had `I` removed, because it is an ancestor of the + other parent `M`. Still, `N` remained because it is !TREESAME. ++ +* `P`'s parent list similarly had `I` removed. `P` was then + removed completely, because it had one parent and is TREESAME. +-- + +The '\--simplify-by-decoration' option allows you to view only the +big picture of the topology of the history, by omitting commits +that are not referenced by tags. Commits are marked as !TREESAME +(in other words, kept after history simplification rules described +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). ifdef::git-rev-list[] Bisection Helpers @@ -424,14 +533,14 @@ Limit output to the one commit object which is roughly halfway between the included and excluded commits. Thus, if ----------------------------------------------------------------------- - $ git-rev-list --bisect foo ^bar ^baz + $ git rev-list --bisect foo ^bar ^baz ----------------------------------------------------------------------- outputs 'midpoint', the output of the two commands ----------------------------------------------------------------------- - $ git-rev-list foo ^midpoint - $ git-rev-list midpoint ^bar ^baz + $ git rev-list foo ^midpoint + $ git rev-list midpoint ^bar ^baz ----------------------------------------------------------------------- would be of roughly the same length. Finding the change which