diff options
| -rw-r--r-- | Documentation/rev-list-options.txt | 35 |
1 files changed, 19 insertions, 16 deletions
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 04ad7dd36e..b01b2b6773 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -581,12 +581,12 @@ option does. Applied to the 'D..M' range, it results in: Before discussing another option, `--show-pulls`, we need to create a new example history. -+ + A common problem users face when looking at simplified history is that a commit they know changed a file somehow does not appear in the file's simplified history. Let's demonstrate a new example and show how options such as `--full-history` and `--simplify-merges` works in that case: -+ + ----------------------------------------------------------------------- .-A---M-----C--N---O---P / / \ \ \/ / / @@ -595,7 +595,7 @@ such as `--full-history` and `--simplify-merges` works in that case: \ / /\ / `---X--' `---Y--' ----------------------------------------------------------------------- -+ + For this example, suppose `I` created `file.txt` which was modified by `A`, `B`, and `X` in different ways. The single-parent commits `C`, `Z`, and `Y` do not change `file.txt`. The merge commit `M` was created by @@ -607,19 +607,19 @@ the contents of `file.txt` at `X`. Hence, `R` is TREESAME to `X` but not contents of `file.txt` at `R`, so `N` is TREESAME to `R` but not `C`. The merge commits `O` and `P` are TREESAME to their first parents, but not to their second parents, `Z` and `Y` respectively. -+ + When using the default mode, `N` and `R` both have a TREESAME parent, so those edges are walked and the others are ignored. The resulting history graph is: -+ + ----------------------------------------------------------------------- I---X ----------------------------------------------------------------------- -+ + When using `--full-history`, Git walks every edge. This will discover the commits `A` and `B` and the merge `M`, but also will reveal the merge commits `O` and `P`. With parent rewriting, the resulting graph is: -+ + ----------------------------------------------------------------------- .-A---M--------N---O---P / / \ \ \/ / / @@ -628,21 +628,21 @@ merge commits `O` and `P`. With parent rewriting, the resulting graph is: \ / /\ / `---X--' `------' ----------------------------------------------------------------------- -+ + Here, the merge commits `O` and `P` contribute extra noise, as they did not actually contribute a change to `file.txt`. They only merged a topic that was based on an older version of `file.txt`. This is a common issue in repositories using a workflow where many contributors work in parallel and merge their topic branches along a single trunk: manu unrelated merges appear in the `--full-history` results. -+ + When using the `--simplify-merges` option, the commits `O` and `P` disappear from the results. This is because the rewritten second parents of `O` and `P` are reachable from their first parents. Those edges are removed and then the commits look like single-parent commits that are TREESAME to their parent. This also happens to the commit `N`, resulting in a history view as follows: -+ + ----------------------------------------------------------------------- .-A---M--. / / \ @@ -651,18 +651,18 @@ in a history view as follows: \ / / `---X--' ----------------------------------------------------------------------- -+ + In this view, we see all of the important single-parent changes from `A`, `B`, and `X`. We also see the carefully-resolved merge `M` and the not-so-carefully-resolved merge `R`. This is usually enough information to determine why the commits `A` and `B` "disappeared" from history in the default view. However, there are a few issues with this approach. -+ + The first issue is performance. Unlike any previous option, the `--simplify-merges` option requires walking the entire commit history before returning a single result. This can make the option difficult to use for very large repositories. -+ + The second issue is one of auditing. When many contributors are working on the same repository, it is important which merge commits introduced a change into an important branch. The problematic merge `R` above is @@ -671,10 +671,13 @@ important branch. Instead, the merge `N` was used to merge `R` and `X` into the important branch. This commit may have information about why the change `X` came to override the changes from `A` and `B` in its commit message. + +--show-pulls:: + In addition to the commits shown in the default history, show + each merge commit that is not TREESAME to its first parent but + is TREESAME to a later parent. + -The `--show-pulls` option helps with both of these issues by adding more -merge commits to the history results. If a merge is not TREESAME to its -first parent but is TREESAME to a later parent, then that merge is +When a merge commit is included by `--show-pulls`, the merge is treated as if it "pulled" the change from another branch. When using `--show-pulls` on this example (and no other options) the resulting graph is: |