git-pw (Patchwork subcommand for Git)

git-pw is a tool for integrating Git with Patchwork, the web-based patch tracking system.

Important

git-pw only supports Patchwork 2.0+ and REST API support must be enabled on the server end. You can check for support by browsing /about for your given instance. If this page returns a 404, you are using Patchwork < 2.0.

The pwclient utility can be used to interact with older Patchwork instances or instances with the REST API disabled.

Installation

The easiest way to install git-pw and its dependencies is using pip. To do so, run:

$ pip install git-pw

You can also install git-pw manually. First, install the required dependencies. On Fedora, run:

$ sudo dnf install python-requests python-click python-pbr python-arrow \
  python-tabulate

On Ubuntu, run:

$ sudo apt-get install python-requests python-click python-pbr python-arrow \
  python-tabulate

Once dependencies are installed, clone this repo and run setup.py:

$ git clone https://github.com/getpatchwork/git-pw
$ cd git-pw
$ sudo python setup.py

Getting Started

To begin, you’ll need to configure Git settings appropriately. The following settings are required:

pw.server

The URL for the Patchwork instance. This will typically look like. For example:

https://patchwork.ozlabs.org/
pw.project

The project name or list-id. This will appear in the URL when using the web UI:

https://patchwork.ozlabs.org/project/{project_name}/list/

You also require authentication - you can use either API tokens or a username/password combination:

pw.token
The API token for you Patchwork account.
pw.username
The username for your Patchwork account.
pw.password
The password for your Patchwork account.

You can set these settings using the git config command. This should be done in the repo in which you intend to apply patches. For example, to configure the Patchwork project, run:

$ git config pw.server 'https://patchwork.ozlabs.org/api/1.0/'
$ git config pw.project 'patchwork'

Development

If you’re interested in contributing to git-pw, first clone the repo:

$ git clone https://github.com/getpatchwork/git-pw
$ cd git-pw

Create a virtualenv, then install the package in editable mode:

$ virtualenv .venv
$ source .venv/bin/activate
$ pip install --editable .

Usage

git-pw

git-pw is a tool for integrating Git with Patchwork.

git-pw can interact with individual patches, complete patch series, and customized bundles. The three major subcommands are patch, bundle, and series.

The git-pw utility is a wrapper which makes REST calls to the Patchwork service. To use git-pw, you must set up your environment by configuring your Patchwork server URL and either an API token or a username and password. To configure the server URL, run:

git config pw.server http://pw.server.com/path/to/patchwork

To configure the token, run:

git config pw.token token

Alternatively, you can pass these options via command line parameters or environment variables.

For more information on any of the commands, simply pass --help to the appropriate command.

git-pw [OPTIONS] COMMAND [ARGS]...

Options

--debug

Output more information about what’s going on.

--token <token>

Authentication token.

--username <username>

Authentication username.

--password <password>

Authentication password.

--server <server>

Patchwork server address/hostname.

--project <project>

Patchwork project.

--version

Show the version and exit.

Environment variables

PW_TOKEN

Provide a default for --token

PW_USERNAME

Provide a default for --username

PW_PASSWORD

Provide a default for --password

PW_SERVER

Provide a default for --server

PW_PROJECT

Provide a default for --project

bundle

Interact with bundles.

Bundles are custom, user-defined groups of patches. Bundles can be used to keep patch lists, preserving order, for future inclusion in a tree. There’s no restriction of number of patches and they don’t even need to be in the same project. A single patch also can be part of multiple bundles at the same time. An example of Bundle usage would be keeping track of the Patches that are ready for merge to the tree.

git-pw bundle [OPTIONS] COMMAND [ARGS]...
apply

Apply bundle.

Apply a bundle locally using the ‘git-am’ command.

git-pw bundle apply [OPTIONS] BUNDLE_ID [ARGS]...

Arguments

BUNDLE_ID

Required argument

ARGS

Optional argument(s)

download

Download bundle in mbox format.

Download a bundle but do not apply it.

git-pw bundle download [OPTIONS] BUNDLE_ID

Arguments

BUNDLE_ID

Required argument

list

List bundles.

List bundles on the Patchwork instance.

git-pw bundle list [OPTIONS] [NAME]

Options

--owner <owner>

Show only bundles with these owners. Should be an email or name. Private bundles of other users will not be shown.

--limit <limit>

Maximum number of bundles to show.

--page <page>

Page to retrieve bundles from. This is influenced by the size of LIMIT.

--sort <sort>

Sort output on given field.

Arguments

NAME

Optional argument

show

Show information about bundle.

Retrieve Patchwork metadata for a bundle.

git-pw bundle show [OPTIONS] BUNDLE_ID

Arguments

BUNDLE_ID

Required argument

patch

Interact with patches.

Patches are the central object in Patchwork structure. A patch contains both a diff and some metadata, such as the name, the description, the author, the version of the patch etc. Patchwork stores not only the patch itself but also various metadata associated with the email that the patch was parsed from, such as the message headers or the date the message itself was received.

git-pw patch [OPTIONS] COMMAND [ARGS]...
apply

Apply patch.

Apply a patch locally using the ‘git-am’ command.

git-pw patch apply [OPTIONS] PATCH_ID [ARGS]...

Options

--series <series>

Series to include dependencies from. Defaults to latest.

--deps, --no-deps

When applying the patch, include dependencies if available. Defaults to using the most recent series.

Arguments

PATCH_ID

Required argument

ARGS

Optional argument(s)

download

Download a patch diff/mbox.

Download a patch but do not apply it.

git-pw patch download [OPTIONS] PATCH_ID

Options

--diff

Show patch in diff format.

--mbox

Show patch in mbox format.

Arguments

PATCH_ID

Required argument

list

List patches.

List patches on the Patchwork instance.

git-pw patch list [OPTIONS] [NAME]

Options

--state <state>

Show only patches matching these states. Should be slugified representations of states. The available states are instance dependant.

--submitter <submitter>

Show only patches by these submitters. Should be an email or name.

--delegate <delegate>

Show only patches by these delegates. Should be an email or username.

--archived

Include patches that are archived.

--limit <limit>

Maximum number of patches to show.

--page <page>

Page to retrieve patches from. This is influenced by the size of LIMIT.

--sort <sort>

Sort output on given field.

Arguments

NAME

Optional argument

show

Show information about patch.

Retrieve Patchwork metadata for a patch.

git-pw patch show [OPTIONS] PATCH_ID

Arguments

PATCH_ID

Required argument

update

Update a patch.

Updates a Patch on the Patchwork instance. Some operations may require admin or maintainer permissions.

git-pw patch update [OPTIONS] PATCH_ID

Options

--commit-ref <commit_ref>

Set the patch commit reference hash

--state <state>

Set the patch state. Should be a slugified representation of a state. The available states are instance dependant.

--delegate <delegate>

Set the patch delegate. Should be unique user identifier: either a username or a user’s email address.

--archived <archived>

Set the patch archived state.

Arguments

PATCH_ID

Required argument

series

Interact with series.

Series are groups of patches, along with an optional cover letter. Series are mostly dumb containers, though they also contain some metadata themselves, such as a version (which is inherited by the patches and cover letter) and a count of the number of patches found in the series.

git-pw series [OPTIONS] COMMAND [ARGS]...
apply

Apply series.

Apply a series locally using the ‘git-am’ command.

git-pw series apply [OPTIONS] SERIES_ID [ARGS]...

Arguments

SERIES_ID

Required argument

ARGS

Optional argument(s)

download

Download series in mbox format.

Download a series but do not apply it.

git-pw series download [OPTIONS] SERIES_ID

Arguments

SERIES_ID

Required argument

list

List series.

List series on the Patchwork instance.

git-pw series list [OPTIONS] [NAME]

Options

--submitter <submitter>

Show only series by these submitters. Should be an email or name.

--limit <limit>

Maximum number of series to show.

--page <page>

Page to retrieve series from. This is influenced by the size of LIMIT.

--sort <sort>

Sort output on given field.

Arguments

NAME

Optional argument

show

Show information about series.

Retrieve Patchwork metadata for a series.

git-pw series show [OPTIONS] SERIES_ID

Arguments

SERIES_ID

Required argument

Release Notes

1.0.0-2

Upgrade Notes

  • Project configuration, e.g. via git config pw.project, is now required. Previously, not configuring a project would result in items for for all projects being listed. This did not scale for larger instances such as patchwork.ozlabs.org and proved confusing for some users. If this functionality is required, you must explicitly request it using the * character, e.g. git pw patch list --project='*'.

1.0.0

Prelude

Initial release of git-pw using the new REST API provided in Patchwork 2.0