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