Skip to content

Commit 055eccd

Browse files
committed
Monospace for named commits, slight rewording
1 parent d45a640 commit 055eccd

File tree

1 file changed

+8
-10
lines changed

1 file changed

+8
-10
lines changed

en/book/03-git-branching/chapter3.asc

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
21
== Git Branching
32

43
Nearly every VCS has some form of branching support. Branching means you diverge from the main line of development and continue to do work without messing with that main line. In many VCS tools, this is a somewhat expensive process, often requiring you to create a new copy of your source code directory, which can take a long time for large projects.
@@ -492,7 +491,7 @@ Consider an example of doing some work (on `master`), branching off for an issue
492491
.Multiple topic branches
493492
image::images/18333fig0320-tn.png[Multiple topic branches.]
494493

495-
Now, let’s say you decide you like the second solution to your issue best (`iss91v2`); and you showed the `dumbidea` branch to your coworkers, and it turns out to be genius. You can throw away the original `iss91` branch (losing commits C5 and C6) and merge in the other two. Your history then looks like this:
494+
Now, let’s say you decide you like the second solution to your issue best (`iss91v2`); and you showed the `dumbidea` branch to your coworkers, and it turns out to be genius. You can throw away the original `iss91` branch (losing commits `C5` and `C6`) and merge in the other two. Your history then looks like this:
496495

497496
.History after merging `dumbidea` and `iss91v2`
498497
image::images/18333fig0321-tn.png[History after merging `dumbidea` and `iss91v2`.]
@@ -625,13 +624,13 @@ If you go back to an earlier example from <<_basic_merging>> (see <<rbdiag_a>>),
625624
.Simple divergent history
626625
image::images/18333fig0327-tn.png[Simple divergent history.]
627626

628-
The easiest way to integrate the branches, as we’ve already covered, is the `merge` command. It performs a three-way merge between the two latest branch snapshots (C3 and C4) and the most recent common ancestor of the two (C2), creating a new snapshot (and commit), as shown in <<rbdiag_b>>.
627+
The easiest way to integrate the branches, as we’ve already covered, is the `merge` command. It performs a three-way merge between the two latest branch snapshots (`C3` and `C4`) and the most recent common ancestor of the two (`C2`), creating a new snapshot (and commit), as shown in <<rbdiag_b>>.
629628

630629
[[rbdiag_b]]
631630
.Merging to integrate diverged work history
632631
image::images/18333fig0328-tn.png[Merging to integrate diverged work history.]
633632

634-
However, there is another way: you can take the patch of the change that was introduced in C3 and reapply it on top of C4. In Git, this is called _rebasing_. With the `rebase` command, you can take all the changes that were committed on one branch and replay them on another one.
633+
However, there is another way: you can take the patch of the change that was introduced in `C3` and reapply it on top of `C4`. In Git, this is called _rebasing_. With the `rebase` command, you can take all the changes that were committed on one branch and replay them on another one.
635634

636635
In this example, you’d run the following:
637636

@@ -654,7 +653,7 @@ At this point, you can go back to the master branch and do a fast-forward merge.
654653
.Fast-forwarding the master branch
655654
image::images/18333fig0330-tn.png[Fast-forwarding the master branch.]
656655

657-
Now, the snapshot pointed to by C3' is exactly the same as the one that was pointed to by C5 in the merge example. There is no difference in the end product of the integration, but rebasing makes for a cleaner history. If you examine the log of a rebased branch, it looks like a linear history: it appears that all the work happened in series, even when it originally happened in parallel.
656+
Now, the snapshot pointed to by `C3'` is exactly the same as the one that was pointed to by `C5` in the merge example. There is no difference in the end product of the integration, but rebasing makes for a cleaner history. If you examine the log of a rebased branch, it looks like a linear history: it appears that all the work happened in series, even when it originally happened in parallel.
658657

659658
Often, you’ll do this to make sure your commits apply cleanly on a remote branch – perhaps in a project to which you’re trying to contribute but that you don’t maintain. In this case, you’d do your work in a branch and then rebase your work onto `origin/master` when you were ready to submit your patches to the main project. That way, the maintainer doesn’t have to do any integration work – just a fast-forward or a clean apply.
660659

@@ -668,7 +667,7 @@ You can also have your rebase replay on something other than the rebase branch.
668667
.A history with a topic branch off another topic branch
669668
image::images/18333fig0331-tn.png[A history with a topic branch off another topic branch.]
670669

671-
Suppose you decide that you want to merge your client-side changes into your mainline for a release, but you want to hold off on the server-side changes until it’s tested further. You can take the changes on client that aren’t on server (C8 and C9) and replay them on your master branch by using the `--onto` option of `git rebase`:
670+
Suppose you decide that you want to merge your client-side changes into your mainline for a release, but you want to hold off on the server-side changes until it’s tested further. You can take the changes on client that aren’t on server (`C8` and `C9`) and replay them on your master branch by using the `--onto` option of `git rebase`:
672671

673672
[source,shell]
674673
----
@@ -758,10 +757,10 @@ image::images/18333fig0339-tn.png[You merge in the same work again into a new me
758757

759758
If you run a `git log` when your history looks like this, you’ll see two commits that have the same author, date, and message, which will be confusing.
760759
Furthermore, if you push this history back up to the server, you’ll reintroduce all those rebased commits to the central server, which can further confuse people.
761-
It's pretty safe to assume that the other developer doesn't want C4 and C6 to be in the history; that's why she rebased in the first place.
760+
It's pretty safe to assume that the other developer doesn't want `C4` and `C6` to be in the history; that's why she rebased in the first place.
762761

763762
Fortunately, Git has a feature to make this easier.
764-
If you use the `--rebase` flag to `git pull`, Git will do a fetch (which updates the remote branch to C4') followed by a _rebase_, rather than a merge.
763+
If you use the `--rebase` flag to `git pull`, Git will do a fetch (which updates the remote branch to `C4'`) followed by a _rebase_, rather than a merge.
765764
This is exactly what you want; your local commits will follow the new remote commits in a straight line, and the abandoned commits will stay lost.
766765

767766
In fact, this functionality is so useful, that you can make that flag the default; simply do `git config --global pull.rebase true`.
@@ -789,8 +788,7 @@ You wouldn't publish the first draft of a book, and the manual for how to mainta
789788
This is the camp that uses tools like rebase and filter-branch when they are appropriate for telling the story in the way that's best for future readers.
790789
If that requires a force-push every now and then, so be it.
791790

792-
Now back to the question of which is better.
793-
Hopefully you'll see that it's not that simple.
791+
Now, to the question of whether merging or rebasing is better: hopefully you'll see that it's not that simple.
794792
Git is a powerful tool, and allows you to do many things to and with your history, but every team and every project is different.
795793
Now that you know how both of these things work, it's up to you to decide which one is best for your particular situation.
796794

0 commit comments

Comments
 (0)