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 to 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 series dependencies if available. Dependencies are retrieved from the most recent series by default. Defaults to the value of ‘git config pw applyPatchDeps’ else ‘true’.

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.

--before <BEFORE>#: Show only items before a given date in ISO 8601 format

--since <SINCE>#: Show only items since a given date in ISO 8601 format

--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.

--before <BEFORE>#: Show only items before a given date in ISO 8601 format

--since <SINCE>#: Show only items since a given date in ISO 8601 format

--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