From: W. Trevor King <wking@tremily.us>
Date: Fri, 29 Nov 2013 23:09:53 +0000 (-0800)
Subject: Merge branch 'mit-license'
X-Git-Tag: v1.0~1
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=3ba6fc9;p=swc-git-example.git

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

3ba6fc98e65521690c44858ac1056704ac445d51