README.md in pivotal-github-0.8.1 vs README.md in pivotal-github-0.9.0
- old
+ new
@@ -23,11 +23,11 @@
`git story-commit` makes a standard `git commit` with the story number added to the commit message. This automatically adds a link at Pivotal Tracker between the story and the diff when the branch gets pushed up to GitHub.
For example, when on a branch called `add-markdown-support-62831853`, the `git story-commit` command automatically adds `[#62831853]` to the commit message:
$ git story-commit -am "Add foo bars"
- [add-markdown-support-62831853 6f56414] Add foo bars
+ [add-markdown-support-62831853 6f56414] Add foo bars
The commit message is multiline and includes the story id:
Add foo bars
@@ -60,52 +60,53 @@
$ git story-commit -dam "Remove baz quuxes"
`git story commit` supports multiple story numbers as well. For example, with a branch called `add-things-62831853-31415926`, we could deliver both stories as follows:
$ git story-commit -dam "Remove baz quuxes"
- [add-things-62831853-31415926 7g56429] Remove baz quuxes
+ [add-things-62831853-31415926 7g56429] Remove baz quuxes
The message here is
Remove baz quuxes
[Delivers #62831853 #31415926]
#### Options
- $ git story-commit -h
- Usage: git story-commit [options]
- -m, --message MESSAGE add a commit message (including story #)
- -f, --finish mark story as finished
- -d, --deliver mark story as delivered
- -a, --all commit all changed files
- -h, --help this usage guide
+ $ git story-commit -h
+ Usage: git story-commit [options]
+ -m, --message MESSAGE add a commit message (including story #)
+ -f, --finish mark story as finished
+ -d, --deliver mark story as delivered
+ -a, --all commit all changed files
+ -h, --help this usage guide
Additionally, `git story-commit` accepts any options valid for `git commit`. (`git story-commit` supports the `-a` flag even though that's a valid option to `git commit` so that the compound flag in `git story-commit -am "message"` works.)
### git story-merge
-`git story-merge` merges the current branch into `master`. On a branch called `add-markdown-support-62831853`, `git story-merge` is equivalent to the following:
+`git story-merge` merges the current branch into the target branch (defaults to `master`). On a branch called `add-markdown-support-62831853`, `git story-merge` is equivalent to the following:
$ git checkout master
- $ git merge --no-ff --log add-markdown-support-62831853
+ $ git merge --no-ff --log add-markdown-support-62831853 -m "#[62831853]"
Note that this effectively changes the default merge behavior from fast-forward to no-fast-forward, which makes it possible to use `git log` to see which of the commit objects together have implemented a story. As noted in [A successful Git branching model](http://nvie.com/posts/a-successful-git-branching-model/),
> The `--no-ff` flag causes the merge to always create a new commit object, even if the merge could be performed with a fast-forward. This avoids losing information about the historical existence of a feature branch and groups together all commits that together added the feature… Yes, it will create a few more (empty) commit objects, but the gain is much bigger than that cost.
-In addition, the `--log` option puts the commit messages from the individual commits in the merge message, which arranges for the merge commit itself to appear in the activity log at Pivotal Tracker. This is especially useful for viewing the full diff represented by the commit.
+The `--log` option puts the commit messages from the individual commits in the merge message, while the `-m` flag adds the story id to the commit (optionally marking it finished or delivered with the `-f` or `-d` flag, respectively). Including the story id arranges for the merge commit itself to appear in the activity log at Pivotal Tracker, which is especially useful for viewing the full diff represented by the story.
Because of the way options are chained, passing `-ff` or `--no-log` to `git story-merge` will override the `--no-ff` or `--log` flags (respectively) and thus restore the default behavior of `git merge`.
-Finally, experience shows that it's easy to forget to mark a story finished when making the final commit. As a reminder, the `git story-merge` command exits with a warning if the most recent commit doesn't contain 'Finishes' or 'Delivers' (or 'Finished', 'Delivered', 'Fixes', or 'Fixed'). This behavior can be overriden with the `--force` option.
+Finally, experience shows that it's easy to forget to mark a story finished when making the final commit. As a reminder, the `git story-merge` command exits with a warning if the most recent commit doesn't contain 'Finishes' or 'Delivers' (or 'Finished', 'Delivered', 'Fixes', or 'Fixed'). This behavior can be overriden with the `--override` option.
#### Options
- Usage: git story-merge [options]
- -d, --development BRANCH development branch (defaults to master)
- -f, --force override unfinished story warning
+ Usage: git story-merge [branch] [options]
+ -o, --override override unfinished story warning
+ -f, --finish mark story as finished
+ -d, --deliver mark story as delivered
-h, --help this usage guide
Additionally, `git story-merge` accepts any options valid for `git merge`.
### git story-pull-request
@@ -119,10 +120,10 @@
As with `git story-merge`, by default `git story-pull-request` exits with a warning if the most recent commit doesn't finish the story.
#### Options
Usage: git story-pull-request [options]
- -f, --force override unfinished story warning
+ -o, --override override unfinished story warning
-h, --help this usage guide
### story-open
The `story-open` command (no `git`) opens the current story in the default browser (OS X–only):