Merge pull request #95 from schacon/errata

Errata

Author: schacon

README.asc

@@ -14,9 +14,9 @@ We've also moved to keeping the translations in seperate repositories rather tha
 
 To contribute errata or new content to this repository, you will need to open up a Pull Request on GitHub. It is generally a good idea before doing anything major to open an issue and make sure your work will get accepted.
 
-You will also need to sign a Contributor License Agreement so if we do a third edition of the book at some point, we won't have to get everyone's permission but instead will simply list you all in an attributions section.
+Errata and basic clarifications will be accepted if we agree that they improve the content. You can also open an issue so we can figure out how or if it needs to be addressed.
 
-There is a CLA bot that will ask you to e-sign an agreement if you send a Pull Request to this repository before that pull will be accepted. Sorry about that, one of the issues with having a dual-licensed work.
+Please refrain from making sweeping copy edit changes as they tend to not get accepted and we don't want you wasting your time. These changes tend to be very subjective, often only clarifying things for some small percentage of people and it's rarely worth the time to accept them. Professional copy editors have already reviewed this content multiple times so while you may have somewhat better taste and grammar than we do it's unlikely that your prose is going to be *so* much better that it's worth changing vast swaths of text.
 
 == How To Generate the Book
 

book/01-introduction/1-introduction.asc

@@ -2,8 +2,8 @@
 == Getting Started
 
 This chapter will be about getting started with Git.
-We will begin at the beginning by explaining some background on version control tools, then move on to how to get Git running on your system and finally how to get it setup to start working with.
-At the end of this chapter you should understand why Git is around, why you should use it and you should be all setup to do so.
+We will begin by explaining some background on version control tools, then move on to how to get Git running on your system and finally how to get it set up to start working with.
+At the end of this chapter you should understand why Git is around, why you should use it and you should be all set up to do so.
 
 include::sections/about-version-control.asc[]
 

book/01-introduction/sections/basics.asc

@@ -84,8 +84,8 @@ Staged means that you have marked a modified file in its current version to go i
 
 This leads us to the three main sections of a Git project: the Git directory, the working directory, and the staging area.
 
-.Working directory, staging area, and git directory.
-image::images/areas.png[Working directory, staging area, and git directory.]
+.Working directory, staging area, and Git directory.
+image::images/areas.png[Working directory, staging area, and Git directory.]
 
 The Git directory is where Git stores the metadata and object database for your project.
 This is the most important part of Git, and it is what is copied when you clone a repository from another computer.

book/01-introduction/sections/first-time-setup.asc

@@ -46,9 +46,10 @@ If you want to use a different text editor, such as Emacs, you can do the follow
 $ git config --global core.editor emacs
 ----
 
-[NOTE]
+[WARNING]
 ====
-Vim and Emacs are popular text editors often used by developers on Unix based systems like Linux and Mac. If you are not familiar with either of these editors or are on a Windows system, you may need to search for instructions for how to set up your favorite editor with Git.
+Vim and Emacs are popular text editors often used by developers on Unix based systems like Linux and Mac. If you are not familiar with either of these editors or are on a Windows system, you may need to search for instructions for how to set up your favorite editor with Git.  
+If you don't set an editor like this and you don't know what Vim or Emacs are, you will likely get into a really confusing state when they are launched.
 ====
 
 ==== Checking Your Settings

book/01-introduction/sections/installing.asc

@@ -50,7 +50,7 @@ Note that this is a project called Git for Windows (also called msysGit), which
 
 Another easy way to get Git installed is by installing GitHub for Windows.
 The installer includes a command line version of Git as well as the GUI.
-It also works well with Powershell, and sets up solid credential caching and sane CRLF settings.((Powershell))((CRLF))((credential caching))
+It also works well with Powershell, and sets up solid credential caching and sane CRLF settings.(((Powershell)))(((CRLF)))(((credential caching)))
 We'll learn more about those things a little later, but suffice it to say they're things you want.
 You can download this from the GitHub for Windows website, at http://windows.github.com[].
 

book/02-git-basics/sections/recording-changes.asc

@@ -214,14 +214,25 @@ You can also use two asterisks to match nested directories; `a/**/z` would match
 
 Here is another example .gitignore file:
 
-[source,console]
+[source]
 ----
-# a comment - this is ignored
-*.a       # no .a files
-!lib.a    # but do track lib.a, even though you're ignoring .a files above
-/TODO     # only ignore the root TODO file, not subdir/TODO
-build/    # ignore all files in the build/ directory
-doc/*.txt # ignore doc/notes.txt, but not doc/server/arch.txt
+# no .a files
+*.a
+
+# but do track lib.a, even though you're ignoring .a files above
+!lib.a
+
+# only ignore the root TODO file, not subdir/TODO
+/TODO
+
+# ignore all files in the build/ directory
+build/
+
+# ignore doc/notes.txt, but not doc/server/arch.txt
+doc/*.txt
+
+# ignore all .txt files in the doc/ directory
+doc/**/*.txt
 ----
 
 [TIP]
@@ -302,7 +313,7 @@ index 0000000..03902a1
 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.
 This can be confusing, because if you've staged all of your changes, `git diff` will give you no output.
 
-For another example, if you stage the `benchmarks.rb` file and then edit it, you can use `git diff` to see the changes in the file that are staged and the changes that are unstaged:
+For another example, if you stage the `benchmarks.rb` file and then edit it, you can use `git diff` to see the changes in the file that are staged and the changes that are unstaged. If our environment looks like this:
 
 [source,console]
 ----
@@ -493,7 +504,7 @@ This is a safety feature to prevent accidental removal of data that hasn't yet b
 
 Another useful thing you may want to do is to keep the file in your working tree but remove it from your staging area.
 In other words, you may want to keep the file on your hard drive but not have Git track it anymore.
-This is particularly useful if you forgot to add something to your `.gitignore` file and accidentally added it, like a large log file or a bunch of `.a` compiled files.
+This is particularly useful if you forgot to add something to your `.gitignore` file and accidentally staged it, like a large log file or a bunch of `.a` compiled files.
 To do this, use the `--cached` option:
 
 [source,console]

book/02-git-basics/sections/tagging.asc

@@ -208,3 +208,16 @@ To [email protected]:schacon/simplegit.git
 ----
 
 Now, when someone else clones or pulls from your repository, they will get all your tags as well.
+
+==== Checking out Tags
+
+You can't really check out a tag in Git, since they can't be moved around.
+If you want to put a version of your repository in your working directory that looks like a specific tag, you can create a new branch at a specific tag:
+
+[source,console]
+----
+$ git checkout -b version2 v2.0.0
+Switched to a new branch 'version2'
+----
+
+Of course if you do this and do a commit, your `version2` branch will be slightly different than your `v2.0.0` tag since it will move forward with your new changes, so do be careful.

book/03-git-branching/sections/nutshell.asc

@@ -46,7 +46,7 @@ The only reason nearly every repository has one is that the `git init` command c
 image::images/branch-and-history.png[A branch and its commit history.]
 
 [[_create_new_branch]]
-==== Creating a new branch
+==== Creating a New Branch
 
 (((branches, creating)))
 What happens if you create a new branch?
@@ -87,7 +87,7 @@ f30ab (HEAD, master, testing) add feature #32 - ability to add new
 You can see the ``master'' and ``testing'' branches that are right there next to the `f30ab` commit.
 
 [[_switching_branches]]
-==== Switching branches
+==== Switching Branches
 
 (((branches, switching)))
 To switch to an existing branch, you run the `git checkout` command.(((git commands, checkout)))

book/03-git-branching/sections/rebasing.asc

@@ -39,6 +39,12 @@ image::images/basic-rebase-3.png[Rebasing the change introduced in `C3` onto `C4
 
 At this point, you can go back to the master branch and do a fast-forward merge.
 
+[source,console]
+----
+$ git checkout master
+$ git merge experiment
+----
+
 .Fast-forwarding the master branch
 image::images/basic-rebase-4.png[Fast-forwarding the master branch.]
 
@@ -171,7 +177,7 @@ Furthermore, if you push this history back up to the server, you'll reintroduce
 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.
 
 [[_rebase_rebase]]
-==== Rebase when you Rebase
+==== Rebase When You Rebase
 
 If you *do* find yourself in a situation like this, Git has some further magic that might help you out. If someone on your team force pushes changes that overwrite work that you've based work on, your challenge is to figure out what is yours and what they've rewritten.
 

book/03-git-branching/sections/remote-branches.asc

@@ -45,7 +45,7 @@ Name this remote `teamone`, which will be your shortname for that whole URL.
 image::images/remote-branches-4.png[Adding another server as a remote.]
 
 Now, you can run `git fetch teamone` to fetch everything the remote `teamone` server has that you don't have yet.
-Because that server is a subset of the data your `origin` server has right now, Git fetches no data but sets a remote branch called `teamone/master` to point to the commit that `teamone` has as its `master` branch.
+Because that server has a subset of the data your `origin` server has right now, Git fetches no data but sets a remote branch called `teamone/master` to point to the commit that `teamone` has as its `master` branch.
 
 .Remote tracking branch for `teamone/master`
 image::images/remote-branches-5.png[Remote tracking branch for `teamone/master`.]
@@ -124,11 +124,9 @@ This gives you a local branch that you can work on that starts where `origin/ser
 (((branches, tracking)))(((branches, upstream)))
 Checking out a local branch from a remote branch automatically creates what is called a ``tracking branch'' (or sometimes an ``upstream 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.
+If you're on a tracking branch and type `git pull`, Git automatically knows which server to fetch from and branch to merge into.
 
 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]`.
 This is a common enough operation that git provides the `--track` shorthand:
@@ -149,7 +147,7 @@ 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`.
+Now, your local branch `sf` will automatically pull from `origin/serverfix`.
 
 If you already have a local branch and want to set it to a remote branch you just pulled down, or want to change the upstream branch you're tracking, you can use the `-u` or `--set-upstream-to` option to `git branch` to explicitly set it at any time.