GrimoireGuruHandbook.tex: Updated instructions for git 1.5

1 files changed, 98 insertions, 64 deletions

diff --git a/GrimoireGuruHandbook.tex b/GrimoireGuruHandbook.tex
index d51b8bd..2399a41 100644
--- a/GrimoireGuruHandbook.tex
+++ b/GrimoireGuruHandbook.tex
@@ -113,35 +113,62 @@ $ git pull
 Note that all but the `git clone` command need to be run from this
 directory.  If you receive a message saying "fatal: Not a git repository:
 '.git'", then you did not follow my instruction above.
-\section{Selecting your working branch}
-The main grimoire that you have checked out has many branches. You may view
-the available branches by running:
+\section{Viewing local branches}
+Local branches are branches made by you, with only one, ``master'', being
+created for you. To view your local branches, run:
 \begin{verbatim}
 $ git branch
+* master
 \end{verbatim}
-And you will see output similar to this:
+The "*" before "master" means that this is the currently checked out
+(working) branch. You may modify local branches as much as you want and you
+will not affect anyone else until you push your changes back to the server
+(see below).
+
+\section{Viewing remote branches}
+The main grimoire that you have checked out has many branches. You may view
+the available remote branches by running:
+\begin{verbatim}
+$ git branch -r
+  origin/HEAD
+  origin/devel
+  origin/devel-iceweasel
+  origin/devel-shadow
+  origin/master
+  origin/stable-0.3
+  origin/stable-0.4
+  origin/stable-0.6
+  origin/stable-0.7
+  origin/stable-0.8
+  origin/stable-rc-0.4
+  origin/stable-rc-0.5
+  origin/stable-rc-0.6
+  origin/stable-rc-0.7
+  origin/stable-rc-0.8
+\end{verbatim}
+All of the branches listed with origin/ are 'remote' branches, ones that are
+available for everyone to use.
 
+\section{Selecting your working branch}
+To checkout another branch (say origin/devel) to work on, you would run:
 \begin{verbatim}
-devel
-* master
-origin
-stable-0.3
-stable-0.4
-stable-rc-0.4
-stable-rc-0.5
-stable-rc-0.6
+$ git checkout -b devel origin/devel
+Switched to a new branch "devel
 \end{verbatim}
-
-The "*" before "master" means that this is the currently checked out branch.
-To checkout another branch (say devel), you would run:
+Now check what local branches you have
 \begin{verbatim}
-$ git checkout devel
+$ git branch
+* devel
+  master
 \end{verbatim}
-Unless you know what you are doing, only work in the master (a.k.a. test)
+You are now working on a local branch of origin/devel called ``devel''.
+
+Unless you know what you are doing, only work in the ``master'' (a.k.a. test)
 branch.
 
 You will *never* touch the 'origin' branch, as this is used by git
 internally to check your changes against.
+
 \section{Making changes}
 Before making any changes, it is a good idea to make sure your clone is
 up-to-date (though this is not required, it does make submitting easier).
@@ -199,7 +226,7 @@ directory.
 If you wish to specify your message log on the command line, rather than in
 your favorite editor, you may do so with the -m flag:
 \begin{verbatim}
-$ git commit -m "Updated git to 1.4.3.5"
+$ git commit -m "git: Updated to 1.4.3.5"
 \end{verbatim}
 
 If ever you make changes you wish to undo, before running `git commit`, you
@@ -218,7 +245,8 @@ repository, run:
 $ git push <destination> <source>
 \end{verbatim}
 
-Since we are working in master, we would run:
+Since we are working in master and want to push to the upstream server, we
+would run:
 \begin{verbatim}
 $ git push origin master
 \end{verbatim}
@@ -240,7 +268,7 @@ which begins the new changes, and a \begin{verbatim}>>>>>>
 .merge_file_otherstuff\end{verbatim}, which
 ends the new changes. Once you resolve the conflict by editing the file
 and remove what should not be there, you will run \textdollar git update-index
-<file>
+<files>
 and then commit your changes.
 \section{Creating your own local branch}
 \section{Creating your own remote branch}
@@ -250,29 +278,26 @@ and then commit your changes.
 
 These grimoires are special, in that you never modify them directly
 (similar to how you treat the origin branch). To update one of these (say
-stable-rc-0.6), you will use the following steps:
+stable-rc-0.8), you will use the following steps:
 \begin{enumerate}
-\item Switch to the stable-rc-0.6 branch.
-\begin{verbatim}
-$ git checkout stable-rc-0.6
-\end{verbatim}
-\item Create a branch of the current stable-rc-0.6 called my-stable-rc-0.6 and
-switch to it.
+\item Checkout the the origin/stable-rc-0.8 branch and call it stable-rc-0.6
+locally.
 \begin{verbatim}
-$ git checkout -b my-stable-rc-0.6
+$ git checkout -b stable-rc-0.8 origin/stable-rc-0.8
 \end{verbatim}
-\item Merge (cherry-pick) the commit id you want into the current branch
+\item Merge (cherry-pick) the commit id you want (in this example,
+fa9869a20bbfb479fafd63ef41e890919df3b6d9) into the current branch
 \begin{verbatim}
-$ git cherry-pick 093af91834hf8a8df90238928f920023
+$ git cherry-pick fa9869a20bbfb479fafd63ef41e890919df3b6d9
 \end{verbatim}
-\item Synchronize stable-rc-0.6 with upstream
+\item Synchronize the local stable-rc-0.8 with upstream origin/stable-rc-0.8
 \begin{verbatim}
-$ git pull origin stable-rc-0.6
+$ git pull origin origin/stable-rc-0.8
 \end{verbatim}
-\item Push your changes from my-stable-rc-0.6 into stable-rc-0.6 and then up to
-the server (origin).
+\item Push your changes from stable-rc-0.8 into origin/stable-rc-0.8 and then
+up to the server (origin).
 \begin{verbatim}
-$ git push origin my-stable-rc-0.6:stable-rc-0.6.
+$ git push origin stable-rc-0.8:origin/stable-rc-0.8
 \end{verbatim}
 \end{enumerate}
 
@@ -280,39 +305,49 @@ $ git push origin my-stable-rc-0.6:stable-rc-0.6.
 The need for this most commonly occurs when a new stable branch is released,
 but may be used for any other remote branches you wish to retrieve.
 
-Let's say that stable-0.6 was just released, and your current local branches
+Let's say that stable-0.8 was just released, and your current local branches
 look like this:
 \begin{verbatim}
-$ git branch
-devel
-* master
-origin
-stable-0.3
-stable-0.4
-stable-rc-0.4
-stable-rc-0.5
-stable-rc-0.6
+$ git branch -r
+  origin/HEAD
+  origin/devel
+  origin/devel-iceweasel
+  origin/devel-shadow
+  origin/master
+  origin/stable-0.3
+  origin/stable-0.4
+  origin/stable-0.6
+  origin/stable-rc-0.4
+  origin/stable-rc-0.5
+  origin/stable-rc-0.6
+  origin/stable-rc-0.7
 \end{verbatim}
 
-To grab the new stable-0.6 and stable-rc-0.7 (the next stable release
-candidate)
-you would do the following:
+New remote branches will automatically be added on your next pull, so just run
+(preferably with the local master checked out):
 \begin{verbatim}
-$ git fetch ssh://scm.sourcemage.org/smgl/grimoire.git stable-0.6:stable-0.6
+$ git pull
 \end{verbatim}
-
-This tells git to fetch the remote branch named stable-0.6 (before the ":") and
-call it stable-0.6 (after the ":") into the current git repository.
-
-If you want this branch to be updated on a pull, you will also need to add
-the branch information to .git/remotes/origin:
-\begin{verbatim}
-Pull: refs/heads/stable-0.6:refs/heads/stable-0.6
-Pull: refs/heads/stable-rc-0.7:refs/heads/stable-rc-0.7
+And then you should now have the new remote branches:
+\begin{verbatim}
+$ git branch -r
+  origin/HEAD
+  origin/devel
+  origin/devel-iceweasel
+  origin/devel-shadow
+  origin/master
+  origin/stable-0.3
+  origin/stable-0.4
+  origin/stable-0.6
+  origin/stable-0.7
+  origin/stable-0.8
+  origin/stable-rc-0.4
+  origin/stable-rc-0.5
+  origin/stable-rc-0.6
+  origin/stable-rc-0.7
+  origin/stable-rc-0.8
 \end{verbatim}
 
-These two lines will add pull information for stable-0.6 and stable-rc-0.7.
-
 \chapter{Writing a spell}
 \section{PREPARE}
 Even before DETAILS, this file is sourced and cane be used to setup variables
@@ -366,8 +401,7 @@ SOURCE_URL[0]=${PREPARE_SOURCE_URL[0]:-http://www.fun.org/download/$SOURCE}
 \end{verbatim}
 
 Note: The \$\{VAR``:-string\}  syntax means if \$VAR is not empty, then use
-\$VAR,
-if it is empty, then use the string.
+\$VAR, if it is empty, then use the string.
 
 Note: We keep all of the checks out of DETAILS and use PREPARE for the
 ugliness.
@@ -446,7 +480,7 @@ Example:
 SOURCE_DIRECTORY=$BUILD_DIRECTORY/$SPELL-$VERSION
 \end{verbatim}
 
-\subsection{SOURCE_URL}
+\subsection{SOURCE\_URL}
 SOURCE\_URL[*]
 	An array where you specify as many targets of where to download the
 	source from. Must specify the full path (including filename) of the
@@ -504,7 +538,7 @@ SOURCE_HASH=sha512:<hash>:UPSTREAM_HASH
 (actual hash ommited due to insane length)
 \end{verbatim}
 
-\subsection{SOURCE_GPG}
+\subsection{SOURCE\_GPG}
 SOURCE\_GPG/SOURCEn\_GPG
 	A signature used to verify the source file. Consists of
 	<key file>:<signature file>:<verification level>. The key file has to