Merge branch 'v1.x'

Bring in changes from the maintenance branch with:

  $ git merge --log v1.x

The pre-merge situation is:

  $ git log --graph --topo-order --oneline --decorate --all
  * 97941bc (HEAD, master) cheat-sheet.md: Mention 'config', 'diff', 'branch', 'remote', ...
  | * 9eba52e (tag: v1.1, v1.x) cheat-sheet.md: Fix 'Incorperate' -> 'Incorporate' typo
  |/
  * 36d8c70 (tag: v1.0) cheet-sheet.md: Add a Git-specific cheat sheet
  ...

And the post-merge situation will be:

  $ git log --graph --topo-order --oneline --decorate --all
  *   XXXXXXX (HEAD, tag: v2.0, master) Merge branch 'v1.x'
  |\
  * | 97941bc cheat-sheet.md: Mention 'config', 'diff', 'branch', 'remote', ...
  | * 0eba52e (tag: v1.1, v1.x) cheat-sheet.md: Fix 'Incorperate' -> 'Incorporate' typo
  |/
  * 36d8c70 (tag: v1.0) cheet-sheet.md: Add a Git-specific cheat sheet
  *   3ba6fc9 (public/master) Merge branch 'mit-license'
  |\
  | * 41d3ea1 (public/mit-license, mit-license) COPYING: Fill in the <year> and <copyright holders> markers
  | * e8051dc COPYING: Add MIT license for this project
  |/
  * c481fb5 README.md: Document the syntax used in the README
  * b089fb8 README.md: Begin versioning by explaining the project goals

This is much like our earlier merge in 3ba6fc9, except that this time
there has been development in the master branch (97941bc), so a
fast-forward merge would not be possible in this case.  If you want to
invoke merge with the `--no-ff` option anyway, that's fine, but it
won't change the default handling in this case.

The v2.0 tag is going to come from a:

  $ git tag v2.0

after I stop editing this commit message for XXXXXXX.

cheat-sheet.md: Fix 'Incorperate' -> 'Incorporate' typo

This fixes a typo introduced by 36d8c70 (cheet-sheet.md: Add a
Git-specific cheat sheet, 2013-06-10).

We saw branched development earlier with mit-license and bsd-license,
where we used branches to isolate new feature development in a series
of related commits.  I've put this commit in a new branch as well,
based on the v1.0 commit:

  $ git checkout -b v1.x v1.0

After checking out the new branch, I fixed the typo in cheat-sheet.md
using my text editor.  Then staging and committing was the usual:

  $ git add cheat-sheet.md
  $ git commit --all --verbose

The reason for branching here is slightly different.  In the license
case, we weren't sure if the branch would land in master at all, so we
created experimental "feature branches".  Now we're confident that the
commit will land in master (the focus of future development), but we
think the branch may *also* be useful to folks using the version 1.0
release that aren't quite ready for the upgrades introducted in
97941bc (cheat-sheet.md: Mention 'config', 'diff', 'branch', 'remote',
..., 2013-06-10).  By creating a "maintenance branch" based on the
v1.0 commit, we can provide the fix both to the bleeding edge and
stable release users, ending up with something like:

  $ git log --graph --topo-order --oneline --decorate --all
  *   YYYYYYY Merge branch 'v1.x'
  |\
  | * XXXXXXX (tag: v1.1, v1.x) cheat-sheet.md: Fix 'Incorperate' -> 'Incorporate' typo
  * | 97941bc (master) cheat-sheet.md: Mention 'config', 'diff', 'branch', 'remote', ...
  |/
  * 36d8c70 (tag: v1.0) cheet-sheet.md: Add a Git-specific cheat sheet
  *   3ba6fc9 (public/master) Merge branch 'mit-license'
  ...

Where the v1.1 tag is going to come from a:

  $ git tag v1.1

after I stop editing this commit message for XXXXXXX, and YYYYYYY is
going to merge the v1.x branch into master.

Maintenance branches allow you to fix bugs in earlier versions of your project, and easily incorperate thos

cheat-sheet.md: Mention 'config', 'diff', 'branch', 'remote', ...

Also mention:

* checkout
* rebase
* commit --amend
* reset

With the exception of 'commit --amend', these were all used or
mentioned in Matt Davis' Git-via-GitHub notes [1].

After editing cheat-sheet.md in my text editor, staging and committing
it was the usual:

  $ git add cheat-sheet.md
  $ git commit --all --verbose

[1]: http://git.tremily.us/?p=swc-version-control-git.git;a=commit;h=fda4a1a751211ccbf9deac1d5bea7d7f1ad0f033

cheet-sheet.md: Add a Git-specific cheat sheet

READMEs and COPYING are all well and good, but this project will
probably make more sense if it has some actual content that it's
trying to development.  I'll use the cheat sheet from
http://git.tremily.us/?p=swc-version-control-git.git as an example,
but this would usually be a paper you're writing or code you're using
in your research, or something else you find interesting.

After writing the file in your text editor, staging and committing it
is the usual:

  $ git add cheat-sheet.md
  $ git commit --all --verbose

The long form options (`--all` and `--verbose`) also have short-form
aliases (`-a` and `-v`), which is why the cheat sheet suggests:

  $ git commit -a ...

That is the same as:

  $ git commit --all ...

Because I think this commit gets things into a useful state, I'll tag
it as version 1.0 and release it to the world.  You can tag the last
commit with:

  $ git tag v1.0

Merge branch 'mit-license'

After consultation with my legal department [1], we've settled on the
MIT license.  I merged the branch into master by checking out the
master branch:

  $ git checkout master

Let's take a look at the pre-merge repository state:

  $ git log --graph --topo-order --oneline --decorate --all
  * 69d4950 (bsd-license) COPYING: Fill in the <YEAR> and <OWNER> markers
  * 6ac4438 COPYING: Add the 2-clause BSD license for this project
  | * 41d3ea1 (mit-license) COPYING: Fill in the <year> and <copyright holders> markers
  | * e8051dc COPYING: Add MIT license for this project
  |/
  * c481fb5 (HEAD, master) README.md: Document the syntax used in the README
  * b089fb8 README.md: Begin versioning by explaining the project goals

You can see that the master branch is at c481fb5, and the license
branches split off there into their own lines of development.  Since
we checked out the master branch, the HEAD branch (which always points
to our working version) is also at c481fb5.

Now for the merge:

  $ git merge --log --no-ff mit-license

After the merge, we expect history to look something like:

  $ git log --graph --topo-order --oneline --decorate --all
  *   XXXXXXX (HEAD, master) Merge branch 'mit-license'
  |\
  | * 41d3ea1 (mit-license) COPYING: Fill in the <year> and <copyright holders> markers
  | * e8051dc COPYING: Add MIT license for this project
  |/
  | * 69d4950 (bsd-license) COPYING: Fill in the <YEAR> and <OWNER> markers
  | * 6ac4438 COPYING: Add the 2-clause BSD license for this project
  |/
  * c481fb5 README.md: Document the syntax used in the README
  * b089fb8 README.md: Begin versioning by explaining the project goals

XXXXXX is a marker for this commit.  We don't know what the commit
hash will be yet, because it depends on the contents of this commit
message.  This commit takes the changes made on the mit-license branch
and applies them to the master branch.  The `--log` option I passed to
merge seeds the commit message with a list of commits that were pulled
in:

* mit-license:
  COPYING: Fill in the <year> and <copyright holders> markers
  COPYING: Add MIT license for this project

With good commit message summaries (the first line of the commit
message), this log explains *what* happened in the branch you just
merged.  It's good practice to add some extra text before the log
explaining *why* you're making the merge.

Because there was no development on the master branch since the
mit-license branch broke away, we could have made a "fast-forward"
merge and just moved the master pointer to 41d3ea1.  By passing the
`--no-ff` option to merge, we tell Git to create an explicit merge
commit (this one, XXXXXXX in the graph).  This has two benefits:

* It gives you somewhere to summarize the changes you're pulling in,
  and why you think the branch as a whole will be useful.  The
  individual commit messages in the branch aren't usually focused on
  the big picture motivation.

* It makes it easy to figure out when a series of commits was builting
  up to a single macroscopic change.  For example, in:

    $ git log --graph --topo-order --oneline --decorate
    *   XXXXXXX (HEAD, master) Merge branch 'mit-license'
    |\
    | * 41d3ea1 (mit-license) COPYING: Fill in the <year> and <copyright holders> markers
    | * e8051dc COPYING: Add MIT license for this project
    |/
    * c481fb5 README.md: Document the syntax used in the README
    * b089fb8 README.md: Begin versioning by explaining the project goals

  it's clear that e8051dc and 41d3ea1 are small steps toward
  MIT-licensing.  It would be less clear in the fast-forwarded
  alternative:

    * 41d3ea1 (mit-license, master) COPYING: Fill in the <year> and <copyright holders> markers
    * e8051dc COPYING: Add MIT license for this project
    * c481fb5 README.md: Document the syntax used in the README
    * b089fb8 README.md: Begin versioning by explaining the project goals

It's up to you to decide whether a fast-forward merge or an explicit
merge is more informative for each merge you make.  You can't make a
bad choice, but sometimes one way would be a bit easier for later
developers to understand.  I generally avoid fast-forwarding for any
branches that have more than one commit.

[1]: http://en.wikipedia.org/wiki/Cane_Corso
     He slept through most of the discussion.

COPYING: Fill in the <year> and <copyright holders> markers

This is a separate commit to make is extremely clear what parts of
this file I've written on my own, and which parts I copied from the
Open Source Initiative.  Probably overkill in this case, but sometimes
it's useful if your pulling someone else's work into your repository.

After editing COPYING in my text editor, I committed the changes with:

  $ git commit --all --verbose

We talked about the `--all` option in c481fb5 (README.md: Document the
syntax used in the README, 2013-11-29).  The `--verbose` option option
shows the diff in comments in your editor so you can check them while
you compose the commit message.  This is useful when you're explaining
complicated commits, and it also lets you verify that you are actually
committing what you think you're committing.

COPYING: Add MIT license for this project

The text is from http://opensource.org/licenses/mit-license.html.  I
haven't made any local changes yet, so the `<year>` and `<copyright
holders>` markers are still there.

Because I'm not sure I want to use this license yet (maybe I'll use
the BSD license instead?), I've started a new branch for this commit:

  $ git checkout -b mit-license master

That creates a new branch `mit-license` based on the current `master`
and checks out the new branch.  You can see which branch you're
usually on using `git branch`:

  $ git branch
  * mit-license
    master

The asterix marks the active branch.  Once we've checked out the new
branch, creating commits is just like it used to be:

  $ git add COPYING
  $ git commit

Projects usually include licensing information like this explaining
the terms under which others are allowed to make changes.  The file is
often called COPYING or LICENSE.  The Open Source Initiative has a
list of popular licenses [1], as does the Free Software Foundation
[2].

[1]: http://opensource.org/licenses/
[2]: http://www.gnu.org/licenses/license-list.html

README.md: Document the syntax used in the README

Explain that the file is written in Markdown, and link to the Markdown
spec and GitHub's markup parsing docs.

After adjusting README.md in my text editor, I compared my working
directory with the index using:

  $ git diff

That looked reasonable, so I committed all the modifications using:

  $ git commit --all

The `--all` option tells Git to automatically stage any modifications
or deletions.  I could have used the following:

  $ git add README.md
  $ git commit

and achieved the same result.  Some people like to stage changes
explicitly, and some like to stage them automatically.  Pick whichever
works best for you.

README.md: Begin versioning by explaining the project goals

I created this commit by writing README.md in my text exitor.  I
staged the file for the next commit with:

  $ git add README.md

I committed the staged version of the file with:

  $ git commit