What is this? =============
This tool is a python script which: - Creates patch directly from your branch - Cleans them up - Inserts a cover letter and change lists - Sends them out to selected people
It is intended to automate patch creation and make it a less error-prone process. It is useful for U-Boot and Linux work so far, since it uses the kernel's checkpatch.pl script.
It is configured almost entirely by tags it finds in your commits. So for example if you put:
Series-to: fred.blogs@napier.co.nz
in one your commits, the series will be sent there (only one 'to' is allowed at present).
How to use this tool ====================
This tool requires a certain way of working:
- Maintain a number of branches, one for each patch series you are working on - Add tags into the commits within each branch to indicate where the series should be sent, cover letter, version, etc. Most of these are normally in the top commit so it is easy to change them with 'git commit --amend' - Each branch tracks the upstream branch, so that this script can automatically determine the number of commits in it - Check out a branch, and run this script to create and send out your patches
How to configure it ===================
Create a file ~/.config/patman directory like this:
[alias] me: Simon Glass sjg@chromium.org
u-boot: U-Boot Mailing List u-boot@lists.denx.de mikef: Mike Frysinger vapier@gentoo.org wolfgang: Wolfgang Denk wd@denx.de albert: Albert ARIBAUD albert.u.boot@aribaud.net <<<<
This contains useful aliases for people you want to send patches to you. Note: This should probably use git's alias feature instead.
Find checkpatch.pl from a Linux kernel tree, and put it in ~/bin/checkpatch.pl
How to run it =============
First do a dry run:
$ ./tools/scripts/patman/patman -n
If it can't detect the upstream branch, try telling it how many patches there are in your series:
$ ./tools/scripts/patman/patman -n -c5
This will create patch files in your current directory and tell you who it is thinking of sending them to. Take a look at the patch files.
How to add tags ===============
To make this script useful you must add tags like the following. Most can only appear once. They must appear in the first column of a line.
Series-to: email / alias Email address / alias to send patch series to
Series-cc: email / alias, ... Email address / alias to Cc patch series to (you can add this multiple times)
Series-version: n Sets the version number of this patch series
Series-prefix: prefix Sets the subject prefix. Normally empty but it can be RFC for RFC patches, or RESEND if you are being ignored.
Cover-letter: This is the patch set title blah blah more blah blah END Sets the cover letter contents for the series. The first line will become the subject of the cover letter
Series-notes: blah blah blah blah more blah blah END Sets some notes for the patch series, which you don't want in the commit messages, but do want to send, The notes are joined together and put after the cover letter. Can appear multiple times.
Signed-off-by: Their Name <email> A sign-off is added automatically to your patches (this is probably a bug). If you put this tag in your patches, it will override your default signoff.
Tested-by: Their Name <email> Acked-by: Their Name <email> These indicate that someone has acked or tested your patch. When you get this reply on the mailing list, you can add this tag to the relevant commit and the script will include it when you send out the next version. If 'Tested-by:' is set to yourself, it will be removed. No one will believe you.
Series-changes: n - Guinea pig moved into its cage - Other changes ending with a blank line <blank line> This can appear in any commit. It lists the changes for a particular version n of that commit. The change list is created based on this information. Each commit gets its own change list and also the whole thing is repeated in the cover letter.
By adding your change lists into your commits it is easier to keep track of what happened. When you amend a commit, remember to update the log there and then, knowing that the script will do the rest.
Various other tags are silently removed, like these Chrome OS and Gerrit tags:
BUG=... TEST=... Change-Id: Review URL: Reviewed-on: Reviewed-by:
Exercise for the reader: Try adding some tags to one of your current patch series and see how the patches turn out.
Other thoughts ==============
This script has been split into sensible files but still needs work. Most of these are indicated by a TODO in the code.
It would be nice if this could handle the In-reply-to side of things.
The git Cc: tag should be respected.
The tests are incomplete. Use the -t flag to run them.
There might be a few other features not mentioned in this README. They might be bugs.
Simon Glass (1): Add patch submission script all in one commit
tools/scripts/patman/.gitignore | 1 + tools/scripts/patman/README | 202 +++++++++++++++++ tools/scripts/patman/command.py | 72 ++++++ tools/scripts/patman/commit.py | 77 +++++++ tools/scripts/patman/gitutil.py | 210 +++++++++++++++++ tools/scripts/patman/patchstream.py | 426 +++++++++++++++++++++++++++++++++++ tools/scripts/patman/patman | 1 + tools/scripts/patman/patman.py | 127 +++++++++++ tools/scripts/patman/series.py | 220 ++++++++++++++++++ tools/scripts/patman/settings.py | 50 ++++ tools/scripts/patman/terminal.py | 86 +++++++ tools/scripts/patman/test.py | 248 ++++++++++++++++++++ 12 files changed, 1720 insertions(+), 0 deletions(-) create mode 100644 tools/scripts/patman/.gitignore create mode 100644 tools/scripts/patman/README create mode 100644 tools/scripts/patman/command.py create mode 100644 tools/scripts/patman/commit.py create mode 100644 tools/scripts/patman/gitutil.py create mode 100644 tools/scripts/patman/patchstream.py create mode 120000 tools/scripts/patman/patman create mode 100755 tools/scripts/patman/patman.py create mode 100644 tools/scripts/patman/series.py create mode 100644 tools/scripts/patman/settings.py create mode 100644 tools/scripts/patman/terminal.py create mode 100644 tools/scripts/patman/test.py