am, format-patch, send-email and request-pull

progit · ben · Oct 21, 2014 · Oct 8, 2014 · Oct 9, 2014 · Oct 9, 2014
commit 8215864ee0407bfb88cb90956ae8732f3ad9c6b9
diff --git a/book/05-distributed-git/sections/contributing.asc b/book/05-distributed-git/sections/contributing.asc
@@ -615,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
@@ -65,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)))

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

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.

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.

diff --git a/book/C-git-commands/1-git-commands.asc b/book/C-git-commands/1-git-commands.asc
@@ -381,12 +381,31 @@ We demonstrate using it and the circumstances in which you might do so in <<_pat
 
 ==== am
 
+The `git am` command is used to apply patches from an email inbox, specifically one that is mbox formatted. This is useful for receiving patches over email and applying them to your project easily.
+
+We covered usage and workflow around `git am` in <<_git_am>> including using the `--resolved`, `-i` and `-3` options.
+
+There are also a number of hooks you can use to help with the workflow around `git am` and they are all covered in <<_email_hooks>>.
+
+We also use it to apply patch formatted GitHub Pull Request changes in <<_email_notifications>>.
+
 ==== format-patch
 
+The `git format-patch` command is used to generate a series of patches in mbox format that you can use to send to a mailing list properly formatted.
+
+We go through an example of contributing to a project using the `git format-patch` tool in <<_project_over_email>>.
+
 ==== send-email
 
+The `git send-email` command is used to send patches that are generated with `git format-patch` over email.
+
+We go through an example of contributing to a project by sending patches with the `git send-email` tool in <<_project_over_email>>.
+
 ==== request-pull
 
+The `git request-pull` command is simply used to generate an example message body to email to someone. If you have a branch on a public server and want to let someone know how to integrate those changes without sending the patches over email, you can run this command and send the output to the person you want to pull the changes in.
+
+We demonstrate how to use `git request-pull` to generate a pull message in <<_public_project>>.
 
 === External Systems