More on Repeated Amend

workflows-repeated-amend.Rmd

@@ -9,7 +9,7 @@ One of the principle joys of version control is the freedom to experiment withou
 Using a Git commit is like using anchors and other protection when climbing. If you're crossing a dangerous rock face you want to make sure you've used protection to catch you if you fall. Commits play a similar role: if you make a mistake, you can't fall past the previous commit. Coding without commits is like free-climbing: you can travel much faster in the short-term, but in the long-term the chances of catastrophic failure are high! Like rock climbing protection, you want to be judicious in your use of commits. Committing too frequently will slow your progress; use more commits when you're in uncertain or dangerous territory. Commits are also helpful to others, because they show your journey, not just the destination.
   </blockquote>
   <p class="caption">
-  <a href="http://r-pkgs.had.co.nz/git.html#git-commit">R Packages, Hadley Wickham</a></p>
+  <a href="http://r-pkgs.had.co.nz/git.html#git-commit">R Packages, Hadley Wickham</a> (@r-pkgs-book)</p>
 </div>
 
 Let's talk about this:
@@ -24,22 +24,39 @@ This can lead to an awful lot of tiny commits. This is absolutely fine and nothi
 
 The Repeated Amend is a pattern where, instead of cluttering your history with lots of tiny commits, you build up a "good" commit gradually, by amending.
 
-## Workflow sketch
+*Yes, there are other ways to do this, e.g. via squashing and interactive rebase, but I think amending is the best way to get started.*
 
-Start with your project in a functional state and synced up with your GitHub remote. Imagine we start at commit C, with previous commits B and A:
+## Workflow sketch
 
-``` bash
-... -- A -- B -- C
-```
+### Initial condition
 
-Make a small step towards your goal. Satisfy yourself that all is well:
+Start with your project in a functional state:
 
   * R package? Run your tests or `R CMD check`.
   * Data analysis? Re-run your script or re-render your `.Rmd` with the new chunk.
   * Website or book? Make sure the project still compiles.
   * You get the idea.
 
-Stage those changes and make a commit with the message "WIP", meaning "work in progress".
+Make sure your "working tree is clean" and you are synced up with your GitHub remote. `git status` should show something like:
+
+``` bash
+On branch master
+Your branch is up to date with 'origin/master'.
+
+nothing to commit, working tree clean
+```
+
+### Get to work
+
+Imagine we start at commit C, with previous commit B and, before that, A:
+
+``` bash
+... -- A -- B -- C
+```
+
+Make a small step towards your goal. Re-check that your project "works".
+
+Stage those changes and make a commit with the message "WIP", meaning "work in progress". Do this in RStudio or in the shell:
 
 ``` bash
 git commit -m "WIP"
@@ -55,12 +72,14 @@ A -- B -- C -- WIP*
 
 **Don't push!** The `*` above signifies a commit that exists only in your local repo, not (yet) on GitHub.
 
-Do a bit more work. Re-check that your project is still in a functional state. Commit again but this time **amend** your previous commit. The `--no-edit` part retains the current commit message of "WIP":
+Do a bit more work. Re-check that your project is still in a functional state. Commit again but this time **amend** your previous commit. RStudio offers a check box for "Amend previous commit" or in the shell:
 
 ``` bash
 git commit --amend --no-edit
 ```
 
+The `--no-edit` part retains the current commit message of "WIP".
+
 **Don't push!**  Your history now looks like this:
 
 ``` bash
@@ -73,7 +92,7 @@ Keep going like this.
 
 Let's say you've finally achieved your goal. One last time, check that your project is functional and in a state you're willing to share with others.
 
-Commit, amending again, but with a real commit message this time. Think of this as commit D. Push.
+Commit, amending again, but with a real commit message this time. Think of this as commit D. Push. Do this in RStudio or the shell:
 
 ``` bash
 git commit --amend -m "Implement awesome feature; closes #43"
@@ -96,19 +115,27 @@ Imagine you're in the middle of a Repeated Amend workflow:
 A -- B -- C -- WIP*
 ```
 
-and you make some changes that break your project, e.g. tests start failing. These changes are not yet committed. You want to fall back to the last good state, represented by `WIP*`.
+and you make some changes that break your project, e.g. tests start failing. These bad changes are not yet committed, but they are saved. You want to fall back to the last good state, represented by `WIP*`.
 
 In Git lingo, you want to do a **hard reset** to the `WIP*` state. With the command line:
 
 ``` bash
 git reset --hard
 ```
 
-This is also possible in RStudio. Click on "Diff" or "Commit". Select a file with changes you do not want. Use "Discard All" to discard all changes in that file. Use "Discard chunk" to discard changes more selectively. Repeat for each affected file until you are back to a desirable state. Carry on.
+which is implicitly the same as
 
-If you committed a bad state, go *link to come* for more general discussion of resets.
+``` bash
+git reset --hard HEAD
+```
+
+which says: "reset my files to their state at the most recent commit".
 
-## Why we don't push intermediate progress
+This is also possible in RStudio. Click on "Diff" or "Commit". Select a file with changes you do not want. Use "Discard All" to discard all changes in that file. Use "Discard chunk" to discard changes in that file, selectively. Repeat this procedure for each affected file until you are back to an acceptable state. Carry on.
+
+If you committed a bad state, go to *link to come* for more reset scenarios.
+
+## Why don't we push intermediate progress?
 
 Amending a commit is an example of what's called "rewriting Git history".
 
@@ -138,7 +165,13 @@ I'm deliberately showing two histories that sort of look the same, in terms of c
 
 You are in a pickle now, as you can neither push nor pull. You have two choices:
 
-  * Hard reset your local repo to `C` (`git reset --hard HEAD^`) and pull from GitHub. Do this if you have collaborators who may have pulled that state.
-  * Force push to GitHub (`git push --force`). Do this if you have no collaborators or you have reason to believe they have not pulled.
-
+  * Hard reset your local repo to `C` (`git reset --hard HEAD^`) and pull from GitHub. Do this if you have collaborators who may have pulled that state. GitHub and local history now show this:
+    ``` bash
+    A -- B -- C -- WIP (85bf30a)
+    ```
+  * Force push to GitHub (`git push --force`). Do this if you have no collaborators or you have reason to believe they have not pulled. GitHub and local history now show this:
+    ``` bash
+    A -- B -- C -- WIP* (6e884e6)
+    ```
+
 Now you are synced up again.