"Stephen P. Smith" <ischis2@xxxxxxx> writes:
> During the mail thread about "Pull is mostly evil" a user asked how
> the first parent could become reversed.
>
> This howto explains how the first parent can get reversed when viewed
> by the project and then explains a method to keep the history correct.
>
> Signed-off-by: Stephen P. Smith <ischis2@xxxxxxx>
> ---
I needed a few tweaks on top while queuing. You will find the
result on 'pu' after I push it out.
In addition to one typofix ("because" lacking "c"), here are what I
did:
- Typeset concrete command e.g. `git pull` in monospace.
- The second and subsequent paragraphs continued with "+" need to
be flushed to the left; leaving them indented will format them in
monospace (see "with `git pull --rebase` or something").
- Be more explicit in describing 'trunk' being 'the first-parent
chain' in the text.
- Refer to a newer article that discusses this exact topic.
- De-emphasize 'fix-bug-12345' in "Merge fix-bug-12345" log message.
- Describe what the final history illustration shows.
Unless you have objections to the below (or suggestions for better
alternatives), there is no need to resend the patch.
Thanks.
diff --git a/Documentation/howto/keep-canonical-history-correct.txt b/Documentation/howto/keep-canonical-history-correct.txt
index 5979a79..35d48ef 100644
--- a/Documentation/howto/keep-canonical-history-correct.txt
+++ b/Documentation/howto/keep-canonical-history-correct.txt
@@ -38,12 +38,12 @@ central repository:
---o---o---A---X---Y---Z
------------
-Now, if you "git push" at this point, beause your history that leads
+Now, if you `git push` at this point, because your history that leads
to `C` lacks `X`, `Y` and `Z`, it will fail. You need to somehow make
the tip of your history a descendant of `Z`.
One suggested way to solve the problem is "fetch and then merge", aka
-"git pull". When you fetch, your repository will have a history like
+`git pull`. When you fetch, your repository will have a history like
this:
------------
@@ -65,8 +65,9 @@ you will create a merge `M` and make the history look like this:
repository. Such a merge `M` does not lose any commit in both
histories, so in that sense it may not be wrong, but when people want
to talk about "the authoritative canonical history that is shared
-among the project participants", i.e. "the trunk", the way they often
-use is to do:
+among the project participants", i.e. "the trunk", they often view
+it as "commits you see by following the first-parent chain", and use
+this command to view it:
------------
$ git log --first-parent
@@ -91,11 +92,11 @@ did `X` and then `Y` and then `Z` and merged a change that consists of
two commits `B` and `C` that achieves a single goal. You may have
worked on fixing the bug #12345 with these two patches, and the merge
`M'` with swapped parents can say in its log message "Merge
-'fix-bug-12345'". Having a way to tell "git pull" to create a merge
+fix-bug-12345". Having a way to tell `git pull` to create a merge
but record the parents in reverse order may be a way to do so.
Note that I said "achieves a single goal" above, because this is
-important. "swapping the merge order" only covers a special case
+important. "Swapping the merge order" only covers a special case
where the project does not care too much about having unrelated
things done on a single merge but cares a lot about first-parent
chain.
@@ -111,7 +112,7 @@ There are multiple schools of thought about the "trunk" management.
---o---o---A---X---Y---Z---B---C
------------
+
- with `git pull --rebase` or something.
+with `git pull --rebase` or something.
2. Some projects tolerate merges in their history, but do not worry
too much about the first-parent order, and allow fast-forward
@@ -190,7 +191,7 @@ and push it back to the central repository.
It is very much possible that while you are merging topic-b and
topic-c, somebody again advanced the history in the central repository
-to put `W` on top of `Z`, and make your "git push" fail.
+to put `W` on top of `Z`, and make your `git push` fail.
In such a case, you would rewind to discard `M` and `N`, update the
tip of your 'master' again and redo the two merges:
@@ -202,6 +203,8 @@ tip of your 'master' again and redo the two merges:
$ git merge topic-c
------------
+The procedure will result in a history that looks like this:
+
------------
C0--C1--------------C2
/ \
@@ -210,4 +213,4 @@ tip of your 'master' again and redo the two merges:
B0--B1---------B2
------------
-See http://git-blame.blogspot.com/2012/03/fun-with-first-parent.html
+See also http://git-blame.blogspot.com/2013/09/fun-with-first-parent-history.html
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html