pivotal-flow
v2.0.0
Published
๐ A command-line tool that helps you manage & automate your workflow to use with PivotalTracker.
Downloads
31
Readme
pivotal-flow ๐
A command-line tool that helps you manage & automate your workflow to use with PivotalTracker.
Install
# install pivotal-flow globally
# you can check if it was installed correctly by running `pivotal-flow --version`
npm install -g pivotal-flow
# initialize pivotal-flow
pivotal-flow init
pivotal-flow
is built to work with husky
๐ถ along with the Pivotal GitHub integration.
Commands
Run pivotal-flow --help
to see usage & documentation.
you can also use the
pf
alias forpivotal-flow
.
init
A guided questionnaire to set-up pivotal-flow
with the basic configuration:
$ pivotal-flow init
# generate a basic configuration file in your home directory.
start
Create a new story or work on an existing story (from the stories in your PivotalTracker project(s)):
$ pivotal-flow start
# start working on a story guided by a questionnaire
git-hooks via husky
pivotal-flow
also provides a few git-hooks to automate a few tasks when working with PivotalTracker
as your project management tool. You can add the provided hooks using husky.
In order to use the hooks from pivotal-flow
, add it as a dependency to your npm project:
$ npm install --save-dev pivotal-flow
# install it as a dev-dependency
Then add the hooks and/or commands to your package.json
:
},
"scripts": {
// ...
+ "start:story": "pivotal-flow start"
},
"husky": {
"hooks": {
+ "post-checkout": "pivotal-flow hook check-story-id-in-branch",
+ "prepare-commit-msg": "pivotal-flow hook add-story-id-to-commit",
+ "commit-msg": "pivotal-flow hook check-story-id-in-commit",
}
}
}
Hooks
check-story-id-in-branch
post-checkout
- check that all newly created branches have a PivotalTracker story id
in the branch name.
Why do we need the ID in the branch?
This allows the GitHub integration to send updates to pivotal to show branch & PR information in a story.
add-story-id-to-commit
add-story-id-to-commit
added as a prepare-commit-msg
hook will pick up story id
from the branch name (if it is present) and append it to each commit message.
Again, this allows the GitHub integration to send updates to PivotalTracker
of commit information in a story.
check-story-id-in-commit
check-story-id-in-commit
as a commit-msg
hook - checks if each new commit message contains the story id
as well.
In case you're not using the add-story-id-to-commit
hook or don't want to enforce story id being present in every branch name, this hook makes sure the story id is present in the commit message (added by other means by the user).
Configuration
Once the init
command is run, it creates a config file in your home directory. This is meant to be a per-user configuration.
You can modify/add the configuration file in multiple levels which are supported via cosmiconfig.
Currently, a configuration file looks like the following:
{
"projects": [
{
"name": "Alpha",
"id": 1234567
},
{
"name": "Bravo",
"id": 7654321
}
],
"pivotalApiToken": "abcde*****************************"
}
NOTE: Since the pivotalApiToken
is meant to be private, we discourage adding the pivotal-flow
configuration file to source control.
Configuration Options
|Option|Type|Description|
|---|---|---|
|pivotalApiToken
|string
|API Token from PivotalTracker.|
|projects
|project[]
|An array of PivotalTracker
projects which will be part of your workflow for creating / working on stories.|
|projects[i].name
|string
|The name of the project (or an alias) to be used when picking among projects in the different commands.|
|projects[i].id
|string|number
|Each PivotalTracker
project has an id
which you can find by referring to your project's URL. For example, if your project's URL is https://www.pivotaltracker.com/n/projects/1234567
then the project id
would be 1234567
. This is required to query the stories from the project|
Commands in action
Starting a new story
Run pivotal-flow
(alias: pf
) as a local/global command to start creating stories from the command line:
Work on an existing story
Fuzzy search
Other
Using pivotal-flow
hooks alongside Pivotal GitHub Integration
ensures your updates (commits, pushes, merges etc) on GitHub are posted directly and automatically to your Pivotal stories.
Follow instructions for and the Pivotal GitHub Integration
to set-up the entire flow for your repository.
Credits
The concept of adding story ids (picked from the branch-name) to all commits are from the awesome git-tracker
project by @stevenharman - ported to husky/node implementation in pivotal-flow
's add-story-id-to-commit
hook.