Merge pull request #891 from rpjday/maintain

Numerous tweaks (rewording/grammar/fonts) to "Maintaining a Project"

Author: ben

book/05-distributed-git/sections/maintaining.asc

@@ -38,7 +38,7 @@ There are two ways to apply an emailed patch: with `git apply` or with `git am`.
 ===== Applying a Patch with apply
 
 (((git commands, apply)))
-If you received the patch from someone who generated it with the `git diff` or a Unix `diff` command (which is not recommended; see the next section), you can apply it with the `git apply` command.
+If you received the patch from someone who generated it with `git diff` or some variation of the Unix `diff` command (which is not recommended; see the next section), you can apply it with the `git apply` command.
 Assuming you saved the patch at `/tmp/patch-ruby-client.patch`, you can apply the patch like this:
 
 [source,console]
@@ -87,12 +87,11 @@ Subject: [PATCH 1/2] add limit to log function
 Limit log functionality to the first 20
 ----
 
-This is the beginning of the output of the `format-patch` command that you saw in the previous section.
-This is also a valid mbox email format.
+This is the beginning of the output of the `git format-patch` command that you saw in the previous section; it also represents a valid mbox email format.
 If someone has emailed you the patch properly using `git send-email`, and you download that into an mbox format, then you can point `git am` to that mbox file, and it will start applying all the patches it sees.
 If you run a mail client that can save several emails out in mbox format, you can save entire patch series into a file and then use `git am` to apply them one at a time.
 
-However, if someone uploaded a patch file generated via `format-patch` to a ticketing system or something similar, you can save the file locally and then pass that file saved on your disk to `git am` to apply it:
+However, if someone uploaded a patch file generated via `git format-patch` to a ticketing system or something similar, you can save the file locally and then pass that file saved on your disk to `git am` to apply it:
 
 [source,console]
 ----
@@ -264,7 +263,7 @@ For example, if you've added a line in a file on the `master` branch, a direct c
 
 If `master` is a direct ancestor of your topic branch, this isn't a problem; but if the two histories have diverged, the diff will look like you're adding all the new stuff in your topic branch and removing everything unique to the `master` branch.
 
-What you really want to see are the changes added to the topic branch – the work you'll introduce if you merge this branch with master.
+What you really want to see are the changes added to the topic branch -- the work you'll introduce if you merge this branch with master.
 You do that by having Git compare the last commit on your topic branch with the first common ancestor it has with the master branch.
 
 Technically, you can do that by explicitly figuring out the common ancestor and then running your diff on it:
@@ -276,8 +275,15 @@ $ git merge-base contrib master
 $ git diff 36c7db
 ----
 
-However, that isn't convenient, so Git provides another shorthand for doing the same thing: the triple-dot syntax.
-In the context of the `diff` command, you can put three periods after another branch to do a `diff` between the last commit of the branch you're on and its common ancestor with another branch:
+or, more concisely:
+
+[source,console]
+----
+$ git diff $(git merge-base contrib master)
+----
+
+However, neither of those is particularly convenient, so Git provides another shorthand for doing the same thing: the triple-dot syntax.
+In the context of the `git diff` command, you can put three periods after another branch to do a `diff` between the last commit of the branch you're on and its common ancestor with another branch:
 
 [source,console]
 ----
@@ -297,10 +303,11 @@ You have a number of choices, so we'll cover a few of them.
 ===== Merging Workflows
 
 (((workflows, merging)))
-One simple workflow is to merge the work into your `master` branch.
+One basic workflow is to simply merge all that work directly into your `master` branch.
 In this scenario, you have a `master` branch that contains basically stable code.
-When you have work in a topic branch that you've done or that someone has contributed and you've verified, you merge it into your master branch, delete the topic branch, and then continue the process.
-If we have a repository with work in two branches named `ruby_client` and `php_client` that looks like <<merwf_a>> and merge `ruby_client` first and then `php_client` next, then your history will end up looking like <<merwf_b>>.
+When you have work in a topic branch that you think you've completed, or work that someone else has contributed and you've verified, you merge it into your master branch, delete that just-merged topic branch, and repeat.
+
+For instance, if we have a repository with work in two branches named `ruby_client` and `php_client` that looks like <<merwf_a>>, and we merge `ruby_client` followed by `php_client`, your history will end up looking like <<merwf_b>>.
 
 [[merwf_a]]
 .History with several topic branches.
@@ -329,7 +336,7 @@ image::images/merging-workflows-4.png[After a topic branch merge.]
 .After a project release.
 image::images/merging-workflows-5.png[After a topic branch release.]
 
-This way, when people clone your project's repository, they can either check out `master` to build the latest stable version and keep up to date on that easily, or they can check out `develop`, which is the more cutting-edge stuff.
+This way, when people clone your project's repository, they can either check out `master` to build the latest stable version and keep up to date on that easily, or they can check out `develop`, which is the more cutting-edge content.
 You can also extend this concept by having an `integrate` branch where all the work is merged together.
 Then, when the codebase on that branch is stable and passes tests, you merge it into a `develop` branch; and when that has proven itself stable for a while, you fast-forward your `master` branch.
 
@@ -421,7 +428,7 @@ We will cover rerere in more detail in <<_rerere>>.
 ==== Tagging Your Releases
 
 (((tags)))(((tags, signing)))
-When you've decided to cut a release, you'll probably want to drop a tag so you can re-create that release at any point going forward.
+When you've decided to cut a release, you'll probably want to assign a tag so you can re-create that release at any point going forward.
 You can create a new tag as discussed in <<_git_basics_chapter>>.
 If you decide to sign the tag as the maintainer, the tagging may look something like this: