various small chapter 2 fixups, formatting and tweaks

schacon · schacon · commit 1dd3a6a0fd48 · 2014-06-03T21:21:32.000-07:00
Also adds the -S option to the log filter page and removes the Reset
section that was outlined here.

Also changes URLs to remove the .git from the ends.
diff --git a/book/02-git-basics/1-git-basics.asc b/book/02-git-basics/1-git-basics.asc
@@ -26,12 +26,12 @@ At this point, nothing in your project is tracked yet.
 (See <<_git_internals>> for more information about exactly what files are contained in the `.git` directory you just created.)
 
 If you want to start version-controlling existing files (as opposed to an empty directory), you should probably begin tracking those files and do an initial commit.
-You can accomplish that with a few git add commands that specify the files you want to track, followed by a commit:
+You can accomplish that with a few `git add` commands that specify the files you want to track, followed by a `git commit`:
 
 [source,shell]
 ----
 $ git add *.c
-$ git add README
+$ git add LICENSE
 $ git commit -m 'initial project version'
 ----
 
@@ -40,33 +40,33 @@ At this point, you have a Git repository with tracked files and an initial commi
 
 ==== Cloning an Existing Repository
 
-If you want to get a copy of an existing Git repository – for example, a project you’d like to contribute to – the command you need is git clone.
-If you’re familiar with other VCS systems such as Subversion, you’ll notice that the command is clone and not checkout.
-This is an important distinction – Git receives a copy of nearly all data that the server has.
-Every version of every file for the history of the project is pulled down when you run `git clone`.
-In fact, if your server disk gets corrupted, you can use any of the clones on any client to set the server back to the state it was in when it was cloned (you may lose some server-side hooks and such, but all the versioned data would be there – see <<_git_on_the_server>> for more details).
+If you want to get a copy of an existing Git repository – for example, a project you’d like to contribute to – the command you need is `git clone`.
+If you’re familiar with other VCS systems such as Subversion, you’ll notice that the command is "clone" and not "checkout".
+This is an important distinction – instead of getting just a working copy, Git receives a full copy of nearly all data that the server has.
+Every version of every file for the history of the project is pulled down by default when you run `git clone`.
+In fact, if your server disk gets corrupted, you can often use nearly any of the clones on any client to set the server back to the state it was in when it was cloned (you may lose some server-side hooks and such, but all the versioned data would be there – see <<_git_on_the_server>> for more details).
 
 You clone a repository with `git clone [url]`.
-For example, if you want to clone the Ruby Git library called Grit, you can do so like this:
+For example, if you want to clone the Git linkable library called libgit2, you can do so like this:
 
 [source,shell]
 ----
-$ git clone https://github.com/schacon/grit.git
+$ git clone https://github.com/libgit2/libgit2
 ----
 
-That creates a directory named ``grit'', initializes a `.git` directory inside it, pulls down all the data for that repository, and checks out a working copy of the latest version.
-If you go into the new `grit` directory, you’ll see the project files in there, ready to be worked on or used.
-If you want to clone the repository into a directory named something other than grit, you can specify that as the next command-line option:
+That creates a directory named ``libgit2'', initializes a `.git` directory inside it, pulls down all the data for that repository, and checks out a working copy of the latest version.
+If you go into the new `libgit2` directory, you’ll see the project files in there, ready to be worked on or used.
+If you want to clone the repository into a directory named something other than ``libgit2'', you can specify that as the next command-line option:
 
 [source,shell]
 ----
-$ git clone https://github.com/schacon/grit.git mygrit
+$ git clone https://github.com/libgit2/libgit2 mylibgit
 ----
 
-That command does the same thing as the previous one, but the target directory is called `mygrit`.
+That command does the same thing as the previous one, but the target directory is called `mylibgit`.
 
 Git has a number of different transfer protocols you can use.
-The previous example uses the `git://` protocol, but you may also see `http(s)://` or `user@server:path/to/repo.git`, which uses the SSH transfer protocol.
+The previous example uses the `https://` protocol, but you may also see `git://` or `user@server:path/to/repo.git`, which uses the SSH transfer protocol.
 <<_git_on_the_server>> will introduce all of the available options the server can set up to access your Git repository and the pros and cons of each.
 
 === Recording Changes to the Repository
@@ -89,7 +89,7 @@ image::images/18333fig0201-tn.png[The lifecycle of the status of your files.]
 
 ==== Checking the Status of Your Files
 
-The main tool you use to determine which files are in which state is the `git status` command.
+The main tool you use to determine which files are in which state is the `git status` command.(((git, status)))
 If you run this command directly after a clone, you should see something like this:
 
 [source,shell]
@@ -101,16 +101,16 @@ nothing to commit, working directory clean
 
 This means you have a clean working directory – in other words, there are no tracked and modified files.
 Git also doesn’t see any untracked files, or they would be listed here.
-Finally, the command tells you which branch you’re on.
-For now, that is always master, which is the default; you won’t worry about it here.
-The next chapter will go over branches and references in detail.
+Finally, the command tells you which branch you’re on and informs you that it has not diverged from the same branch on the server.
+For now, that branch is always ``master'', which is the default; you won’t worry about it here.
+<<_git_branching>>  will go over branches and references in detail.
 
 Let’s say you add a new file to your project, a simple README file.
 If the file didn’t exist before, and you run `git status`, you see your untracked file like so:
 
 [source,shell]
 ----
-$ vim README
+$ echo 'My Project' > README
 $ git status
 On branch master
 Untracked files:
@@ -128,15 +128,15 @@ You do want to start including README, so let’s start tracking the file.
 
 ==== Tracking New Files
 
-In order to begin tracking a new file, you use the command `git add`.
+In order to begin tracking a new file, you use the command `git add`.(((git, add)))
 To begin tracking the README file, you can run this:
 
 [source,shell]
 ----
 $ git add README
 ----
 
-If you run your status command again, you can see that your README file is now tracked and staged:
+If you run your status command again, you can see that your README file is now tracked and staged to be committed:
 
 [source,shell]
 ----
@@ -150,14 +150,14 @@ Changes to be committed:
 ----
 
 You can tell that it’s staged because it’s under the ``Changes to be committed'' heading.
-If you commit at this point, the version of the file at the time you ran git add is what will be in the historical snapshot.
-You may recall that when you ran git init earlier, you then ran git add (files) – that was to begin tracking files in your directory.
-The git add command takes a path name for either a file or a directory; if it’s a directory, the command adds all the files in that directory recursively.
+If you commit at this point, the version of the file at the time you ran `git add` is what will be in the historical snapshot.
+You may recall that when you ran `git init` earlier, you then ran `git add (files)` – that was to begin tracking files in your directory.(((git, init)))(((git, add)))
+The `git add` command takes a path name for either a file or a directory; if it’s a directory, the command adds all the files in that directory recursively.
 
 ==== Staging Modified Files
 
 Let’s change a file that was already tracked.
-If you change a previously tracked file called `benchmarks.rb` and then run your `git status` command again, you get something that looks like this:
+If you change a previously tracked file called ``benchmarks.rb'' and then run your `git status` command again, you get something that looks like this:
 
 [source,shell]
 ----
@@ -176,9 +176,9 @@ Changes not staged for commit:
 
 ----
 
-The `benchmarks.rb` file appears under a section named ``Changed but not staged for commit'' – which means that a file that is tracked has been modified in the working directory but not yet staged.
-To stage it, you run the `git add` command (it’s a multipurpose command – you use it to begin tracking new files, to stage files, and to do other things like marking merge-conflicted files as resolved).
-Let’s run `git add` now to stage the benchmarks.rb file, and then run `git status` again:
+The ``benchmarks.rb'' file appears under a section named ``Changed but not staged for commit'' – which means that a file that is tracked has been modified in the working directory but not yet staged.
+To stage it, you run the `git add` command. `git add` is a multipurpose command – you use it to begin tracking new files, to stage files, and to do other things like marking merge-conflicted files as resolved. It may be helpful to think of it more as ``add this content to the next commit'' rather than ``add this file to the project''.
+Let’s run `git add` now to stage the ``benchmarks.rb'' file, and then run `git status` again:
 
 [source,shell]
 ----
@@ -214,6 +214,7 @@ Changes not staged for commit:
   (use "git checkout -- <file>..." to discard changes in working directory)
 
 	modified:   benchmarks.rb
+
 ----
 
 What the heck?
@@ -277,12 +278,17 @@ build/    # ignore all files in the build/ directory
 doc/*.txt # ignore doc/notes.txt, but not doc/server/arch.txt
 ----
 
+[TIP]
+====
+GitHub maintains a fairly comprehensive list of good `.gitignore` file examples for dozens or projects and languages at https://github.com/github/gitignore[] if you want a starting point for your project.
+====
+
 ==== Viewing Your Staged and Unstaged Changes
 
 If the `git status` command is too vague for you – you want to know exactly what you changed, not just which files were changed – you can use the `git diff` command.
 We’ll cover `git diff` in more detail later, but you’ll probably use it most often to answer these two questions: What have you changed but not yet staged?
 And what have you staged that you are about to commit?
-Although `git status` answers those questions very generally, `git diff` shows you the exact lines added and removed – the patch, as it were.
+Although `git status` answers those questions very generally by listing the file names, `git diff` shows you the exact lines added and removed – the patch, as it were.
 
 Let’s say you edit and stage the `README` file again and then edit the `benchmarks.rb` file without staging it.
 If you run your `git status` command, you once again see something like this:
@@ -328,24 +334,22 @@ index 3cb747f..e445e28 100644
 That command compares what is in your working directory with what is in your staging area.
 The result tells you the changes you’ve made that you haven’t yet staged.
 
-If you want to see what you’ve staged that will go into your next commit, you can use `git diff --cached`.
-(In Git versions 1.6.1 and later, you can also use `git diff --staged`, which may be easier to remember.)
+If you want to see what you’ve staged that will go into your next commit, you can use `git diff --staged`.
 This command compares your staged changes to your last commit:
 
 [source,shell]
 ----
-$ git diff --cached
+$ git diff --staged
 diff --git a/README b/README
 new file mode 100644
 index 0000000..03902a1
 --- /dev/null
-+++ b/README2
-@@ -0,0 +1,5 @@
-+grit
-+ by Tom Preston-Werner, Chris Wanstrath
-+ https://github.com/mojombo/grit
++++ b/README
+@@ -0,0 +1,4 @@
++My Project
++
++ This is my project and it is amazing.
 +
-+Grit is a Ruby library for extracting information from a Git repository
 ----
 
 It’s important to note that `git diff` by itself doesn’t show all changes made since your last commit – only changes that are still unstaged.
@@ -414,8 +418,8 @@ index 3cb747f..e445e28 100644
 Now that your staging area is set up the way you want it, you can commit your changes.
 Remember that anything that is still unstaged – any files you have created or modified that you haven’t run `git add` on since you edited them – won’t go into this commit.
 They will stay as modified files on your disk.
-In this case, the last time you ran `git status`, you saw that everything was staged, so you’re ready to commit your changes.
-The simplest way to commit is to type `git commit`:
+In this case, the last time you ran `git status`, you saw that everything was staged, so you’re ready to commit your changes.(((git, status)))
+The simplest way to commit is to type `git commit`:(((git, commit)))
 
 [source,shell]
 ----
@@ -488,7 +492,7 @@ $ git commit -a -m 'added new benchmarks'
  1 file changed, 5 insertions(+), 0 deletions(-)
 ----
 
-Notice how you don’t have to run `git add` on the benchmarks.rb file in this case before you commit.
+Notice how you don’t have to run `git add` on the ``benchmarks.rb'' file in this case before you commit.
 
 ==== Removing Files
 
@@ -536,7 +540,7 @@ To do this, use the `--cached` option:
 
 [source,shell]
 ----
-$ git rm --cached readme.txt
+$ git rm --cached README
 ----
 
 You can pass files, directories, and file-glob patterns to the `git rm` command.
@@ -610,7 +614,7 @@ To get the project, run
 
 [source,shell]
 ----
-git clone https://github.com/schacon/simplegit-progit.git
+git clone https://github.com/schacon/simplegit-progit
 ----
 
 When you run `git log` in this project, you should get output that looks something like this:
@@ -643,7 +647,7 @@ As you can see, this command lists each commit with its SHA-1 checksum, the auth
 A huge number and variety of options to the `git log` command are available to show you exactly what you’re looking for.
 Here, we’ll show you some of the most popular.
 
-One of the more helpful options is `-p`, which shows the diff introduced in each commit.
+One of the more helpful options is `-p`, which shows the difference introduced in each commit.
 You can also use `-2`, which limits the output to only the last two entries:
 
 [source,shell]
@@ -731,6 +735,7 @@ Date:   Sat Mar 15 10:31:28 2008 -0700
 
 As you can see, the `--stat` option prints below each commit entry a list of modified files, how many files were changed, and how many lines in those files were added and removed.
 It also puts a summary of the information at the end.
+
 Another really useful option is `--pretty`.
 This option changes the log output to formats other than the default.
 A few prebuilt options are available for you to use.
@@ -751,9 +756,9 @@ This is especially useful when you’re generating output for machine parsing 
 [source,shell]
 ----
 $ git log --pretty=format:"%h - %an, %ar : %s"
-ca82a6d - Scott Chacon, 11 months ago : changed the version number
-085bb3b - Scott Chacon, 11 months ago : removed unnecessary test code
-a11bef0 - Scott Chacon, 11 months ago : first commit
+ca82a6d - Scott Chacon, 6 years ago : changed the version number
+085bb3b - Scott Chacon, 6 years ago : removed unnecessary test code
+a11bef0 - Scott Chacon, 6 years ago : first commit
 ----
 
 <<pretty_format>> lists some of the more useful options that format takes.
@@ -786,7 +791,7 @@ So, if you send in a patch to a project and one of the core members applies the
 We’ll cover this distinction a bit more in <<_distributed_git>>.
 
 The oneline and format options are particularly useful with another `log` option called `--graph`.
-This option adds a nice little ASCII graph showing your branch and merge history, which we can see our copy of the Grit project repository:
+This option adds a nice little ASCII graph showing your branch and merge history:
 
 [source,shell]
 ----
@@ -803,6 +808,8 @@ $ git log --pretty=format:"%h %s" --graph
 *  11d191e Merge branch 'defunkt' into local
 ----
 
+This type of output will become more interesting as we go through branching and merging in the next chapter.
+
 Those are only some simple output-formatting options to `git log` – there are many more.
 <<log_options>> lists the options we’ve covered so far, as well as some other common formatting options that may be useful, along with how they change the output of the log command.
 
@@ -824,7 +831,7 @@ Those are only some simple output-formatting options to `git log` – there are
 
 ==== Limiting Log Output
 
-In addition to output-formatting options, git log takes a number of useful limiting options – that is, options that let you show only a subset of commits.
+In addition to output-formatting options, `git log` takes a number of useful limiting options – that is, options that let you show only a subset of commits.
 You’ve seen one such option already – the `-2` option, which show only the last two commits.
 In fact, you can do `-<n>`, where `n` is any integer to show the last `n` commits.
 In reality, you’re unlikely to use that often, because Git by default pipes all output through a pager so you see only one page of log output at a time.
@@ -843,6 +850,13 @@ You can also filter the list to commits that match some search criteria.
 The `--author` option allows you to filter on a specific author, and the `--grep` option lets you search for keywords in the commit messages.
 (Note that if you want to specify both author and grep options, you have to add `--all-match` or the command will match commits with either.)
 
+Another really helpful filter is the `-S` option which takes a string and only shows the commits that introduced a change to the code that added or removed that string.  For instance, if you wanted to find the last commit that added or removed a reference to a specific function, you could call:
+
+[source,shell]
+----
+$ git log --Sfunction_name
+----
+
 The last really useful option to pass to `git log` as a filter is a path.
 If you specify a directory or file name, you can limit the log output to commits that introduced a change to those files.
 This is always the last option and is generally preceded by double dashes (`--`) to separate the paths from the options.
@@ -859,6 +873,8 @@ In <<limit_options>> we’ll list these and a few other common options for your
 | `--until`, `--before` | Limit the commits to those made before the specified date.
 | `--author`            | Only show commits in which the author entry matches the specified string.
 | `--committer`         | Only show commits in which the committer entry matches the specified string.
+| `--grep`              | Only show commits with a commit message containing the string
+| `-S `                 | Only show commits adding or removing code matching the string
 |================================
 
 For example, if you want to see which commits modifying test files in the Git source code history were committed by Junio Hamano and were not merges in the month of October 2008, you can run something like this:
@@ -885,27 +901,6 @@ Here, we’ll review a few basic tools for undoing changes that you’ve made.
 Be careful, because you can’t always undo some of these undos.
 This is one of the few areas in Git where you may lose some work if you do it wrong.
 
-[[_reset]]
-==== Reset Demystified
-
-**TODO**
-
-===== The Three Trees
-
-===== The Workflow
-
-===== The Role of Reset
-
-===== Reset With a Path
-
-===== A Fun Example
-
-===== Check It Out
-
-===== Summary
-
-==== Changing Your Last Commit
-
 One of the common undos takes place when you commit too early and possibly forget to add some files, or you mess up your commit message.
 If you want to try that commit again, you can run commit with the `--amend` option:
 
@@ -1037,7 +1032,7 @@ If you’ve cloned your repository, you should at least see origin – that is t
 
 [source,shell]
 ----
-$ git clone https://github.com/schacon/ticgit.git
+$ git clone https://github.com/schacon/ticgit
 Cloning into 'ticgit'...
 remote: Reusing existing pack: 1857, done.
 remote: Total 1857 (delta 0), reused 0 (delta 0)
