Merge pull request progit#89 from schacon/appendix-final

ben · ben · commit 99ada877e2cd · 2014-10-20T19:44:03.000-07:00
Appendix Final
diff --git a/book/02-git-basics/sections/recording-changes.asc b/book/02-git-basics/sections/recording-changes.asc
@@ -360,6 +360,13 @@ index 3cb747f..e445e28 100644
           log.size
 ----
 
+[[_git_difftool]]
+[NOTE]
+.Git Diff in an External Tool
+====
+We will continue to use the `git diff` command in various ways throughout the rest of the book. There is another way to look at these diffs if you prefer a graphical or external diff viewing program instead. If you run `git difftool` instead of `git diff`, you can view any of these diffs in software like Araxis, emerge, vimdiff and more. Run `git difftool --tool-help` to see what is available on your system.
+====
+
 [[_committing_changes]]
 ==== Committing Your Changes
 
diff --git a/book/02-git-basics/sections/remotes.asc b/book/02-git-basics/sections/remotes.asc
@@ -1,3 +1,4 @@
+[[_remote_repos]]
 === Working with Remotes
 
 To be able to collaborate on any Git project, you need to know how to manage your remote repositories.
@@ -94,7 +95,7 @@ From https://github.com/paulboone/ticgit
 Paul's master branch is now accessible locally as `pb/master` – you can merge it into one of your branches, or you can check out a local branch at that point if you want to inspect it.
 (We'll go over what branches are and how to use them in much more detail in <<_git_branching>>.)
 
-
+[[_fetching_and_pulling]]
 ==== Fetching and Pulling from Your Remotes
 
 As you just saw, to get data from your remote projects, you can run:(((git commands, fetch)))
@@ -116,6 +117,7 @@ If you have a branch set up to track a remote branch (see the next section and <
 This may be an easier or more comfortable workflow for you; and by default, the `git clone` command automatically sets up your local master branch to track the remote master branch (or whatever the default branch is called) on the server you cloned from.
 Running `git pull` generally fetches data from the server you originally cloned from and automatically tries to merge it into the code you're currently working on.
 
+[[_pushing_remotes]]
 ==== Pushing to Your Remotes
 
 When you have your project at a point that you want to share, you have to push it upstream.
@@ -132,6 +134,7 @@ If you and someone else clone at the same time and they push upstream and then y
 You'll have to pull down their work first and incorporate it into yours before you'll be allowed to push.
 See <<_git_branching>> for more detailed information on how to push to remote servers.
 
+[[_inspecting_remote]]
 ==== Inspecting a Remote
 
 If you want to see more information about a particular remote, you can use the `git remote show [remote-name]` command.(((git commands, remote)))
diff --git a/book/02-git-basics/sections/tagging.asc b/book/02-git-basics/sections/tagging.asc
@@ -1,3 +1,4 @@
+[[_git_tagging]]
 === Tagging
 
 (((tags)))
@@ -48,6 +49,7 @@ Annotated tags, however, are stored as full objects in the Git database.
 They're checksummed; contain the tagger name, e-mail, and date; have a tagging message; and can be signed and verified with GNU Privacy Guard (GPG).
 It's generally recommended that you create annotated tags so you can have all this information; but if you want a temporary tag or for some reason don't want to keep the other information, lightweight tags are available too.
 
+[[_annotated_tags]]
 ==== Annotated Tags
 
 (((tags, annotated)))
@@ -172,6 +174,7 @@ Date:   Sun Apr 27 20:43:35 2008 -0700
 ...
 ----
 
+[[_sharing_tags]]
 ==== Sharing Tags
 
 By default, the `git push` command doesn't transfer tags to remote servers.(((git commands, push)))
diff --git a/book/02-git-basics/sections/undoing.asc b/book/02-git-basics/sections/undoing.asc
@@ -126,5 +126,5 @@ Don't ever use this command unless you absolutely know that you don't want the f
 If you would like to keep the changes you've made to that file but still need to get it out of the way for now, we'll go over stashing and branching in <<_git_branching>>; these are generally better ways to go.
 
 Remember, anything that is __committed__ in Git can almost always be recovered.
-Even commits that were on branches that were deleted or commits that were overwritten with an `--amend` commit can be recovered (see <<data_recovery>> for data recovery).
+Even commits that were on branches that were deleted or commits that were overwritten with an `--amend` commit can be recovered (see <<_data_recovery>> for data recovery).
 However, anything you lose that was never committed is likely never to be seen again.
diff --git a/book/02-git-basics/sections/viewing-history.asc b/book/02-git-basics/sections/viewing-history.asc
@@ -1,3 +1,4 @@
+[[_viewing_history]]
 === Viewing the Commit History
 
 After you have created several commits, or if you have cloned a repository with an existing commit history, you'll probably want to look back to see what has happened.
diff --git a/book/03-git-branching/sections/rebasing.asc b/book/03-git-branching/sections/rebasing.asc
@@ -170,6 +170,7 @@ If you run a `git log` when your history looks like this, you'll see two commits
 Furthermore, if you push this history back up to the server, you'll reintroduce all those rebased commits to the central server, which can further confuse people.
 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
 
 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.
diff --git a/book/03-git-branching/sections/remote-branches.asc b/book/03-git-branching/sections/remote-branches.asc
@@ -50,6 +50,7 @@ Because that server is a subset of the data your `origin` server has right now,
 .Remote tracking branch for `teamone/master`
 image::images/remote-branches-5.png[Remote tracking branch for `teamone/master`.]
 
+[[_pushing_branches]]
 ==== Pushing
 
 (((pushing)))
@@ -189,6 +190,7 @@ If you have a tracking branch set up as demonstrated in the last section, either
 
 Generally it's better to simply use the `fetch` and `merge` commands explicitly as the magic of `git pull` can often be confusing.
 
+[[_delete_branches]]
 ==== Deleting Remote Branches
 
 (((branches, deleting remote)))
diff --git a/book/05-distributed-git/sections/contributing.asc b/book/05-distributed-git/sections/contributing.asc
@@ -1,3 +1,4 @@
+[[_contributing_project]]
 === Contributing to a Project
 
 (((contributing)))
@@ -89,6 +90,7 @@ The Git project has well-formatted commit messages – try running `git log --no
 In the following examples, and throughout most of this book, for the sake of brevity this book doesn't have nicely-formatted messages like this; instead, we use the `-m` option to `git commit`.
 Do as we say, not as we do.
 
+[[_private_team]]
 ==== Private Small Team
 
 (((contributing, private small team)))
@@ -613,6 +615,7 @@ Now you can send the maintainer a message that you've made the requested changes
 .Commit history after `featureBv2` work.
 image::images/public-small-3.png[Commit history after `featureBv2` work.]
 
+[[_project_over_email]]
 ==== Public Project over E-Mail
 
 (((contributing, public large project)))
diff --git a/book/05-distributed-git/sections/maintaining.asc b/book/05-distributed-git/sections/maintaining.asc
@@ -28,6 +28,7 @@ $ git checkout -b sc/ruby_client master
 
 Now you're ready to add your contributed work into this topic branch and determine if you want to merge it into your longer-term branches.
 
+[[_patches_from_email]]
 ==== Applying Patches from E-mail
 
 (((email, applying patches from)))
@@ -64,6 +65,7 @@ error: ticgit.gemspec: patch does not apply
 If there is no output, then the patch should apply cleanly.
 This command also exits with a non-zero status if the check fails, so you can use it in scripts if you want.
 
+[[_git_am]]
 ===== Applying a Patch with `am`
 
 (((git commands, am)))
@@ -353,6 +355,7 @@ When a topic branch has finally been merged into `master`, it's removed from the
 The Git project also has a `maint` branch that is forked off from the last release to provide backported patches in case a maintenance release is required.
 Thus, when you clone the Git repository, you have four branches that you can check out to evaluate the project in different stages of development, depending on how cutting edge you want to be or how you want to contribute; and the maintainer has a structured workflow to help them vet new contributions.
 
+[[_rebase_cherry_pick]]
 ===== Rebasing and Cherry Picking Workflows
 
 (((workflows, rebasing and cherry-picking)))
@@ -410,6 +413,7 @@ If you need to, you can interact with the rerere cache using the `git rerere` co
 When it's invoked alone, Git checks its database of resolutions and tries to find a match with any current merge conflicts and resolve them (although this is done automatically if `rerere.enabled` is set to `true`).
 There are also subcommands to see what will be recorded, to erase specific resolution from the cache, and to clear the entire cache. We will cover rerere in more detail in <<_rerere>>.
 
+[[_tagging_releases]]
 ==== Tagging Your Releases
 
 (((tags)))(((tags, signing)))
@@ -465,6 +469,7 @@ $ git show maintainer-pgp-pub | gpg --import
 They can use that key to verify all your signed tags.
 Also, if you include instructions in the tag message, running `git show <tag>` will let you give the end user more specific instructions about tag verification.
 
+[[_build_number]]
 ==== Generating a Build Number
 
 (((build numbers)))(((git commands, describe)))
@@ -485,6 +490,7 @@ The `git describe` command favors annotated tags (tags created with the `-a` or
 You can also use this string as the target of a checkout or show command, although it relies on the abbreviated SHA-1 value at the end, so it may not be valid forever.
 For instance, the Linux kernel recently jumped from 8 to 10 characters to ensure SHA-1 object uniqueness, so older `git describe` output names were invalidated.
 
+[[_preparing_release]]
 ==== Preparing a Release
 
 (((releasing)))(((git commands, archive)))
@@ -509,6 +515,7 @@ $ git archive master --prefix='project/' --format=zip > `git describe master`.zi
 
 You now have a nice tarball and a zip archive of your project release that you can upload to your website or e-mail to people.
 
+[[_the_shortlog]]
 ==== The Shortlog
 
 (((git commands, shortlog)))
diff --git a/book/06-github/sections/3-maintaining.asc b/book/06-github/sections/3-maintaining.asc
@@ -62,6 +62,7 @@ Pull Requests can either come from a branch in a fork of your repository or they
 
 For these examples, let's assume you are ``tonychacon'' and you've created a new Arudino code project named ``fade''.
 
+[[_email_notifications]]
 ===== Email Notifications
 
 Someone comes along and makes a change to your code and sends you a Pull Request. You should get an email notifying you about the new Pull Request and it should look something like <<_email_pr>>.
@@ -100,6 +101,7 @@ image::images/maint-02-merge.png[Merge button]
 
 If you decide you don't want to merge it, you can also just close the Pull Request and the person who opened it will be notified.
 
+[[_pr_refs]]
 ===== Pull Request Refs
 
 If you're dealing with a *lot* of Pull Requests and don't want to add a bunch of remotes or do one time pulls every time, there is a neat trick that GitHub allows you to do. This is a bit of an advanced trick and we'll go over the details of this a bit more in <<_refspec>>, but it can be pretty useful.
diff --git a/book/07-git-tools/sections/advanced-merging.asc b/book/07-git-tools/sections/advanced-merging.asc
@@ -136,6 +136,7 @@ Since in this case, the actual file changes were not conflicting, once we ignore
 
 This is a lifesaver if you have someone on your team who likes to occasionally reformat everything from spaces to tabs or vice-versa.
 
+[[_manual_remerge]]
 ===== Manual File Re-merging
 
 Though Git handles whitespace pre-processing pretty well, there are other types of changes that perhaps Git can't handle automatically, but are scriptable fixes. As an example, let's pretend that Git could not handle the whitespace change and we needed to do it by hand.
@@ -362,6 +363,7 @@ The `git checkout` command can also take `--ours` and `--theirs` options, which
 
 This can be particularly useful for conflicts of binary files where you can simply choose one side, or where you only want to merge certain files in from another branch - you can do the merge and then checkout certain files from one side or the other before committing.
 
+[[_merge_log]]
 ===== Merge Log
 
 Another useful tool when resolving merge conflicts is `git log`. This can help you get context on what may have contributed to the conflicts. Reviewing a little bit of history to remember why two lines of development were touching the same area of code can be really helpful sometimes.
@@ -512,6 +514,7 @@ The downside of this approach is that it's rewriting history, which can be probl
 Check out <<_rebase_peril>> for more on what can happen; the short version is that if other people have the commits you're rewriting, you should probably avoid `reset`.
 This approach also won't work if any other commits have been created since the merge; moving the refs would effectively lose those changes.
 
+[[_reverse_commit]]
 ===== Reverse the commit
 
 If moving the branch pointers around isn't going to work for you, Git gives you the option of making a new commit which undoes all the changes from an existing one.
diff --git a/book/07-git-tools/sections/debugging.asc b/book/07-git-tools/sections/debugging.asc
@@ -3,6 +3,7 @@
 Git also provides a couple of tools to help you debug issues in your projects.
 Because Git is designed to work with nearly any type of project, these tools are pretty generic, but they can often help you hunt for a bug or culprit when things go wrong.
 
+[[_file_annotation]]
 ==== File Annotation
 
 If you track down a bug in your code and want to know when it was introduced and why, file annotation is often your best tool.
@@ -62,6 +63,7 @@ This is really useful.
 Normally, you get as the original commit the commit where you copied the code over, because that is the first time you touched those lines in this file.
 Git tells you the original commit where you wrote those lines, even if it was in another file.
 
+[[_binary_search]]
 ==== Binary Search
 
 Annotating a file helps if you know where the issue is to begin with.
diff --git a/book/07-git-tools/sections/notes.asc b/book/07-git-tools/sections/notes.asc
@@ -1,3 +1,4 @@
+[[_git_notes]]
 === Notes
 
 One of the cool things about Git is that it has strong cryptographic integrity.  If you change any bit in the commit data or any of the files it keeps, all the checksums change, including the commit SHA and every commit SHA since that one.  However, that means that in order to amend the commit in any way, for instance to add some comments on something or even sign off on a commit, you have to change the SHA of the commit itself.
@@ -132,6 +133,7 @@ You can also switch the current namespace you're using so that the default for w
 $ git config core.notesRef refs/notes/bugzilla
 ----
 
+[[_sharing_notes]]
 === Sharing Notes
 
 The notes (as you may have noticed in the previous section) are stored as references, just like branches and tags. This means you can push them to a server. However, Git has a bit of magic built in to expand a branch name like `master` to it's full name, which is `refs/heads/master`. Unfortunately, Git has no such magic built in for notes. So to push your notes to a server you cannot simply run something like `git push origin bugzilla`. Git will do
@@ -160,6 +162,7 @@ To https://github.com/schacon/kidgloves
 
 In fact, you may want to just make that `git push origin refs/notes/*` which will push all your notes.  This is what Git does normally for something like tags.  When you run `git push origin --tags` it basically expands to `git push origin refs/tags/*`.
 
+[[_getting_notes]]
 ==== Getting Notes
 
 Unfortunately, getting notes is even more difficult. Notes do not come down with a clone and there nothing like `git fetch --notes`. In order to fetch notes, you have to specify both sides of the refspec.
diff --git a/book/07-git-tools/sections/replace.asc b/book/07-git-tools/sections/replace.asc
@@ -1,3 +1,4 @@
+[[_replace]]
 === Replace
 
 Git's objects are unchangable, but it does provide an interesting way to pretend to replace objects in it's database with other objects.
diff --git a/book/07-git-tools/sections/reset.asc b/book/07-git-tools/sections/reset.asc
@@ -48,6 +48,7 @@ $ git ls-tree -r HEAD
 
 The `cat-file` and `ls-tree` commands are ``plumbing'' commands that are used for lower level things and not really used in day-to-day work, but they help us see what's going on here.
 
+[[_the_index]]
 ===== The Index
 
 The Index is your *proposed next commit*. We've also been referring to this concept as Git's ``Staging Area'' as this is what Git looks at when you run `git commit`.
diff --git a/book/07-git-tools/sections/revision-selection.asc b/book/07-git-tools/sections/revision-selection.asc
@@ -1,3 +1,4 @@
+[[_revision_selection]]
 === Revision Selection
 
 Git allows you to specify specific commits or a range of commits in several ways.
@@ -81,6 +82,7 @@ If all 6.5 billion humans on Earth were programming, and every second, each one
 A higher probability exists that every member of your programming team will be attacked and killed by wolves in unrelated incidents on the same night.
 ====
 
+[[_branch_references]]
 ==== Branch References
 
 The most straightforward way to specify a commit requires that it have a branch reference pointed at it.
@@ -104,6 +106,7 @@ $ git rev-parse topic1
 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.
diff --git a/book/07-git-tools/sections/rewriting-history.asc b/book/07-git-tools/sections/rewriting-history.asc
@@ -30,6 +30,7 @@ You stage the changes you want by editing a file and running `git add` on it or
 You need to be careful with this technique because amending changes the SHA-1 of the commit.
 It’s like a very small rebase – don’t amend your last commit if you’ve already pushed it.
 
+[[_changing_multiple]]
 ==== Changing Multiple Commit Messages
 
 To modify a commit that is farther back in your history, you must move to more complex tools.
@@ -259,6 +260,7 @@ The command is `filter-branch`, and it can rewrite huge swaths of your history,
 However, it can be very useful.
 You’ll learn a few of the common uses so you can get an idea of some of the things it’s capable of.
 
+[[_removing_file_every_commit]]
 ===== Removing a File from Every Commit
 
 This occurs fairly commonly.
diff --git a/book/07-git-tools/sections/searching.asc b/book/07-git-tools/sections/searching.asc
@@ -3,6 +3,7 @@
 
 With just about any size codebase, you'll often need to find where a function is called or defined, or find the history of a method. Git provides a couple of useful tools for looking through the code and commits stored in it's database quickly and easily. We'll go through a few of them.
 
+[[_git_grep]]
 ==== Git Grep
 
 Git ships with a command called `grep` that allows you to easily search through any committed tree or the working directory for a string or regular expression. For these examples, we'll look through the Git source code itself.
diff --git a/book/07-git-tools/sections/stashing-cleaning.asc b/book/07-git-tools/sections/stashing-cleaning.asc
@@ -233,6 +233,7 @@ Dropped refs/stash@{0} (f0dfc4d5dc332d1cee34a634182e168c4efc3359)
 
 This is a nice shortcut to recover stashed work easily and work on it in a new branch.
 
+[[_git_clean]]
 ==== Cleaning your Working Directory
 
 Finally, you may not want to stash some work or files in your working directory, but simply get rid of them. The `git clean` command will do this for you.
diff --git a/book/07-git-tools/sections/submodules.asc b/book/07-git-tools/sections/submodules.asc
@@ -451,6 +451,7 @@ Unable to merge 'c75e92a2b3855c9e5b66f915308390d9db204aca' in submodule path 'Db
 
 You can go into the submodule directory and fix the conflict just as you normally would.
 
+[[_publishing_submodules]]
 ===== Publishing Submodule Changes
 
 Now we have some changes in our submodule directory. Some of these were brought in from upstream by our updates and others were made locally and aren't available to anyone else yet as we haven't pushed them yet.
diff --git a/book/08-customizing-git/sections/hooks.asc b/book/08-customizing-git/sections/hooks.asc
@@ -53,6 +53,7 @@ After the entire commit process is completed, the `post-commit` hook runs.
 It doesn't take any parameters, but you can easily get the last commit by running `git log -1 HEAD`.
 Generally, this script is used for notification or something similar.
 
+[[_email_hooks]]
 ===== E-mail Workflow Hooks
 
 You can set up three client-side hooks for an e-mail-based workflow.
@@ -73,6 +74,7 @@ The last hook to run during a `git am` operation is `post-applypatch`, which run
 You can use it to notify a group or the author of the patch you pulled in that you've done so.
 You can't stop the patching process with this script.
 
+[[_other_client_hooks]]
 ===== Other Client Hooks
 
 The `pre-rebase` hook runs before you rebase anything and can halt the process by exiting non-zero.
diff --git a/book/09-git-and-other-scms/sections/client-svn.asc b/book/09-git-and-other-scms/sections/client-svn.asc
@@ -1,3 +1,4 @@
+[[_git_svn]]
 ==== Git and Subversion
 
 (((Subversion)))(((Interoperation with other VCSs, Subversion)))
diff --git a/book/09-git-and-other-scms/sections/import-custom.asc b/book/09-git-and-other-scms/sections/import-custom.asc
@@ -1,3 +1,4 @@
+[[_custom_importer]]
 ==== A Custom Importer
 
 (((git commands, fast-import)))
diff --git a/book/09-git-and-other-scms/sections/import-p4.asc b/book/09-git-and-other-scms/sections/import-p4.asc
@@ -12,6 +12,7 @@ Just configure your project settings, user mappings, and branches using a config
 Git Fusion leaves you with what looks like a native Git repository, which is then ready to push to a native Git host if you desire.
 You could even use Perforce as your Git host if you like.
 
+[[_git_p4]]
 ===== Git-p4
 
 Git-p4 can also act as an import tool.
diff --git a/book/09-git-and-other-scms/sections/import-tfs.asc b/book/09-git-and-other-scms/sections/import-tfs.asc
@@ -1,3 +1,4 @@
+[[_git_tfs]]
 ==== TFS
 
 (((TFS)))(((Importing, from TFS)))
diff --git a/book/10-git-internals/sections/maintenance.asc b/book/10-git-internals/sections/maintenance.asc
diff --git a/book/10-git-internals/sections/refspec.asc b/book/10-git-internals/sections/refspec.asc
diff --git a/book/B-embedding-git/1-embedding-git.asc b/book/B-embedding-git/1-embedding-git.asc
diff --git a/book/B-embedding-git/sections/jgit.asc b/book/B-embedding-git/sections/jgit.asc
diff --git a/book/B-embedding-git/sections/libgit2.asc b/book/B-embedding-git/sections/libgit2.asc
diff --git a/book/C-git-commands/1-git-commands.asc b/book/C-git-commands/1-git-commands.asc

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+[[_viewing_history]]`
`1`	`2`	`=== Viewing the Commit History`
`2`	`3`
`3`	`4`	`After you have created several commits, or if you have cloned a repository with an existing commit history, you'll probably want to look back to see what has happened.`