Documentation: rev-list-options: Rewrite simplification descriptions for clarity
This completely rewrites the documentation of --full-history with lots of examples. Signed-off-by: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Thomas Rast committed
Aug 12, 2008 at 01:55 UTC
70d9895ebcb8d401b569d28f049ad37fcb7b5ade
1 file changed
+136
-17
Documentation/rev-list-options.txt
+136
-17
@@ -43,11 +43,13 @@ endif::git-rev-list[]
43
44
--parents::
45
46
- Print the parents of the commit.
46
+ Print the parents of the commit. Also enables parent
47
+ rewriting, see 'History Simplification' below.
48
49
--children::
50
50
- Print the children of the commit.
51
+ Print the children of the commit. Also enables parent
52
+ rewriting, see 'History Simplification' below.
53
54
ifdef::git-rev-list[]
55
--timestamp::
@@ -191,14 +193,6 @@ endif::git-rev-list[]
193
194
Stop when a given path disappears from the tree.
195
194
---full-history::
195
-
196
- Show also parts of history irrelevant to current state of a given
197
- path. This turns off history simplification, which removed merges
198
- which didn't change anything at all at some child. It will still actually
199
- simplify away merges that didn't change anything at all into either
200
- child.
201
-
196
--no-merges::
197
198
Do not print commits with more than one parent.
@@ -280,18 +274,144 @@ See also linkgit:git-reflog[1].
274
Output uninteresting commits at the boundary, which are usually
275
not shown.
276
277
+--
278
+
279
+History Simplification
280
+~~~~~~~~~~~~~~~~~~~~~~
281
+
282
+When optional paths are given, 'git-rev-list' simplifies commits with
283
+various strategies, according to the options you have selected.
284
+
285
+Suppose you specified `foo` as the <paths>. We shall call commits
286
+that modify `foo` !TREESAME, and the rest TREESAME. (In a diff
287
+filtered for `foo`, they look different and equal, respectively.)
288
+
289
+In the following, we will always refer to the same example history to
290
+illustrate the differences between simplification settings. We assume
291
+that you are filtering for a file `foo` in this commit graph:
292
+-----------------------------------------------------------------------
293
+ .-A---M---N---O---P
294
+ / / / / /
295
+ I B C D E
296
+ \ / / / /
297
+ `-------------'
298
+-----------------------------------------------------------------------
299
+The horizontal line of history A--P is taken to be the first parent of
300
+each merge. The commits are:
301
+
302
+* `I` is the initial commit, in which `foo` exists with contents
303
+ "asdf", and a file `quux` exists with contents "quux". Initial
304
+ commits are compared to an empty tree, so `I` is !TREESAME.
305
+
306
+* In `A`, `foo` contains just "foo".
307
+
308
+* `B` contains the same change as `A`. Its merge `M` is trivial and
309
+ hence TREESAME to all parents.
310
+
311
+* `C` does not change `foo`, but its merge `N` changes it to "foobar",
312
+ so it is not TREESAME to any parent.
313
+
314
+* `D` sets `foo` to "baz". Its merge `O` combines the strings from
315
+ `N` and `D` to "foobarbaz"; i.e., it is not TREESAME to any parent.
316
+
317
+* `E` changes `quux` to "xyzzy", and its merge `P` combines the
318
+ strings to "quux xyzzy". Despite appearing interesting, `P` is
319
+ TREESAME to all parents.
320
+
321
+'rev-list' walks backwards through history, including or excluding
322
+commits based on whether '\--full-history' and/or parent rewriting
323
+(via '\--parents' or '\--children') are used. The following settings
324
+are available.
325
+
326
+Default mode::
327
+
328
+ Commits are included if they are not TREESAME to any parent
329
+ (though this can be changed, see '\--sparse' below). If the
330
+ commit was a merge, and it was TREESAME to one parent, follow
331
+ only that parent. (Even if there are several TREESAME
332
+ parents, follow only one of them.) Otherwise, follow all
333
+ parents.
334
++
335
+This results in:
336
++
337
+-----------------------------------------------------------------------
338
+ .-A---N---O
339
+ / /
340
+ I---------D
341
+-----------------------------------------------------------------------
342
++
343
+Note how the rule to only follow the TREESAME parent, if one is
344
+available, removed `B` from consideration entirely. `C` was
345
+considered via `N`, but is TREESAME. Root commits are compared to an
346
+empty tree, so `I` is !TREESAME.
347
++
348
+Parent/child relations are only visible with --parents, but that does
349
+not affect the commits selected in default mode, so we have shown the
350
+parent lines.
351
+
352
+--full-history without parent rewriting::
353
+
354
+ This mode differs from the default in one point: always follow
355
+ all parents of a merge, even if it is TREESAME to one of them.
356
+ Even if more than one side of the merge has commits that are
357
+ included, this does not imply that the merge itself is! In
358
+ the example, we get
359
++
360
+-----------------------------------------------------------------------
361
+ I A B N D O
362
+-----------------------------------------------------------------------
363
++
364
+`P` and `M` were excluded because they are TREESAME to a parent. `E`,
365
+`C` and `B` were all walked, but only `B` was !TREESAME, so the others
366
+do not appear.
367
++
368
+Note that without parent rewriting, it is not really possible to talk
369
+about the parent/child relationships between the commits, so we show
370
+them disconnected.
371
+
372
+--full-history with parent rewriting::
373
+
374
+ Ordinary commits are only included if they are !TREESAME
375
+ (though this can be changed, see '\--sparse' below).
376
++
377
+Merges are always included. However, their parent list is rewritten:
378
+Along each parent, prune away commits that are not included
379
+themselves. This results in
380
++
381
+-----------------------------------------------------------------------
382
+ .-A---M---N---O---P
383
+ / / / / /
384
+ I B / D /
385
+ \ / / / /
386
+ `-------------'
387
+-----------------------------------------------------------------------
388
++
389
+Compare to '\--full-history' without rewriting above. Note that `E`
390
+was pruned away because it is TREESAME, but the parent list of P was
391
+rewritten to contain `E`'s parent `I`. The same happened for `C` and
392
+`N`. Note also that `P` was included despite being TREESAME.
393
+
394
+In addition to the above settings, you can change whether TREESAME
395
+affects inclusion:
396
+
397
--dense::
398
+
399
+ Commits that are walked are included if they are not TREESAME
400
+ to any parent.
401
+
402
--sparse::
403
286
-When optional paths are given, the default behaviour ('--dense') is to
287
-only output commits that changes at least one of them, and also ignore
288
-merges that do not touch the given paths.
404
+ All commits that are walked are included.
405
++
406
+Note that without '\--full-history', this still simplifies merges: if
407
+one of the parents is TREESAME, we follow only that one, so the other
408
+sides of the merge are never walked.
409
290
-Use the '--sparse' flag to makes the command output all eligible commits
291
-(still subject to count and age limitation), but apply merge
292
-simplification nevertheless.
410
411
ifdef::git-rev-list[]
412
+Bisection Helpers
413
+~~~~~~~~~~~~~~~~~
414
+
415
--bisect::
416
417
Limit output to the one commit object which is roughly halfway between
@@ -341,7 +461,6 @@ after all the sorted commit objects, there will be the same text as if
461
`--bisect-vars` had been used alone.
462
endif::git-rev-list[]
463
344
---
464
465
Commit Ordering
466
~~~~~~~~~~~~~~~