Edits part III

Author: ben

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

@@ -1,3 +1,5 @@
+**TODO**: reword figure titles
+
 == Git Branching
 
 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.
@@ -271,7 +273,7 @@ It’s worth pointing out that Git determines the best common ancestor to use fo
 .Git automatically creates a new commit object that contains the merged work
 image::images/18333fig0317-tn.png[Git automatically creates a new commit object that contains the merged work.]
 
-Now that your work is merged in, you have no further need for the `iss53` branch. You can delete it and then close the ticket in your ticket-tracking system:
+Now that your work is merged in, you have no further need for the `iss53` branch. You can close the ticket in your ticket-tracking system, and delete the branch:
 
 [source,shell]
 ----
@@ -295,19 +297,21 @@ Git hasn’t automatically created a new merge commit. It has paused the process
 [source,shell]
 ----
 [master*]$ git status
-index.html: needs merge
-# On branch master
-# Changed but not updated:
-#   (use "git add <file>..." to update what will be committed)
-#   (use "git checkout -- <file>..." to discard changes in working directory)
-#
-#  unmerged:   index.html
-#
+On branch master
+You have unmerged paths.
+  (fix conflicts and run "git commit")
+
+Unmerged paths:
+  (use "git add <file>..." to mark resolution)
+
+	both modified:      index.html
+
+no changes added to commit (use "git add" and/or "git commit -a")
 ----
 
 Anything that has merge conflicts and hasn’t been resolved is listed as unmerged. Git adds standard conflict-resolution markers to the files that have conflicts, so you can open them manually and resolve those conflicts. Your file contains a section that looks something like this:
 
-[source,shell]
+[source,html]
 ----
 <<<<<<< HEAD:index.html
 <div id="footer">contact : [email protected]</div>
@@ -318,9 +322,9 @@ Anything that has merge conflicts and hasn’t been resolved is listed as unmerg
 >>>>>>> iss53:index.html
 ----
 
-This means the version in HEAD (your master branch, because that was what you had checked out when you ran your merge command) is the top part of that block (everything above the `=======`), while the version in your `iss53` branch looks like everything in the bottom part. In order to resolve the conflict, you have to either choose one side or the other or merge the contents yourself. For instance, you might resolve this conflict by replacing the entire block with this:
+This means the version in `HEAD` (your `master` branch, because that was what you had checked out when you ran your merge command) is the top part of that block (everything above the `=======`), while the version in your `iss53` branch looks like everything in the bottom part. In order to resolve the conflict, you have to either choose one side or the other or merge the contents yourself. For instance, you might resolve this conflict by replacing the entire block with this:
 
-[source,shell]
+[source,html]
 ----
 <div id="footer">
 please contact us at [email protected]
@@ -333,16 +337,21 @@ If you want to use a graphical tool to resolve these issues, you can run `git me
 [source,shell]
 ----
 $ git mergetool
-merge tool candidates: kdiff3 tkdiff xxdiff meld gvimdiff opendiff emerge vimdiff
-Merging the files: index.html
+
+This message is displayed because 'merge.tool' is not configured.
+See 'git mergetool --tool-help' or 'git help config' for more details.
+'git mergetool' will now attempt to use one of the following tools:
+opendiff kdiff3 tkdiff xxdiff meld tortoisemerge gvimdiff diffuse diffmerge ecmerge p4merge araxis bc3 codecompare vimdiff emerge
+Merging:
+index.html
 
 Normal merge conflict for 'index.html':
- {local}: modified
- {remote}: modified
+  {local}: modified file
+  {remote}: modified file
 Hit return to start merge resolution tool (opendiff):
 ----
 
-If you want to use a merge tool other than the default (Git chose `opendiff` for me in this case because I ran the command on a Mac), you can see all the supported tools listed at the top after ``merge tool candidates''. Type the name of the tool you’d rather use. In <<_git_tools>>, we’ll discuss how you can change this default value for your environment.
+If you want to use a merge tool other than the default (Git chose `opendiff` for me in this case because I ran the command on a Mac), you can see all the supported tools listed at the top after ``one of the following tools.'' Just type the name of the tool you’d rather use. In <<_git_tools>>, we’ll discuss how you can change this default value for your environment (Git gave us a helpful hint).
 
 After you exit the merge tool, Git asks you if the merge was successful. If you tell the script that it was, it stages the file to mark it as resolved for you.
 
@@ -351,12 +360,13 @@ You can run `git status` again to verify that all conflicts have been resolved:
 [source,shell]
 ----
 $ git status
-# On branch master
-# Changes to be committed:
-#   (use "git reset HEAD <file>..." to unstage)
-#
-#  modified:   index.html
-#
+On branch master
+All conflicts fixed but you are still merging.
+  (use "git commit" to conclude merge)
+
+Changes to be committed:
+
+	modified:   index.html
 ----
 
 If you’re happy with that, and you verify that everything that had conflicts has been staged, you can type `git commit` to finalize the merge commit. The commit message by default looks something like this:
@@ -365,21 +375,34 @@ If you’re happy with that, and you verify that everything that had conflicts h
 ----
 Merge branch 'iss53'
 
-
 Conflicts:
- index.html
+	index.html
 #
-# It looks like you may be committing a MERGE.
+# It looks like you may be committing a merge.
 # If this is not correct, please remove the file
-# .git/MERGE_HEAD
+#	.git/MERGE_HEAD
 # and try again.
+
+
+# Please enter the commit message for your changes. Lines starting
+# with '#' will be ignored, and an empty message aborts the commit.
+# On branch master
+# All conflicts fixed but you are still merging.
+#
+# Changes to be committed:
+#	modified:   index.html
 #
 ----
 
 You can modify that message with details about how you resolved the merge if you think it would be helpful to others looking at this merge in the future – why you did what you did, if it’s not obvious.
 
 ==== Undoing Merges
 
+**TODO**
+
+- `git reset --merge ORIG_HEAD`
+- `git revert -m 1 sha`
+
 === Branch Management
 
 Now that you’ve created, merged, and deleted some branches, let’s look at some branch-management tools that will come in handy when you begin using branches all the time.
@@ -389,27 +412,27 @@ The `git branch` command does more than just create and delete branches. If you
 [source,shell]
 ----
 $ git branch
- iss53
+  iss53
 * master
- testing
+  testing
 ----
 
 Notice the `*` character that prefixes the `master` branch: it indicates the branch that you currently have checked out. This means that if you commit at this point, the `master` branch will be moved forward with your new work. To see the last commit on each branch, you can run `git branch -v`:
 
 [source,shell]
 ----
 $ git branch -v
- iss53   93b412c fix javascript issue
+  iss53   93b412c fix javascript issue
 * master  7a98805 Merge branch 'iss53'
- testing 782fd34 add scott to the author list in the readmes
+  testing 782fd34 add scott to the author list in the readmes
 ----
 
 Another useful option to figure out what state your branches are in is to filter this list to branches that you have or have not yet merged into the branch you’re currently on. The useful `--merged` and `--no-merged` options have been available in Git since version 1.5.6 for this purpose. To see which branches are already merged into the branch you’re on, you can run `git branch --merged`:
 
 [source,shell]
 ----
 $ git branch --merged
- iss53
+  iss53
 * master
 ----
 
@@ -420,15 +443,15 @@ To see all the branches that contain work you haven’t yet merged in, you can r
 [source,shell]
 ----
 $ git branch --no-merged
- testing
+  testing
 ----
 
 This shows your other branch. Because it contains work that isn’t merged in yet, trying to delete it with `git branch -d` will fail:
 
 [source,shell]
 ----
 $ git branch -d testing
-error: The branch 'testing' is not an ancestor of your current HEAD.
+error: The branch 'testing' is not fully merged.
 If you are sure you want to delete it, run 'git branch -D testing'.
 ----
 
@@ -518,12 +541,13 @@ If you have a branch named `serverfix` that you want to work on with others, you
 [source,shell]
 ----
 $ git push origin serverfix
-Counting objects: 20, done.
-Compressing objects: 100% (14/14), done.
-Writing objects: 100% (15/15), 1.74 KiB, done.
-Total 15 (delta 5), reused 0 (delta 0)
+Counting objects: 24, done.
+Delta compression using up to 8 threads.
+Compressing objects: 100% (15/15), done.
+Writing objects: 100% (24/24), 1.91 KiB | 0 bytes/s, done.
+Total 24 (delta 2), reused 0 (delta 0)
 To [email protected]:schacon/simplegit.git
-* [new branch]      serverfix -> serverfix
+ * [new branch]      serverfix -> serverfix
 ----
 
 This is a bit of a shortcut. Git automatically expands the `serverfix` branchname out to `refs/heads/serverfix:refs/heads/serverfix`, which means, ``Take my serverfix local branch and push it to update the remote’s serverfix branch.'' We’ll go over the `refs/heads/` part in detail in <<_git_internals>>, but you can generally leave it off. You can also do `git push origin serverfix:serverfix`, which does the same thing – it says, ``Take my serverfix and make it the remote’s serverfix.'' You can use this format to push a local branch into a remote branch that is named differently. If you didn’t want it to be called `serverfix` on the remote, you could instead run `git push origin serverfix:awesomebranch` to push your local `serverfix` branch to the `awesomebranch` branch on the remote project.
@@ -533,12 +557,12 @@ The next time one of your collaborators fetches from the server, they will get a
 [source,shell]
 ----
 $ git fetch origin
-remote: Counting objects: 20, done.
-remote: Compressing objects: 100% (14/14), done.
-remote: Total 15 (delta 5), reused 0 (delta 0)
-Unpacking objects: 100% (15/15), done.
+remote: Counting objects: 7, done.
+remote: Compressing objects: 100% (2/2), done.
+remote: Total 3 (delta 0), reused 3 (delta 0)
+Unpacking objects: 100% (3/3), done.
 From [email protected]:schacon/simplegit
-* [new branch]      serverfix    -> origin/serverfix
+ * [new branch]      serverfix    -> origin/serverfix
 ----
 
 It’s important to note that when you do a fetch that brings down new remote branches, you don’t automatically have local, editable copies of them. In other words, in this case, you don’t have a new `serverfix` branch – you only have an `origin/serverfix` pointer that you can’t modify.
@@ -548,8 +572,8 @@ To merge this work into your current working branch, you can run `git merge orig
 [source,shell]
 ----
 $ git checkout -b serverfix origin/serverfix
-Branch serverfix set up to track remote branch refs/remotes/origin/serverfix.
-Switched to a new branch "serverfix"
+Branch serverfix set up to track remote branch serverfix from origin.
+Switched to a new branch 'serverfix'
 ----
 
 This gives you a local branch that you can work on that starts where `origin/serverfix` is.
@@ -558,22 +582,22 @@ This gives you a local branch that you can work on that starts where `origin/ser
 
 Checking out a local branch from a remote branch automatically creates what is called a _tracking branch_. Tracking branches are local branches that have a direct relationship to a remote branch. If you’re on a tracking branch and type `git push`, Git automatically knows which server and branch to push to. Also, running `git pull` while on one of these branches fetches all the remote references and then automatically merges in the corresponding remote branch.
 
-When you clone a repository, it generally automatically creates a `master` branch that tracks `origin/master`. That’s why `git push` and `git pull` work out of the box with no other arguments. However, you can set up other tracking branches if you wish – ones that don’t track branches on `origin` and don’t track the `master` branch. The simple case is the example you just saw, running `git checkout -b [branch] [remotename]/[branch]`. If you have Git version 1.6.2 or later, you can also use the `--track` shorthand:
+When you clone a repository, it generally automatically creates a `master` branch that tracks `origin/master`. That’s why `git push` and `git pull` work out of the box with no other arguments. However, you can set up other tracking branches if you wish – ones that track branches on other remotes, or don’t track the `master` branch. The simple case is the example you just saw, running `git checkout -b [branch] [remotename]/[branch]`. If you have Git version 1.6.2 or later, you can also use the `--track` shorthand:
 
 [source,shell]
 ----
 $ git checkout --track origin/serverfix
-Branch serverfix set up to track remote branch refs/remotes/origin/serverfix.
-Switched to a new branch "serverfix"
+Branch serverfix set up to track remote branch serverfix from origin.
+Switched to a new branch 'serverfix'
 ----
 
 To set up a local branch with a different name than the remote branch, you can easily use the first version with a different local branch name:
 
 [source,shell]
 ----
 $ git checkout -b sf origin/serverfix
-Branch sf set up to track remote branch refs/remotes/origin/serverfix.
-Switched to a new branch "sf"
+Branch sf set up to track remote branch serverfix from origin.
+Switched to a new branch 'sf'
 ----
 
 Now, your local branch sf will automatically push to and pull from origin/serverfix.
@@ -586,7 +610,7 @@ Suppose you’re done with a remote branch – say, you and your collaborators a
 ----
 $ git push origin :serverfix
 To [email protected]:schacon/simplegit.git
-- [deleted]         serverfix
+ - [deleted]         serverfix
 ----
 
 Boom. No more branch on your server. You may want to dog-ear this page, because you’ll need that command, and you’ll likely forget the syntax. A way to remember this command is by recalling the `git push [remotename] [localbranch]:[remotebranch]` syntax that we went over a bit earlier. If you leave off the `[localbranch]` portion, then you’re basically saying, ``Take nothing on my side and make it be `[remotebranch]`.''