Synchronize user stories in Pivotal Tracker with Cucumber features.
If you aren’t using Cucumber, you can still use pickler as a Pivotal Tracker command line client, provided you humor it with a features/ directory containing a tracker.yml file.
gem install tpope-pickler --source=http://gems.github.com echo "api_token: ..." > ~/.tracker.yml echo "project_id: ..." > ~/my/app/features/tracker.yml echo "ssl: [true|false]" >> ~/my/app/features/tracker.yml pickler --help
“ssl” defaults to false if not configured in the yml file.
For details about the Pivotal Tracker API, including where to find your API token and project id, see www.pivotaltracker.com/help/api .
The pull and push commands map the story’s name into the “Feature: …” line and the story’s description with an additional two space indent into the feature’s body. Keep this in mind when entering stories into Pivotal Tracker.
pickler pull [--any-state] [--any-description] [story [story...]]
Download all well formed stories to the features/ directory.
Unless a story is explicitly named on the command line, or an option is specified, pickler filters the stories pull’ed using several criteria. First, Tracker stories that are in the “unscheduled” or “unstared” states are not pulled. (This behavior can be overridden with the “–any-state” option.)
Second, the Tracker story’s description must contain at least one “Scenario:” clause, and the entire content of the description must be a valid Cucumber feature (less the “Feature:” line). If, once a “Feature:” line created from the story’s name is added to the story’s description, the entire block cannot be successfully parsed by Cucumber, then a .feature file will not be written for the story. (This check can be overridden with the “–any-description” option.)
Note that previously unseen stories will be given a numeric file name (that you are encouraged to change), and placed directly below the features/ directory (though they may be moved under features/stories).
pickler push [story [story...]]
Upload all features with a tracker url in a comment on the first line.
This will operate on all “.feature” files under your features/ directory, regardless of directory nesting depth. Files whose first line is not a comment (either blank or containing the tracker /story/ URL for the feature) will be ignored. In addition, to be pushed, the file’s first non-comment, non-blank line must start with the word “Feature:” followed by the string that will be used as the story’s name. Files whose first “active” line is anything other than a Feature name will not be pushed.
Note that new stories (.feature files pushed for the first time) will be given the Tracker state “unscheduled”. Which means that, by default, they will not be downloaded by future “pickler pull” commands unless explicitly named on the command line.
pickler search <query>
List all stories matching the given query.
pickler start <story>
Pull a given feature and change its state to started.
pickler finish <story>
Push a given feature and change its state to finished.
pickler --help
Full list of commands.
pickler <command> --help
Further help for a given command.
No warranties, expressed or implied.
Notably, the push and pull commands are quite happy to blindly clobber features if so instructed. Pivotal Tracker has a history to recover things server side.