Merge remote-tracking branch 'origin/master' into errata

.gitignore

@@ -1,2 +1,11 @@
 output
 .DS_Store
+
+# build artifacts
+progit.html
+progit.pdf
+progit.pdfmarks
+progit.epub
+progit-kf8.epub
+progit.mobi
+images/

Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+
+gem 'rake'
+gem 'asciidoctor', '1.5.0'
+
+gem 'json'
+gem 'awesome_print'
+
+gem 'asciidoctor-epub3', '1.0.0.alpha.2'
+gem 'asciidoctor-pdf', '1.5.0.alpha.5'
+
+gem 'coderay'
+gem 'pygments.rb'
+gem 'thread_safe'
+gem 'epubcheck'
+gem 'kindlegen'

Gemfile.lock

@@ -0,0 +1,74 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    Ascii85 (1.0.2)
+    afm (0.2.2)
+    asciidoctor (1.5.0)
+    asciidoctor-epub3 (1.0.0.alpha.2)
+      asciidoctor (>= 1.5.0, < 1.6.0)
+      gepub (~> 0.6.9.2)
+      thread_safe (~> 0.3.4)
+    asciidoctor-pdf (1.5.0.alpha.5)
+      asciidoctor (~> 1.5.0)
+      prawn (= 1.2.1)
+      prawn-svg (= 0.16.0)
+      prawn-table (= 0.1.1)
+      prawn-templates (= 0.0.3)
+      treetop (= 1.5.3)
+    awesome_print (1.2.0)
+    coderay (1.1.0)
+    epubcheck (3.0.1)
+    gepub (0.6.9.2)
+      nokogiri (~> 1.6.1)
+      rubyzip (>= 1.1.1)
+    hashery (2.1.1)
+    json (1.8.1)
+    kindlegen (2.9.3)
+    mini_portile (0.6.0)
+    nokogiri (1.6.3.1)
+      mini_portile (= 0.6.0)
+    pdf-core (0.2.5)
+    pdf-reader (1.3.3)
+      Ascii85 (~> 1.0.0)
+      afm (~> 0.2.0)
+      hashery (~> 2.0)
+      ruby-rc4
+      ttfunk
+    polyglot (0.3.5)
+    posix-spawn (0.3.9)
+    prawn (1.2.1)
+      pdf-core (~> 0.2.5)
+      ttfunk (~> 1.2.0)
+    prawn-svg (0.16.0)
+      prawn (>= 0.8.4)
+    prawn-table (0.1.1)
+    prawn-templates (0.0.3)
+      pdf-reader (~> 1.3)
+      prawn (>= 0.15.0)
+    pygments.rb (0.6.0)
+      posix-spawn (~> 0.3.6)
+      yajl-ruby (~> 1.1.0)
+    rake (10.3.2)
+    ruby-rc4 (0.1.5)
+    rubyzip (1.1.6)
+    thread_safe (0.3.4)
+    treetop (1.5.3)
+      polyglot (~> 0.3)
+    ttfunk (1.2.2)
+    yajl-ruby (1.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  asciidoctor (= 1.5.0)
+  asciidoctor-epub3 (= 1.0.0.alpha.2)
+  asciidoctor-pdf (= 1.5.0.alpha.5)
+  awesome_print
+  coderay
+  epubcheck
+  json
+  kindlegen
+  pygments.rb
+  rake
+  thread_safe

README.asc

@@ -1,26 +1,60 @@
 = Pro Git, Second Edition
 
-Welcome to the second edition of the Pro Git book.  Until release, this README will be notes on how to collaboratively write this book.
+Welcome to the second edition of the Pro Git book.
 
-First, each chapter will have to be converted from the Markdown of the first release to Asciidoc for the generation toolchain.
+You can find this book online at: http://git-scm.com/book
 
-We should put each topic we want to address in as an issue and close the issue when the text addressing it is complete.  That way we can see what still needs to be done, who is assigned to what and have conversations around the topics before writing.
+Like the first edition, the second edition of Pro Git is open source under a Creative Commons license.
 
-We will use the Pull Request workflow to collaborate on the book.  Referencing an existing issue or multiple issues from the PR is encouraged.  Ideally the technical editor will sign off on each PR as well and should be opening their own as we go.
+A couple of things have changed since open sourcing the first edition. For one, we've moved from Markdown to the amazing Asciidoc format for the text of the book. We've also moved to using O'Reilly's https://atlas.oreilly.com[Atlas platform] for generating continuous builds of the book so all major formats are always available in every language.
 
-I will start by putting in the outline of the current book as OUTLINE.asc and we can start by figuring out what we want the skeleton of the second edition to look like.
+We've also moved to keeping the translations in seperate repositories rather than subdirectories of the English repository. See the Translations section for more information.
 
-== Git 2.0
+== Contributing
 
-The book should be aimed at releasing close to Git 2.0 and all of the examples and defaults should be tuned to what Git 2.0 will act and look like.
+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.
+
+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.
 
 == How To Generate the Book
 
-Right now you should be able to run `asciidoc book.asc` for the whole book, or `asciidoc chapterX.asc` for a single chapter.  Eventually we will want to automate this and perhaps even have a build server (or use Atlas).
+There are two ways to generate e-book content from this source code.
+
+The easiest way is simply to let us do it. A robot is standing by to look for new work on the main branch and automatically build it for everyone.
+
+You can find the current builds on http://git-scm.com/book[] and more information about the builds available at https://progit.org[].
+
+The other way to generate e-book files is to do so manually with Asciidoctor. If you run the following you _may_ actually get HTML, Epub, Mobi and PDF output files:
+
+----
+$ bundle install
+$ bundle exec rake book:build
+Converting to HTML...
+ -- HTML output at progit.html
+Converting to EPub...
+ -- Epub output at progit.epub
+Converting to Mobi (kf8)...
+ -- Mobi output at progit.mobi
+Converting to PDF...
+ -- PDF  output at progit.pdf
+----
+
+This uses the `asciidoctor`, `asciidoctor-pdf` and `asciidoctor-epub` projects.
+
+== Translations
+
+Translations to other languages are highly encouraged but handled a little differently than the first edition. We now keep each translation in a seperate repository and automatically build the output files through Atlas. This was something that was really difficult in the last edition.
+
+Since each translation is a different repository, we can also have different maintainers for each project. The Pro Git team simply pulls them in and builds them for the translation teams. To get automatic builds, translations repositories will have to be under the https://github.com/progit[progit organization on GitHub].
+
+You can find out information on all the current translations and information on how to start your own at: http://progit.org/translations[].
 
 == Figures
 
-The images in this book were generated using Sketch 3, with the [included sketchbook file](progit.sketch).
+The images in this book were generated using http://bohemiancoding.com/sketch/[Sketch 3], with the link:diagram-source/progit.sketch[included sketchbook file].
+
 To add a figure:
 
 . Add a page to the sketchbook. Try to use the included symbols wherever possible.

Rakefile

@@ -0,0 +1,28 @@
+namespace :book do
+  desc 'prepare build'
+  task :prebuild do
+    Dir.mkdir 'images' unless Dir.exists? 'images'
+    Dir.glob("book/*/images/*").each do |image|
+      FileUtils.copy(image, "images/" + File.basename(image))
+    end
+  end
+
+  desc 'build basic book formats'
+  task :build => :prebuild do
+    puts "Converting to HTML..."
+    `bundle exec asciidoctor progit.asc`
+    puts " -- HTML output at progit.html"
+
+    puts "Converting to EPub..."
+    `bundle exec asciidoctor-epub3 progit.asc`
+    puts " -- Epub output at progit.epub"
+
+    puts "Converting to Mobi (kf8)..."
+    `bundle exec asciidoctor-epub3 -a ebook-format=kf8 progit.asc`
+    puts " -- Mobi output at progit.mobi"
+
+    puts "Converting to PDF... (this one takes a while)"
+    `bundle exec asciidoctor-pdf progit.asc 2>/dev/null`
+    puts " -- PDF  output at progit.pdf"
+  end
+end

TRANSLATION_NOTES.asc

@@ -0,0 +1,9 @@
+== Translation Notes
+
+After forking this repository to translate the work, this file is where the notes for coordinating the translation work would go. Things like standardizing on words and expressions so that the work is consistent or notes on how the contributing process is to be handled.
+
+As a translation maintainer, also feel free to modify or completely rewrite the README file to contain instructions specific to your translation.
+
+=== Translation Status
+
+As the work is translated, please update the `status.json` file to indicate the rough percentage complete each file is. This will be shown on various pages to let people know how much work is left to be done.

book/01-introduction/sections/basics.asc

@@ -56,7 +56,10 @@ The mechanism that Git uses for this checksumming is called a SHA-1 hash.(((SHA-
 This is a 40-character string composed of hexadecimal characters (0–9 and a–f) and calculated based on the contents of a file or directory structure in Git.
 A SHA-1 hash looks something like this:
 
-  24b9da6552252987aa493b52f8696cd6d3b00373
+[source]
+----
+24b9da6552252987aa493b52f8696cd6d3b00373
+----
 
 You will see these hash values all over the place in Git because it uses them so much.
 In fact, Git stores everything in its database not by file name but by the hash value of its contents.

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

@@ -24,8 +24,11 @@ It also still looks for `/etc/gitconfig`, although it's relative to the MSys roo
 The first thing you should do when you install Git is to set your user name and e-mail address.
 This is important because every Git commit uses this information, and it's immutably baked into the commits you start creating:
 
-  $ git config --global user.name "John Doe"
-  $ git config --global user.email [email protected]
+[source,console]
+----
+$ git config --global user.name "John Doe"
+$ git config --global user.email [email protected]
+----
 
 Again, you need to do this only once if you pass the `--global` option, because then Git will always use that information for anything you do on that system.
 If you want to override this with a different name or e-mail address for specific projects, you can run the command without the `--global` option when you're in that project.
@@ -38,7 +41,10 @@ Now that your identity is set up, you can configure the default text editor that
 If not configured, Git uses your system's default editor, which is generally Vim.
 If you want to use a different text editor, such as Emacs, you can do the following:
 
-  $ git config --global core.editor emacs
+[source,console]
+----
+$ git config --global core.editor emacs
+----
 
 [NOTE]
 ====
@@ -49,19 +55,25 @@ Vim and Emacs are popular text editors often used by developers on Unix based sy
 
 If you want to check your settings, you can use the `git config --list` command to list all the settings Git can find at that point:
 
-  $ git config --list
-  user.name=John Doe
-  [email protected]
-  color.status=auto
-  color.branch=auto
-  color.interactive=auto
-  color.diff=auto
-  ...
+[source,console]
+----
+$ git config --list
+user.name=John Doe
+[email protected]
+color.status=auto
+color.branch=auto
+color.interactive=auto
+color.diff=auto
+...
+----
 
 You may see keys more than once, because Git reads the same key from different files (`/etc/gitconfig` and `~/.gitconfig`, for example).
 In this case, Git uses the last value for each unique key it sees.
 
 You can also check what Git thinks a specific key's value is by typing `git config <key>`:(((git commands, config)))
 
-  $ git config user.name
-  John Doe
+[source,console]
+----
+$ git config user.name
+John Doe
+----

book/01-introduction/sections/help.asc

@@ -3,13 +3,19 @@
 
 If you ever need help while using Git, there are three ways to get the manual page (manpage) help for any of the Git commands:
 
-  $ git help <verb>
-  $ git <verb> --help
-  $ man git-<verb>
+[source,console]
+----
+$ git help <verb>
+$ git <verb> --help
+$ man git-<verb>
+----
 
 For example, you can get the manpage help for the config command by running(((git commands, help)))
 
-  $ git help config
+[source,console]
+----
+$ git help config
+----
 
 These commands are nice because you can access them anywhere, even offline.
 If the manpages and this book aren't enough and you need in-person help, you can try the `#git` or `#github` channel on the Freenode IRC server (irc.freenode.net).

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
 

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)))

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)))

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.

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.

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

@@ -176,6 +176,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.