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