git-process 1.1.4 → 2.0.0

data/CHANGELOG.md

@@ -1,4 +1,17 @@
-# CHANGELOG - 1.1.4 #
+# CHANGELOG - 1.2.0 #
+
+### Since 1.1.4 ###
+
+* **Changed git-sync to default to rebasing.** ([GH-112](https://github.com/jdigger/git-process/issues/112))
+* git-sync now can take a branch name to check it out for work ([GH-117](https://github.com/jdigger/git-process/issues/117))
+* Change to use the "native" manpage-based help system for `git help`.
+  ([GH-113](https://github.com/jdigger/git-process/issues/113))
+* `git new-fb` now defaults to doing a `git fetch` before creating the feature branch if a remote is defined.
+  ([GH-118](https://github.com/jdigger/git-process/issues/118))
+* Removed **--interactive** option from git-to-master
+* Updated README and related files.
+* Retries closing a pull request if it gets a 422. ([GH-102](https://github.com/jdigger/git-process/issues/102))
+* Fixed typo in merge error. ([GH-114](https://github.com/jdigger/git-process/issues/114))
 
 ### Since 1.1.3 ###
 

data/LICENSE

@@ -1,22 +1,193 @@
-Copyright (c) 2012 Jim Moore
-
-MIT License
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2012-2013 Jim Moore
+
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work and such
+Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable (except as stated in this section) patent license to make, have
+made, use, offer to sell, sell, import, and otherwise transfer the Work, where
+such license applies only to those patent claims licensable by such Contributor
+that are necessarily infringed by their Contribution(s) alone or by combination
+of their Contribution(s) with the Work to which such Contribution(s) was
+submitted. If You institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work or a
+Contribution incorporated within the Work constitutes direct or contributory
+patent infringement, then any patent licenses granted to You under this License
+for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof
+in any medium, with or without modifications, and in Source or Object form,
+provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+You must cause any modified files to carry prominent notices stating that You
+changed the files; and
+You must retain, in the Source form of any Derivative Works that You distribute,
+all copyright, patent, trademark, and attribution notices from the Source form
+of the Work, excluding those notices that do not pertain to any part of the
+Derivative Works; and
+If the Work includes a "NOTICE" text file as part of its distribution, then any
+Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in the Work by You to the Licensor shall be under the terms and
+conditions of this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify the terms of
+any separate license agreement you may have executed with Licensor regarding
+such Contributions.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names, trademarks,
+service marks, or product names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides the
+Work (and each Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
+including, without limitation, any warranties or conditions of TITLE,
+NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
+solely responsible for determining the appropriateness of using or
+redistributing the Work and assume any risks associated with Your exercise of
+permissions under this License.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law (such as deliberate
+and grossly negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special, incidental,
+or consequential damages of any character arising as a result of this License or
+out of the use or inability to use the Work (including but not limited to
+damages for loss of goodwill, work stoppage, computer failure or malfunction, or
+any and all other commercial damages or losses), even if such Contributor has
+been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may choose to
+offer, and charge a fee for, acceptance of support, warranty, indemnity, or
+other liability obligations and/or rights consistent with this License. However,
+in accepting such obligations, You may act only on Your own behalf and on Your
+sole responsibility, not on behalf of any other Contributor, and only if You
+agree to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "{}" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification within
+third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -11,14 +11,30 @@ See the F.A.Q. for a much more complete explanation for the thoughts and assumpt
 
 ## Unix-based OS (OSX, Linux, etc.) Installation ##
 
-    $ sudo gem install git-process
+If you are using a Ruby sandboxing system like [RVM](https://rvm.io/) or [rbenv](https://github.com/sstephenson/rbenv)
+(either or which I would recommend) then simply do:
 
-Some older operating systems (such as OSX 10.6) are using an old version of RubyGems, which can cause installation problems. Do "`sudo gem update --system`" to fix.
+    $ gem install git-process
+
+If you are not using RVM or rbenv, you will likely need to precede that with "`sudo`".
+
+Some older operating systems (such as OSX 10.6) are using an old version of RubyGems, which can cause installation problems. Do "`gem update --system`" to fix.
 
 ## Windows Installation ##
 
-1. Install Ruby (if you have not sone so already) from http://rubyinstaller.org/
+1. Install Ruby (if you have not done so already) from http://rubyinstaller.org/
+   * If it complains about not being able to compile native code, install [DevKit](http://rubyinstaller.org/downloads).
+   * See [this StackOverflow](http://stackoverflow.com/questions/8100891/the-json-native-gem-requires-installed-build-tools/8463500#8463500) for help.
 2. Open a command prompt and type `gem install git-process`
+3. *THERE IS A KNOWN PROBLEM WITH [HELP ON WINDOWS](https://github.com/jdigger/git-process/issues/120).*
+
+## All Operating Systems ##
+
+To get full `git help` and manpage support, do:
+
+    $ git config --global man.gem-man.cmd "gem man -s"
+    $ git config --global man.viewer gem-man
+    $ alias man="gem man -s"
 
 
 # Overview #
@@ -33,68 +49,11 @@ Some older operating systems (such as OSX 10.6) are using an old version of Ruby
 ## Command List ##
 
 * `git new-fb` - Create a new feature branch based on the integration branch.
-* `git sync` - Gets the latest changes that have happened on the integration branch, then pushes your changes to a "private" branch on the server.
-* `git pull-request` - Creates a Pull Request for the current branch.
+* `git sync` - Gets the latest changes that have happened on the integration branch and remote feature branch, then pushes your changes to a feature branch on the server.
+* `git pull-request` - Create or get a Pull Request for the current branch.
 * `git to-master` - Rebase against the integration branch, then pushes to it. Knows how to deal "intelligently" with pull-requests.
 
-**All commands are well documented within themselves: Use the "-h" switch to see the full documentation.** (e.g., "`git sync -h`")
-
-
-# Workflow #
-
-_The following assumes that the integration branch is "origin/master"._
-
-## Code Review Using Pull Requests ##
-
-1. When starting work on a new feature, use "`git new-fb feature-name`".
-    * This creates a new branch called "`feature-name`" based on "`origin/master`".
-2. After making some changes, if you want to pick up any changes other people have made, as well
-   as save your work on the server, do "`git sync`".
-    * That will merge in the changes that have occurred in "`origin/master`" and then push the
-      result to the "`feature_branch`" branch to the server.
-3. When you feel your work is ready for others to look at, do "`git pull-request`" to ask someone to review your changes.
-    * If no name or number is provided, it is assumed that you want to create a new pull request with the same name as the current branch.
-    * Any changes you make via "`git sync`" are automatically reflected in the pull request.
-4. As a reviewer, to see a pull-request, do "`git pull-request ##`" (where "##" is the pull request number) to check
-   out the branch associated with the pull request in your repository.
-5. If you get the thumbs up from the code-review, use "`git to-master`".
-    * This will merge and push your changes into "`origin/master`", closing the pull request.
-    * If reviewing the pull request via the web interface was sufficient, or there is otherwise not a reason
-      to explicitly checkout the branch first, you can use "`git to-master`" with the pull request number to
-      combine both of these steps.
-5. If you still need to make changes, do so and use "`git sync`" to keep your branch on the
-   server for that feature updated with your work until all issues have been resolved.
-
-```
-$ git new-fb my-feature      # 1
-# do work                    # 2
-$ git commit                 # 3
-$ git sync                   # 4
-# repeat #2-#4 as necessary  # 5
-$ git pull-request           # 6
-# repeat #2-#4 as necessary  # 7
-$ git to-master              # 8
-```
-
-## Working Alone or When Pairing ##
-
-1. When starting work on a new feature, use "`git new-fb feature-name`".
-    * This creates a new branch called "`feature-name`" based on "`origin/master`".
-2. After making some changes, if you want to pick up any changes other people have made, as well
-   as save your work on the server, do "`git sync`".
-    * That will merge in the changes that have occurred in "`origin/master`" and then push the
-      result to the "`feature_branch`" branch to the server.
-3. When you are ready to merge your work into the mainline, "`git to-master`".
-    * This will merge and push your changes into "`origin/master`"
-
-```
-$ git new-fb my-feature      # 1
-# do work                    # 2
-$ git commit                 # 3
-$ git sync                   # 4
-# repeat #2-#4 as necessary  # 5
-$ git to-master              # 6
-```
+**All commands are well documented within themselves: Use the "git help" to see the full documentation.** (e.g., "`git help sync`")
 
 
 ## Configurables ##
@@ -104,7 +63,7 @@ $ git to-master              # 6
 * `gitProcess.integrationBranch` : The name of the integration branch. Defaults to `master`, but can be set to `develop` or other.
 * `gitProcess.keepLocalIntegrationBranch` : Controls asking about removing the local integration branch. Defaults to 'false' (i.e., do not assume the branch should be there).
 * `gitProcess.remoteName` : Explicitly sets the remote server name to use.
-* `gitProcess.defaultRebaseSync`: Should `git sync` default to using rebase instead of merge?
+* `gitProcess.defaultRebaseSync`: Should `git sync` default to using rebase instead of merge? Defaults to 'true' (i.e., Sync using rebase.)
 
 
 # Assumptions #
@@ -114,7 +73,7 @@ $ git to-master              # 6
   * "`git sync`" makes it extremely easy for you to get any changes that are made in "`master`" into your branch so you can react to it immediately.
   * "`git to-master`" then makes it easy to cleanly integrate the changes you have made. If you need to keep the current branch open, use the `--keep` option. Otherwise it closes the branch along with various other house-keeping duties.
 * The process that you use should be essentially the same, regardless of whether you are working alone, or on a large distributed team.
-  * The exception here is "`git pull-request`" since you do not use pull requests when working solo or when pair-programming.
+  * The exception here is "`git pull-request`" since you typically do not use pull requests when working solo or when pair-programming.
 
 
 # Notes #
@@ -123,11 +82,191 @@ $ git to-master              # 6
 * If there is a problem (such as a merge conflict), this will try to resolve such errors for you as much as it can do safely. When it can't do so in an automated way, it will try to tell you the process for doing so manually.
 * The first time you use a GitHub feature (e.g., "`git pull-request`"), this will ask for your username and password. It does not store them, but instead uses them to get an OAuth2 token, which is stored in "`git config gitProcess.github.authToken`".
 * If you want to use a different integration branch other than "`master`", set the "`gitProcess.integrationBranch`" configuration value. (e.g., "`git config gitProcess.integrationBranch my-integ-branch`")
-* This tries to respond "intelligently" to the use of 'rerere'.
 * By default the first server name reported by `git remote` is used as the server/remote name. Since most projects only have a single remote (i.e., "origin") this works most of the time. But if you have multiple remotes and want to explicitly set it, use the `gitProcess.remoteName` configuration option.
 * `git pull-request` shows the URL for the pull request after creating it on the server. Most terminal programs let you click on it to open it in your browser. (e.g., Cmd-Click on OSX.)
 
 
+# Workflow Examples #
+
+## Working Alone On A Local-Only Project ##
+
+Jim is working on "my_project" and needs to start work on a new feature.
+
+```
+[a_branch]$ git new-fb save_the_planet
+  Creating save_tp off of master
+[save_the_planet]$
+```
+
+He does lots of work. Checkin, checkin, checkin.
+
+A sudden new brilliant idea happens.
+
+```
+[save_the_planet]$ git new-fb shave_the_bunnies
+  Creating shave_the_bunnies off of master
+[shave_the_bunnies]$
+```
+
+After creating a Sheering class and tests, he commits his changes.
+
+```
+[shave_the_bunnies]$ git commit
+[shave_the_bunnies]$ git to-master
+  Rebasing shave_the_bunnies against master
+  Removing branch 'shave_the_bunnies'
+[_parking_]$
+```
+
+Time to get back to work on "save_the_planet".
+
+```
+[_parking_]$ git checkout save_the_planet
+[save_the_planet]$ git sync
+  Rebasing save_the_planet against master
+[save_the_planet]$
+```
+
+Do more work. Commit. Commit. Commit.
+
+```
+[save_the_planet]$ git sync
+  Rebasing save_the_planet against master
+[save_the_planet]$
+```
+
+Liking to have a clean history, he squashes and edits the commits to hide
+the evidence of false starts and stupid ideas so that anyone who sees the
+code in the future will think he was simply a genius.
+
+```
+[save_the_planet]$ git rebase -i
+  Rebasing save_the_planet against master
+[save_the_planet]$ git to-master
+  Rebasing save_the_planet against master
+  Removing branch 'save_the_planet'
+[_parking_]$
+```
+
+Time to release to a grateful world.
+
+
+## Working With A Team ##
+
+John, Alice, Bill and Sally are working on "big_monies." Alice and John are pairing and
+need to start work on a new feature.
+
+```
+john-[a_branch]$ git new-fb steal_underpants
+  Fetching the latest changes from the server
+  Creating steal_underpants off of origin/master
+john-[steal_underpants]$
+```
+
+They do lots of work. Checkin, checkin, checkin. It has a lot of steps...
+
+Meanwhile Bill has been working on his great idea:
+
+```
+bill-[some_branch]$ git new-fb awesomo4000
+  Fetching the latest changes from the server
+  Creating awesomo4000 off of origin/master
+bill-[awesomo4000]$
+```
+
+He creates his "Laaaaame" class and checks it in, with a pull request asking Sally to do a code review.
+
+```
+bill-[awesomo4000]$ git commit
+bill-[awesomo4000]$ git pull-request "A.W.E.S.O.M-0 4000 prototype" \
+                    -d "@sally, can you make sure Butters won't recognize it?"
+  Pushing to 'awesomo4000' on 'origin'.
+  Creating a pull request asking for 'awesomo4000' to be merged into 'master' on big_monies.
+  Created pull request at https://github.com/big_monies/pull/3454
+bill-[awesomo4000]$
+```
+
+Sally sees the email. After looking at it in the web interface, she wants to test it.
+
+```
+sally-[other_branch]$ git pull-request 3454
+  Getting #pr_number
+  Fetching the latest changes from the server
+    new branch: awesomo4000
+  Setting upstream/tracking for branch 'awesomo4000' to 'origin/master'.
+sally-[awesomo4000]$ git sync
+  Fetching the latest changes from the server
+  Rebasing awesomo4000 against origin/master
+  Pushing to 'awesomo4000' on 'origin'.
+sally-[awesomo4000]$
+```
+
+After verifying that the tests still work and "it's all good" she promotes the code to integration.
+
+```
+sally-[awesomo4000]$ git to-master
+  Fetching the latest changes from the server
+  Rebasing awesomo4000 against origin/master
+  Pushing to 'awesomo4000' on 'origin'.
+  Removing branch remote 'awesomo4000'
+  Removing branch local 'awesomo4000'
+  Closing a pull request #3454 on origin.
+sally-[_parking_]$
+```
+
+Over lunch Alice gets a brainstorm ("a duck and rubber hose!") and rushes off to her computer:
+
+```
+alice-[lens_cap]$ git sync steal_underpants
+  Fetching the latest changes from the server
+  Creating steal_underpants off of origin/steal_underpants
+  Setting upstream/tracking for branch 'steal_underpants' to 'origin/master'.
+alice-[steal_underpants]$
+```
+
+She makes her changes, syncs back up with the server, and heads over to pair with John again.
+
+```
+alice-[steal_underpants]$ git commit
+alice-[steal_underpants]$ git sync
+  Fetching the latest changes from the server
+  Rebasing steal_underpants against origin/master
+  Pushing to 'steal_underpants' on 'origin'.
+alice-[steal_underpants]$
+```
+
+John, meanwhile, had made some changes of his own.
+
+```
+john-[steal_underpants]$ git commit
+john-[steal_underpants]$ git sync
+  Fetching the latest changes from the server
+  Remote branch has changed
+  Rebasing steal_underpants against origin/steal_underpants
+  Rebasing steal_underpants against origin/master
+  Pushing to 'steal_underpants' on 'origin'.
+john-[steal_underpants]$
+```
+
+At this point, his local branch has Alice's change as well as Bill and
+Sally's A.W.E.S.O.M-O 4000 enhancements.
+
+After confirming with Alice and Bill that everything looks good, he
+pushes his changes up for integration.
+
+```
+john-[steal_underpants]$ git to-master
+  Fetching the latest changes from the server
+  Rebasing steal_underpants against origin/master
+  Pushing to 'steal_underpants' on 'origin'.
+  Removing remote branch 'steal_underpants'
+  Removing local branch 'steal_underpants'
+[_parking_]$
+```
+
+Profit!!
+
+
 # F.A.Q. #
 
 ## Q: How is this different from git-flow or GitHub flow? ##
@@ -142,14 +281,14 @@ $ git to-master              # 6
 Branches are extremely powerful tools that allow for clean organization/modularization of development.
 
 * Branches make it easy to sandbox changes while they are in a state of flux, while at the same time allowing you to be very fearless about making potentially breaking changes.
-    * For example, I commit "green to green": Doing [TDD](http://en.wikipedia.org/wiki/Test-driven_development), I commit every time I have a newly passing test case. So, assuming I'm in a regular development flow, I'm committing my changes every five minutes. Tiny commits, but lots of them. What that means is that if I make a "less than wise choice" at some point, it's trivial to rewind to before I'd made the mistake, potentially keep the throw-away code in another branch while I do my cleanup, and generally use the full power of a revision control system to make my life safer and easier. The branch(es) are pretty chaotic, but that's not a problem because before integrating with the mainline, I take a moment to cleanup: Squash related commits together, write clearer commit messages (since now I know what "the answer" is), and generally move from my drafts to a more finished result. (See below on objections related to "lying with rebase.") That may just be me, though, because I'm very paranoid when it comes to computers. I tend to automatically hit Cmd/Ctl-S every time I type a period when I'm writing, or when I close a block when I'm programming. I have a minimum of three copies/backups around the world of all my important documents. And I "`git sync`" frequently to make sure my machine isn't the only place where all my hard work is being stored. Have I mentioned I don't trust computers?
+    * For example, I commit "green to green": Doing [TDD](http://en.wikipedia.org/wiki/Test-driven_development), I commit every time I have a newly passing test case. So, assuming I'm in a regular development flow, I'm committing my changes every five minutes or so. Tiny commits, but lots of them. What that means is that if I make a "less than wise choice" at some point, it's trivial to rewind to before I'd made the mistake, potentially keep the throw-away code in another branch while I do my cleanup, and generally use the full power of a revision control system to make my life safer and easier. The branch(es) are pretty chaotic, but that's not a problem because before integrating with the mainline, I take a moment to cleanup: Squash related commits together, write clearer commit messages (since now I know what "the answer" is), and generally move from my drafts to a more finished result. (See below on objections related to "lying with rebase.") That may just be me, though, because I'm very paranoid when it comes to computers. I tend to automatically hit Cmd/Ctl-S every time I type a period when I'm writing, or when I close a block when I'm programming. I have a minimum of three copies/backups around the world of all my important documents. And I "`git sync`" frequently to make sure my machine isn't the only place where all my hard work is being stored. Have I mentioned I don't trust computers?
 
 * Branches allow for focused collaboration. Because a branch is about exactly one thing, it means that a team can collaborate around a feature/bug (especially when used in conjunction with a "pull request"), and keep such changes sandboxed until such time that they are ready to bring a larger audience into the mix.
-    * Branches encourage being less "shy" about your code. I have heard, on a number of occasions, developers say "I'm not ready to push this to the server yet because [it's still rough (and embarrassing)]/[it may break other people]/etc." All of those reasons for "hoarding" code are moot with branches.
+    * Branches encourage being less "shy" about your code. I have heard, on a number of occasions, developers say "I'm not ready to push this to the server yet because \[it's still rough (and embarrassing)]/\[it may break other people]/etc." All of those reasons for "hoarding" code are moot with branches.
 
 Jez Humble, a brilliant Principle at ThoughtWorks Studios, talks a lot about how "branches are evil." Unfortunately, people hear that, know how smart he is, and simply repeat it without really understanding what his objections are. Fortunately, he [posted clarification about what's really meant by that](http://continuousdelivery.com/2011/07/on-dvcs-continuous-integration-and-feature-branches/). He essentially says that the problem is that developers abuse branches by not merging with mainline (i.e., "master") on a regular basis. Not constantly getting changes *from* mainline makes life rough when it comes time to integrate. Not putting your changes *into* mainline means that your changes are not being validated (via [Continuous Integration](http://martinfowler.com/articles/continuousIntegration.html), or -- better -- with [Continuous Delivery](http://continuousdelivery.com/)). Both are, in fact, sins akin to not doing automated testing.
 
-Making it "easier to do things right than wrong" (i.e., using branches and keeping them synced with mainline) was the primary motivation for this project. This should be especially evident in the "`git sync`" and "`git to-master`" commands.
+Making it "easier to do things right than wrong" (i.e., using branches and keeping them synced with mainline) was the primary motivation for this project. Every command here is focussed on making it trivial to use branches that stay in sync with mainline and encourage collaboration.
 
 
 ## Q: Why so much emphasis on rebasing? Isn't rebasing a dangerous lie? ##
@@ -158,11 +297,13 @@ Like any powerful tool, "`git rebase`" is "dangerous" if used incorrectly, just
 
 [A famous article](http://paul.stadig.name/2010/12/thou-shalt-not-lie-git-rebase-ammend.html) that people have been parroting in various forms for a while makes the case that rebasing (and its various forms, such as squashing, amending commits, etc.) is a "lie." As with so many things, context is everything.
 
-You almost certainly should *not* rebase things that you have "published." Generally this really means "Don't rebase the 'master' branch!" Fortunately, these scripts make it impossible to rebase the mainline by accident. By default "`git sync`" uses "merge" instead of "rebase" to encourage collaboration. (Though you can easily use "-r" if you know no one else is working on the branch.) When it's time to actually merge your work into the mainline (and thus no one is working against it except in the context of mainline), that's when it gets rebased in.
+You almost certainly should *not* rebase things that you have "published." Generally this really means "Don't rebase the 'master' branch!" Fortunately, these scripts make it impossible to rebase the mainline by accident.
 
 Rebasing "your" code is an extremely useful way of communicating clearly. In the "green to green" scenario above about branches, a lot of noise is generated. If someone wants to review my code, or cherry-pick in my changes, it's too much of a mess to effectively do so. Also, as part of the process of squashing, I have the opportunity to write clearer commit message based upon my newly enhanced understanding. The intermediate commits were my "drafts" and I'm now submitting my cleaned up copy.
 
-If you have ever seen an "active" project that uses a process like "git-flow" that encourages a lot of branching and merging, you've seen how hard it can be to follow a particular line of development. Branch lines are flying around everywhere, and half the commits are pretty much pure noise. (e.g., "Merge branch 'develop' of ... into develop".) It's also hard to follow the order in which commits actually impacted the mainline. In many ways, in practice merges turn into "a truth effectively being a lie (because it's buried in the noise)" versus rebases that are "a lie (changed from it's 'original' form) to tell an effective truth (clean and very clear about its impact)."
+If you have ever seen an "active" project that uses a process like "git-flow" that encourages a lot of branching and merging, you've seen how hard it can be to follow a particular line of development. Branch lines are flying around everywhere, and half the commits are pretty much pure noise. (e.g., "Merge branch 'master' of ... into master".) It's also hard to follow the order in which commits actually impacted the mainline. In many ways, in practice merges turn into "a truth effectively being a lie" (because it's buried in the noise) versus rebases that are "a lie (changed from it's 'original' form) to tell an effective truth" (clean and very clear about its impact).
+
+One significant advantage of using automation like this is that it lets you have the best of both worlds. For example, "`git sync`" uses "rebase" instead of "merge" in a way to is completely safe for collaboration on the same branch. As long as the other people are also using "`git sync`", it will make sure that changes are automatically incorporated with and brought in line. (See the extensive test suite in "`sync_spec.rb`" if you want to see how this works.)
 
 This project is trying to promote clear communication about reality as it applies to the code, over micro-management over no-longer-relevant history. Thus rational for the judicious use of rebase.