Merge pull request #895 from rpjday/tools_revisions

General rewording/grammar/font cleanup of "Revision Selection"

Author: ben

book/07-git-tools/sections/revision-selection.asc

@@ -1,19 +1,19 @@
 [[_revision_selection]]
 === Revision Selection
 
-Git allows you to specify specific commits or a range of commits in several ways.
+Git allows you to refer to a set of commits or a range of commits in several ways.
 They aren’t necessarily obvious but are helpful to know.
 
 ==== Single Revisions
 
-You can obviously refer to a commit by the SHA-1 hash that it’s given, but there are more human-friendly ways to refer to commits as well.
-This section outlines the various ways you can refer to a single commit.
+You can obviously refer to any single commit by its full, 40-character SHA-1 hash, but there are more human-friendly ways to refer to commits as well.
+This section outlines the various ways you can refer to any commit.
 
 ==== Short SHA-1
 
-Git is smart enough to figure out what commit you meant to type if you provide the first few characters, as long as your partial SHA-1 is at least four characters long and unambiguous – that is, only one object in the current repository begins with that partial SHA-1.
+Git is smart enough to figure out what commit you're referring to if you provide the first few characters of the SHA-1 hash, as long as that partial hash is at least four characters long and unambiguous; that is, no other object in the object database can have a hash that begins with the same prefix.
 
-For example, to see a specific commit, suppose you run a `git log` command and identify the commit where you added certain functionality:
+For example, to examine a specific commit where you know you added certain functionality, you might first run `git log` command to locate the commit:
 
 [source,console]
 ----
@@ -38,7 +38,8 @@ Date:   Thu Dec 11 14:58:32 2008 -0800
     added some blame and merge stuff
 ----
 
-In this case, choose `1c002dd...`. If you `git show` that commit, the following commands are equivalent (assuming the shorter versions are unambiguous):
+In this case, say you're interested in the commit whose hash begins with `1c002dd...`.
+You can inspect that commit with any of the following variations of `git show` (assuming the shorter versions are unambiguous):
 
 [source,console]
 ----
@@ -59,17 +60,16 @@ a11bef0 first commit
 ----
 
 Generally, eight to ten characters are more than enough to be unique within a project.
-
-As an example, the Linux kernel, which is a pretty large project with over 450k commits and 3.6 million objects, has no two objects whose SHA-1s overlap more than the first 11 characters.
+For example, as of October 2017, the Linux kernel (which is a fairly sizable project) has over 700,000 commits and almost six million objects, with no two objects whose SHA-1s are identical in the first 11 characters.
 
 [NOTE]
 .A SHORT NOTE ABOUT SHA-1
 ====
 
-A lot of people become concerned at some point that they will, by random happenstance, have two objects in their repository that hash to the same SHA-1 value.
+A lot of people become concerned at some point that they will, by random happenstance, have two distinct objects in their repository that hash to the same SHA-1 value.
 What then?
 
-If you do happen to commit an object that hashes to the same SHA-1 value as a previous object in your repository, Git will see the previous object already in your Git database and assume it was already written.
+If you do happen to commit an object that hashes to the same SHA-1 value as a previous _different_ object in your repository, Git will see the previous object already in your Git database, assume it was already written and simply reuse it.
 If you try to check out that object again at some point, you’ll always get the data of the first object.
 
 However, you should be aware of how ridiculously unlikely this scenario is.
@@ -89,9 +89,8 @@ Thus, a SHA-1 collision is less likely than every member of your programming tea
 [[_branch_references]]
 ==== Branch References
 
-The most straightforward way to specify a commit requires that it has a branch reference pointed at it.
-Then, you can use a branch name in any Git command that expects a commit object or SHA-1 value.
-For instance, if you want to show the last commit object on a branch, the following commands are equivalent, assuming that the `topic1` branch points to `ca82a6d`:
+One straightforward way to refer to a particular commit is if it's the commit at the tip of a branch; in that case, you can simply use the branch name in any Git command that expects a reference to a commit.
+For instance, if you want to examine the last commit object on a branch, the following commands are equivalent, assuming that the `topic1` branch points to commit `ca82a6d...`:
 
 [source,console]
 ----
@@ -113,7 +112,7 @@ ca82a6dff817ec66f44342007202690a93763949
 [[_git_reflog]]
 ==== RefLog Shortnames
 
-One of the things Git does in the background while you’re working away is keep a ``reflog'' – a log of where your HEAD and branch references have been for the last few months.
+One of the things Git does in the background while you’re working away is keep a ``reflog'' -- a log of where your HEAD and branch references have been for the last few months.
 
 You can see your reflog by using `git reflog`:
 
@@ -130,8 +129,8 @@ d921970 HEAD@{1}: merge phedders/rdocs: Merge made by the 'recursive' stategy.
 ----
 
 Every time your branch tip is updated for any reason, Git stores that information for you in this temporary history.
-And you can specify older commits with this data, as well.
-If you want to see the fifth prior value of the HEAD of your repository, you can use the `@{5}` reference that you see in the reflog output:
+You can use your reflog data to refer to older commits as well.
+For example, if you want to see the fifth prior value of the HEAD of your repository, you can use the `@{5}` reference that you see in the reflog output:
 
 [source,console]
 ----
@@ -146,7 +145,7 @@ For instance, to see where your `master` branch was yesterday, you can type
 $ git show master@{yesterday}
 ----
 
-That shows you where the branch tip was yesterday.
+That would show you where tip of your `master` branch was yesterday.
 This technique only works for data that’s still in your reflog, so you can’t use it to look for commits older than a few months.
 
 To see reflog information formatted like the `git log` output, you can run `git log -g`:
@@ -171,9 +170,15 @@ Date:   Thu Dec 11 15:08:43 2008 -0800
     Merge commit 'phedders/rdocs'
 ----
 
-It’s important to note that the reflog information is strictly local – it’s a log of what you’ve done in your repository.
-The references won’t be the same on someone else’s copy of the repository; and right after you initially clone a repository, you'll have an empty reflog, as no activity has occurred yet in your repository.
-Running `git show HEAD@{2.months.ago}` will work only if you cloned the project at least two months ago – if you cloned it five minutes ago, you’ll get no results.
+It’s important to note that reflog information is strictly local -- it’s a log only of what _you've_ done in _your_ repository.
+The references won’t be the same on someone else’s copy of the repository; also, right after you initially clone a repository, you'll have an empty reflog, as no activity has occurred yet in your repository.
+Running `git show HEAD@{2.months.ago}` will show you the matching commit only if you cloned the project at least two months ago -- if you cloned it any more recently than that, you'll see only your first local commit.
+
+[TIP]
+.Think of the reflog as Git's version of shell history
+====
+If you have a UNIX or Linux background, you can think of the reflog as Git's version of shell history, which emphasizes that what's there is clearly relevant only for you and your ``session'', and has nothing to do with anyone else who might be working on the same machine.
+====
 
 ==== Ancestry References
 
@@ -223,7 +228,7 @@ $ git show "HEAD^"   # OK
 ====
 
 You can also specify a number after the `^` – for example, `d921970^2` means ``the second parent of d921970.''
-This syntax is only useful for merge commits, which have more than one parent.
+This syntax is useful only for merge commits, which have more than one parent.
 The first parent is the branch you were on when you merged, and the second is the commit on the branch that you merged in:
 
 [source,console]
@@ -246,7 +251,7 @@ Date:   Wed Dec 10 22:22:03 2008 +0000
 The other main ancestry specification is the `~` (tilde).
 This also refers to the first parent, so `HEAD~` and `HEAD^` are equivalent.
 The difference becomes apparent when you specify a number.
-`HEAD~2` means ``the first parent of the first parent,'' or ``the grandparent'' – it traverses the first parents the number of times you specify.
+`HEAD~2` means ``the first parent of the first parent,'' or ``the grandparent'' -- it traverses the first parents the number of times you specify.
 For example, in the history listed earlier, `HEAD~3` would be
 
 [source,console]
@@ -271,13 +276,13 @@ Date:   Fri Nov 7 13:47:59 2008 -0500
     ignore *.gem
 ----
 
-You can also combine these syntaxes – you can get the second parent of the previous reference (assuming it was a merge commit) by using `HEAD~3^2`, and so on.
+You can also combine these syntaxes -- you can get the second parent of the previous reference (assuming it was a merge commit) by using `HEAD~3^2`, and so on.
 
 [[_commit_ranges]]
 ==== Commit Ranges
 
 Now that you can specify individual commits, let’s see how to specify ranges of commits.
-This is particularly useful for managing your branches – if you have a lot of branches, you can use range specifications to answer questions such as, ``What work is on this branch that I haven’t yet merged into my main branch?''
+This is particularly useful for managing your branches -- if you have a lot of branches, you can use range specifications to answer questions such as, ``What work is on this branch that I haven’t yet merged into my main branch?''
 
 ===== Double Dot
 
@@ -289,8 +294,8 @@ For example, say you have a commit history that looks like <<double_dot>>.
 .Example history for range selection.
 image::images/double-dot.png[Example history for range selection.]
 
-You want to see what is in your experiment branch that hasn’t yet been merged into your master branch.
-You can ask Git to show you a log of just those commits with `master..experiment` – that means ``all commits reachable by experiment that aren’t reachable by master.''
+Say you want to see what is in your `experiment` branch that hasn’t yet been merged into your `master` branch.
+You can ask Git to show you a log of just those commits with `master..experiment` -- that means ``all commits reachable from experiment that aren’t reachable from master.''
 For the sake of brevity and clarity in these examples, the letters of the commit objects from the diagram are used in place of the actual log output in the order that they would display:
 
 [source,console]
@@ -300,7 +305,7 @@ D
 C
 ----
 
-If, on the other hand, you want to see the opposite – all commits in `master` that aren’t in `experiment` – you can reverse the branch names.
+If, on the other hand, you want to see the opposite -- all commits in `master` that aren’t in `experiment` -- you can reverse the branch names.
 `experiment..master` shows you everything in `master` not reachable from `experiment`:
 
 [source,console]
@@ -310,8 +315,8 @@ F
 E
 ----
 
-This is useful if you want to keep the `experiment` branch up to date and preview what you’re about to merge in.
-Another very frequent use of this syntax is to see what you’re about to push to a remote:
+This is useful if you want to keep the `experiment` branch up to date and preview what you’re about to merge.
+Another frequent use of this syntax is to see what you’re about to push to a remote:
 
 [source,console]
 ----
@@ -320,14 +325,14 @@ $ git log origin/master..HEAD
 
 This command shows you any commits in your current branch that aren’t in the `master` branch on your `origin` remote.
 If you run a `git push` and your current branch is tracking `origin/master`, the commits listed by `git log origin/master..HEAD` are the commits that will be transferred to the server.
-You can also leave off one side of the syntax to have Git assume HEAD.
-For example, you can get the same results as in the previous example by typing `git log origin/master..` – Git substitutes HEAD if one side is missing.
+You can also leave off one side of the syntax to have Git assume `HEAD`.
+For example, you can get the same results as in the previous example by typing `git log origin/master..` -- Git substitutes `HEAD` if one side is missing.
 
 ===== Multiple Points
 
-The double-dot syntax is useful as a shorthand; but perhaps you want to specify more than two branches to indicate your revision, such as seeing what commits are in any of several branches that aren’t in the branch you’re currently on.
+The double-dot syntax is useful as a shorthand, but perhaps you want to specify more than two branches to indicate your revision, such as seeing what commits are in any of several branches that aren’t in the branch you’re currently on.
 Git allows you to do this by using either the `^` character or `--not` before any reference from which you don’t want to see reachable commits.
-Thus these three commands are equivalent:
+Thus, the following three commands are equivalent:
 
 [source,console]
 ----
@@ -337,7 +342,7 @@ $ git log refB --not refA
 ----
 
 This is nice because with this syntax you can specify more than two references in your query, which you cannot do with the double-dot syntax.
-For instance, if you want to see all commits that are reachable from `refA` or `refB` but not from `refC`, you can type one of these:
+For instance, if you want to see all commits that are reachable from `refA` or `refB` but not from `refC`, you can use either of:
 
 [source,console]
 ----
@@ -350,9 +355,9 @@ This makes for a very powerful revision query system that should help you figure
 [[_triple_dot]]
 ===== Triple Dot
 
-The last major range-selection syntax is the triple-dot syntax, which specifies all the commits that are reachable by either of two references but not by both of them.
+The last major range-selection syntax is the triple-dot syntax, which specifies all the commits that are reachable by _either_ of two references but not by both of them.
 Look back at the example commit history in <<double_dot>>.
-If you want to see what is in `master` or `experiment` but not any common references, you can run
+If you want to see what is in `master` or `experiment` but not any common references, you can run:
 
 [source,console]
 ----
@@ -366,7 +371,7 @@ C
 Again, this gives you normal `log` output but shows you only the commit information for those four commits, appearing in the traditional commit date ordering.
 
 A common switch to use with the `log` command in this case is `--left-right`, which shows you which side of the range each commit is in.
-This helps make the data more useful:
+This helps make the output more useful:
 
 [source,console]
 ----