patches Patch Tracking System
patches is a patch tracking system. It consists of two parts: a set of commands that build a database of patches from a mailing list and then a set of commands that can search that database. It supports the following features:
Tracking patch status by determining which patches are already committed, have newer versions posted, are RFC, etc.
Applying patches or pull requests with a single command.
Searching for patches using a rich query language.
$ python setup.py install
There are no dependencies if you are working with an existing database. To build a new database, you need python-notmuch.
To get started with the QEMU project:
$ patches fetch http://wiki.qemu.org/patches/patches.json $ patches list Message-id: firstname.lastname@example.org From: Andreas Färber <email@example.com> [0/2] QOM realize, device-only [1/2] qdev: Fold state enum into bool realized [2/2] qdev: Prepare "realized" property Message-id: firstname.lastname@example.org From: Andreas Färber <email@example.com> [0/2] PowerPCCPU subclasses [1/2] target-ppc: Slim conversion of model definitions to QOM subcl.. [2/2] target-ppc: Error out for -cpu host on unknown PVR ... $ patches apply id:firstname.lastname@example.org Applying: qdev: Fold state enum into bool realized Applying: qdev: Prepare "realized" property
fetch command should be run whenever you want to refresh the patch
database; it will download any new patches that have arrived since the
last time you did a fetch.
If you only use patches with one project you can set the default fetch
URL by creating a
~/.patchesrc file with the following contents:
[fetch] # Default URL to use if 'patches fetch' is not given an argument: url=http://wiki.qemu.org/patches/patches.json
The query language supported by patches supports boolean operators: "and" and "or", and unary operators: "not", "any", and "all". Parentheses and string quotation are also supported. Terms are matched using substring search within the subject.
The "any" and "all" operators change whether the search term applies to at least one of the messages in a thread or all messages in a thread.
Special terms have a prefix and can be used to search against other parameters than subject text. The following prefixes are supported:
status:brokenshow broken series (malformed or missing patches)
status:obsoleteshow series that have newer versions available
status:pull-requestshow pull requests
status:rfcshow RFC postings
status:committedshow committed series
status:appliedshow series with a "Thanks, applied" reply
status:unappliedshort hand for
not (status:broken or status:obsolete or status:pull-request or status:rfc or status:committed or status:applied)
status:reviewedshow series where every patch has at least one Reviewed-by
to:ADDRESSshow series where
ADDRESSis on the receipent list
from:ADDRESSshow series where
ADDRESSis the sender
reviewed-by:ADDRESSshow series if a patch has a Reviewed-by by
tested-by:ADDRESSshow series if a patch has a Tested-by by
nacked-by:ADDRESSshow series if a patch has a Nacked-by by
acked-by:ADDRESSshow series if a patch has a Acked-by by
Show unapplied patches where 'Anthony Liguori' was CC'd:
$ patches list 'to:"Anthony Liguori" status:unapplied'
Note that the whole query is wrapped in single quotes. This is necessary to avoid having conflicts between shell quote interpretation and patches.
Limit the search to only patches that haven't been reviewed yet:
$ patches list 'to:"Anthony Liguori" status:unapplied not status:reviewed'
Integration with Notmuch
patches is not meant to be a tool to review patches directly. Instead, it is designed to integrate with mail clients for displaying patches.
list command can be passed
--format=notmuch which will cause
patches to output a notmuch search query instead of a stylized output.
Applying Patches and Pull Requests
Given a message-id of any patch within a series, patches can apply a patch series or pull request. This is meant to allow integration with mail clients that can call out to a external program to process a mail.
patches apply takes a query string, so you usually want to provide a search
string with an
Notifying on Commits
To use the
notify command, you need to add the following stanzas to your
[notify] default_sender=Your Name <email@example.com> smtp_server=your.smtp.server.com events=pulled;committed
This will send out notifications when patches detects that you have committed a patch or pulled a pull request.
There are two very important options when using the notify command. The
--dry-run option will show you the mail you are about to send without
taking any real action. You should always run with
Since patches is looking at a 30 day history, the first time you run it, it will want to send a very large number of notifications.
To setup the database and avoid these notifications, you should run with the
--fake option for the first time. This will pretend that the emails are
being sent without actually sending them.