This is a command line utility for doing project management with Redmine in Bash. It is written completely in Bash.
This has been tested with Bash v3.2 and should work with anything greater as well. The only dependency is JQ, which can be installed on Mac via Homebrew with:
brew install jq
Git clone this repo or copy the pm.sh
file somehwere onto your
computer, and then make sure that its directory is in your shell
environment's $PATH
.
I've done this on my computer by creating a bin
folder in my home
directory, then symlinking the utility like so:
mkdir -p ~/bin
ln -s /full/path/to/pm/pm.sh ~/bin/pm
And then adding this to ~/.bash_profile
:
export PATH="~/bin:$PATH"
The utility is made to access data in Redmine on a per-project basis.
For convenience, you can configure your different project directories on
your computer to access different projects on Redmine (or even different
instances of Redmine) when you are running the pm
command from within
those directories.
To do this, create a .redmine
file in your project's working
directory, and provide it with your Redmine access credentials and
default configuration. See the .redmine.sample
file for an example
configuration.
In this file, these are the available configurations:
API_KEY
: Your Redmine API key.DOMAIN
: The domain of the Redmine instance with which you wish to interact.
PROJECT_ID
: The numeric project ID of the project with which the working directory corresponds.CURRENT_VERSION_ID
: If you're using Redmine "Versions" (aka "Target Version" or "Fixed Version") to manage your sprints, this is useful to set the default target version for listing Issues.
General usage is of the form:
pm [flags] function [secondary function] [arguments]
Where the parts in []
are optional. The simplest valid command is:
pm function
Some functions require inputs which can be passed either via
[arguments]
or may also be piped into pm
.
Use pm -h
for a list of available [flags]
.
NOTE: If running with any [flags]
, the [flags]
must come before the function
.
Here are the available functions and secondary functions:
project
: Get the configured Project for the current working directory. Can override Project to get with-p
flag.queries
: Get the Saved Queries for Project.statuses
: Get the available Statuses for querying and updating Issues.categories
: Get the available Categories for querying and updating Issues.users
: Get the available Users for querying and updating Issues.user
: Get the current user.versions
: Get the available Versions for querying and updating Issues. Format of output can be specifies with-f
flag.versions update
: Update a Version. Use the-c true
flag with a quoted JSON object to specify the attributes to update.issue
: Get Issue information. Pass Issue ID as argument (or piped in).issue open
: Open Issue in browser. Pass Issue ID as argument (or piped in).issue update
: Update Issue using-c true
with quoted JSON object to specify the attributes to update.issues
: List multiple Issues. Pass space-separated Issue IDs as arguments, or newline-separated issues piped in. You can also query via-q
,-v
,-a
, or-c true
custom query with JSON.issues update
: Update multiple Issues usingc true
with quoted JSON object to specify the attributes to update. The Issue IDs to update need to be passed in as space-separated arguments, or newline-separated issues piped in.issues open
: Open multiple Issues in the browser. Pass space-separated Issue IDs as arguments, or newline-separated issues piped in. You can also query via-q
,-v
,-a
, or-c true
custom query with JSON.
One thing to note about the above is that since arguments can be piped
in, you can combine multiple calls to pm
by piping the output of one
call to the input of the next. For example, you can pipe the Issue IDs
from a custom Issue
query to the Issue update command.
This example does a custom query for Issues from Target Version 15
assigned to my user ID and created after January 15th, 2020, and updates
them with Status ID 5. Note that we format the output of the first
command to output IDs only (-f ids
) and also silence any progress output
statements (-z true
) so that they don't get piped in as Issue ID inputs to the
second command:
pm -v 15 -f ids -z true -c true issues '{"assigned_to_id": 3, "created_on": ">=2020-01-15"}' | pm -c true issues update '{"status_id": 5}'
Some other example commands:
pm -f ids -z true issues 8191 8338 | pm -f summary issues
pm -c true -f summary issues '{"created_on": ">=2019-10-01", "fixed_version_id": "!249"}'
pm -c true -f summary -z true issues '{"created_on": "lw"}' | sort
pm issue open 7784
pm versions
pm queries
pm -v 250 issues