Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.markdown

piv - Pivotal Tracker Command Line Utility

A simple command line utility providing an opinionated workflow for development using Pivotal Tracker and GIT.

Commands

Setting up piv

Usage:

  piv setup -e, --email=EMAIL -p, --project=PROJECT

Options:

  -p, --project=PROJECT  # Pivotal Tracker project name.
  -e, --email=EMAIL      # Pivotal Tracker user email.
  -f, [--force]          # Force generation of .piv and installation of commit hook.

Description:

  This command needs to be run from the root directory of the application.
  It generates a configuration file named .piv containing the supplied project's id and user's access token and email.
  Additionally, if the application is under an SCM, it will disable tracking of the configuration file in SCM and
  install a commit hook to enable auto-tagging commit messages.
  By default, this command assumes absence of the configuration file and commit hook.
  This command will only generate the configuration file and install commit hook if none is present.
  Otherwise, use --force option to bypass these checks.

Creating a Pivotal Tracker story

Usage:

  piv create STORY_TYPE -n, --name#NAME

Options:

  -n, --name#NAME
  -d, --desc, [--description#DESCRIPTION]
  -o, --owner, [--owned-by#OWNED_BY]
  -e, [--estimate#N]
  -l, [--labels#LABELS]                    # Comma-separated list of labels for this story

Description:

  Create a new bug, feature or chore story in the current Pivotal Tracker project.

Updating an existing Pivotal Tracker story

Usage:

  piv update STORY_ID

Options:

  -t, --type, [--story-type#STORY_TYPE]
  -n, [--name#NAME]
  -d, --desc, [--description#DESCRIPTION]
  -o, --owner, [--owned-by#OWNED_BY]
  -r, --requester, [--requested-by#REQUESTED_BY]
  -e, [--estimate#N]
  -l, [--labels#LABELS]                           # Comma-separated list of new labels for this story

Description:

  Update an existing Pivotal Tracker story.

Searching existing Pivotal Tracker stories

Usage:

  piv search

Options:

  -t, [--type#TYPE]
  -l, [--label#LABEL]
  -o, --owner, [--owned-by#OWNED_BY]
  -s, [--state#STATE]
  -n, [--limit=N]

Description:

  This command will return all stories belonging to the specified Pivotal Tracker project in the absence of all search filters.

Listing unstarted Pivotal Tracker stories in current or backlog iteration

Usage:

  piv list

Options:

  -n, [--limit=N]
                    # Default: 10

Description:

  Lists stories belonging to the current Pivotal Tracker project that are prioritized but not yet started ordered by priority.

Show details of an existing Pivotal Tracker story

Usage:

  piv show [STORY_ID]

Description:

  Show details of story.

Starting a Pivotal Tracker story

Usage:

  piv start [STORY_ID]

Options:

  -v, [--verbose]  # Show story details
  -f, [--force]    # Start story regardless of its current status and ownership status

Description:

  This command will start the specified story only if it is either unscheduled or unstarted and is not owned by some other user.
  In order to start story regardless of meeting these conditions, use --force option.

Starting the next assigned Pivotal Tracker story

Usage:

  piv next

Description:

  This command will start the next story in queue that is unstarted and owned by current user.

Viewing current Pivotal Tracker story

Usage:

  piv current

Options:

  -d, --details, [--with-details]

Description:

  Show current story.

Commenting on current Pivotal Tracker story

Usage:

  piv comment [COMMENT_TEXT]

Description:

  Add a comment to the current story.

Finishing current Pivotal Tracker story

Usage:

  piv finish

Description:

  Finish current story.

Delivering all finished Pivotal Tracker stories

Usage:

  piv deliver

Description:

  Deliver all finished stories belonging to current Pivotal Tracker project.

Committing without tagging the commit message with pivotal story id

Usage:

  git commit-skip-piv [OPTIONS]

Options:

  Same as available to git-commit.

Description:

  For a piv-enabled project, allows commits without the need to tag the commit messages with pivotal story id.

Commiting changes that finish the current Pivotal Tracker story

Usage:

  git finish [OPTIONS]

Options:

  Same as available to git-commit.

Description:

  For a piv-enabled project, this GIT command does the following:
  * Tags the commit with current story id and makes the commit.
  * If commit was successfully tagged, pushes the local changes to remote.
  * If changes were successfully pushed to remote, marks the current story as finished in Pivotal Tracker.
  * If changes were not pushed to remote, reverts the current commit keeping the changes in the working tree.

Contributing

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
  • Fork the project
  • Start a feature/bugfix branch
  • Commit and push until you are happy with your contribution
  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright

Copyright (c) 2010 The Turing Studio, Inc. See LICENSE.txt for further details.

Something went wrong with that request. Please try again.