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. Defaults to the value of ‘git config pw.token’.

--username <USERNAME>

Authentication username. Defaults to the value of ‘git config pw.username’.

--password <PASSWORD>

Authentication password. Defaults to the value of ‘git config pw.password’.

--server <SERVER>

Patchwork server address/hostname. Defaults to the value of ‘git config pw.server’.

--project <PROJECT>

Patchwork project. Defaults the value of ‘git config pw.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]...

add

Add one or more patches to a bundle.

Append the provided PATCH_IDS to bundle BUNDLE_ID.

Requires API version 1.2 or greater.

git-pw bundle add [OPTIONS] BUNDLE_ID PATCH_IDS...

Options

-f, --format <fmt>

Output format. Defaults to the value of ‘git config pw.format’ else ‘table’.

Options:simple | table | csv | yaml

Arguments

BUNDLE_ID

Required argument

PATCH_IDS

Required argument(s)

apply

Apply bundle.

Apply a bundle locally using the ‘git-am’ command. Any additional ARGS provided will be passed to the ‘git-am’ command.

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

Arguments

BUNDLE_ID

Required argument

ARGS

Optional argument(s)

create

Create a bundle.

Create a bundle with the given NAME and patches from PATCH_ID.

Requires API version 1.2 or greater.

git-pw bundle create [OPTIONS] NAME PATCH_IDS...

Options

--public, --private

Allow other users to view this bundle. If private, only you will be able to see this bundle.

-f, --format <fmt>

Output format. Defaults to the value of ‘git config pw.format’ else ‘table’.

Options:simple | table | csv | yaml

Arguments

NAME

Required argument

PATCH_IDS

Required argument(s)

delete

Delete a bundle.

Delete bundle BUNDLE_ID.

Requires API version 1.2 or greater.

git-pw bundle delete [OPTIONS] BUNDLE_ID

Options

-f, --format <fmt>

Output format. Defaults to the value of ‘git config pw.format’ else ‘table’.

Options:simple | table | csv | yaml

Arguments

BUNDLE_ID

Required argument

download

Download bundle in mbox format.

Download a bundle but do not apply it. OUTPUT is optional and can be an output full file path or a directory or - to output to stdout. If OUTPUT is not provided, the output path will be automatically chosen.

git-pw bundle download [OPTIONS] BUNDLE_ID [OUTPUT]

Arguments

BUNDLE_ID

Required argument

OUTPUT

Optional 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, name or ID. Private bundles of other users will not be shown.

--sort <FIELD>

Sort output on given field.

Options:id | -id | name | -name
--page <PAGE>

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

--limit <LIMIT>

Maximum number of items to show.

-c, --column <COLUMN>

Columns to be included in output.

Options:ID | Name | Owner | Public
-f, --format <fmt>

Output format. Defaults to the value of ‘git config pw.format’ else ‘table’.

Options:simple | table | csv | yaml

Arguments

NAME

Optional argument

remove

Remove one or more patches from a bundle.

Remove the provided PATCH_IDS to bundle BUNDLE_ID.

Requires API version 1.2 or greater.

git-pw bundle remove [OPTIONS] BUNDLE_ID PATCH_IDS...

Options

-f, --format <fmt>

Output format. Defaults to the value of ‘git config pw.format’ else ‘table’.

Options:simple | table | csv | yaml

Arguments

BUNDLE_ID

Required argument

PATCH_IDS

Required argument(s)

show

Show information about bundle.

Retrieve Patchwork metadata for a bundle.

git-pw bundle show [OPTIONS] BUNDLE_ID

Options

-f, --format <fmt>

Output format. Defaults to the value of ‘git config pw.format’ else ‘table’.

Options:simple | table | csv | yaml

Arguments

BUNDLE_ID

Required argument

update

Update a bundle.

Update bundle BUNDLE_ID. If PATCH_IDs are specified, this will overwrite all patches in the bundle. Use ‘bundle add’ and ‘bundle remove’ to add or remove patches.

Requires API version 1.2 or greater.

git-pw bundle update [OPTIONS] BUNDLE_ID

Options

--name <name>
--patch <patch_ids>

Add the specified patch(es) to the bundle.

--public, --private

Allow other users to view this bundle. If private, only you will be able to see this bundle.

-f, --format <fmt>

Output format. Defaults to the value of ‘git config pw.format’ else ‘table’.

Options:simple | table | csv | yaml

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. Any additional ARGS provided will be passed to 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 patch in diff or mbox format.

Download a patch but do not apply it. OUTPUT is optional and can be an output file path or a directory or - to output to stdout. If OUTPUT is not provided, the output path will be automatically chosen.

git-pw patch download [OPTIONS] PATCH_ID [OUTPUT]

Options

--diff

Show patch in diff format.

--mbox

Show patch in mbox format.

Arguments

PATCH_ID

Required argument

OUTPUT

Optional 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, name or ID.

--delegate <DELEGATE>

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

--hash <HASH>

Show only patches with these hashes.

--archived

Include patches that are archived.

--sort <FIELD>

Sort output on given field.

Options:id | -id | name | -name | date | -date
--page <PAGE>

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

--limit <LIMIT>

Maximum number of items to show.

-c, --column <COLUMN>

Columns to be included in output.

Options:ID | Date | Name | Submitter | State | Archived | Delegate
-f, --format <fmt>

Output format. Defaults to the value of ‘git config pw.format’ else ‘table’.

Options:simple | table | csv | yaml

Arguments

NAME

Optional argument

show

Show information about patch.

Retrieve Patchwork metadata for a patch.

git-pw patch show [OPTIONS] PATCH_ID

Options

-f, --format <fmt>

Output format. Defaults to the value of ‘git config pw.format’ else ‘table’.

Options:simple | table | csv | yaml

Arguments

PATCH_ID

Required argument

update

Update one or more patches.

Updates one or more Patches on the Patchwork instance. Some operations may require admin or maintainer permissions.

git-pw patch update [OPTIONS] PATCH_IDS...

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 and can be configured using ‘git config pw.states’.

Options:new | under-review | accepted | rejected | rfc | not-applicable | changes-requested | awaiting-upstream | superseded | deferred
--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.

-f, --format <fmt>

Output format. Defaults to the value of ‘git config pw.format’ else ‘table’.

Options:simple | table | csv | yaml

Arguments

PATCH_IDS

Required argument(s)

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. Any additional ARGS provided will be passed to 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. OUTPUT is optional and can be an output path or - to output to stdout. If OUTPUT is not provided, the output path will be automatically chosen.

git-pw series download [OPTIONS] SERIES_ID [OUTPUT]

Options

--separate

Download each series patch to a separate file

--combined

Download all series patches to one file

Arguments

SERIES_ID

Required argument

OUTPUT

Optional 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, name or ID.

--sort <FIELD>

Sort output on given field.

Options:id | -id | name | -name | date | -date
--page <PAGE>

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

--limit <LIMIT>

Maximum number of items to show.

-c, --column <COLUMN>

Columns to be included in output.

Options:ID | Date | Name | Version | Submitter
-f, --format <fmt>

Output format. Defaults to the value of ‘git config pw.format’ else ‘table’.

Options:simple | table | csv | yaml

Arguments

NAME

Optional argument

show

Show information about series.

Retrieve Patchwork metadata for a series.

git-pw series show [OPTIONS] SERIES_ID

Options

-f, --format <fmt>

Output format. Defaults to the value of ‘git config pw.format’ else ‘table’.

Options:simple | table | csv | yaml

Arguments

SERIES_ID

Required argument