# Copyright (c) 2011 The Chromium OS Authors.
#
-# See file CREDITS for list of people who contributed to this
-# project.
-#
-# This program is free software; you can redistribute it and/or
-# modify it under the terms of the GNU General Public License as
-# published by the Free Software Foundation; either version 2 of
-# the License, or (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program; if not, write to the Free Software
-# Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-# MA 02111-1307 USA
+# SPDX-License-Identifier: GPL-2.0+
#
What is this?
in one of your commits, the series will be sent there.
+In Linux and U-Boot this will also call get_maintainer.pl on each of your
+patches automatically (unless you use -m to disable this).
+
How to use this tool
====================
How to configure it
===================
-For most cases patman will locate and use the file 'doc/git-mailrc' in
-your U-Boot directory. This contains most of the aliases you will need.
+For most cases of using patman for U-Boot development, patman can use the
+file 'doc/git-mailrc' in your U-Boot directory to supply the email aliases
+you need. To make this work, tell git where to find the file by typing
+this once:
+
+ git config sendemail.aliasesfile doc/git-mailrc
-To add your own, create a file ~/.config/patman directory like this:
+For both Linux and U-Boot the 'scripts/get_maintainer.pl' handles figuring
+out where to send patches pretty well.
+
+During the first run patman creates a config file for you by taking the default
+user name and email address from the global .gitconfig file.
+
+To add your own, create a file ~/.patman like this:
>>>>
# patman alias file
used. Failing that you can put it into your path or ~/bin/checkpatch.pl
+If you want to change the defaults for patman's command-line arguments,
+you can add a [settings] section to your .patman file. This can be used
+for any command line option by referring to the "dest" for the option in
+patman.py. For reference, the useful ones (at the moment) shown below
+(all with the non-default setting):
+
+>>>
+
+[settings]
+ignore_errors: True
+process_tags: False
+verbose: True
+
+<<<
+
+
+If you want to adjust settings (or aliases) that affect just a single
+project you can add a section that looks like [project_settings] or
+[project_alias]. If you want to use tags for your linux work, you could
+do:
+
+>>>
+
+[linux_settings]
+process_tags: True
+
+<<<
+
+
How to run it
=============
First do a dry run:
-$ ./tools/scripts/patman/patman -n
+$ ./tools/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
+$ ./tools/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.
-$ ./tools/scripts/patman/patman -n -c5 -s1
+$ ./tools/patman/patman -n -c5 -s1
Similar to the above, but skip the first commit and take the next 5. This
is useful if your top commit is for setting up testing.
+How to install it
+=================
+
+The most up to date version of patman can be found in the U-boot sources.
+However to use it on other projects it may be more convenient to install it as
+a standalone application. A distutils installer is included, this can be used
+to install patman:
+
+$ cd tools/patman && python setup.py install
+
+
How to add tags
===============
commit. Most can only appear once in the whole series.
Series-to: email / alias
- Email address / alias to send patch series to (you can add this
- multiple times)
+ Email address / alias to send patch series to (you can add this
+ multiple times)
Series-cc: email / alias, ...
- Email address / alias to Cc patch series to (you can add this
- multiple times)
+ 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
+ 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.
+ Sets the subject prefix. Normally empty but it can be RFC for
+ RFC patches, or RESEND if you are being ignored. The patch subject
+ is like [RFC PATCH] or [RESEND PATCH].
+ In the meantime, git format.subjectprefix option will be added as
+ well. If your format.subjectprefix is set to InternalProject, then
+ the patch shows like: [InternalProject][RFC/RESEND PATCH]
+
+Series-name: name
+ Sets the name of the series. You don't need to have a name, and
+ patman does not yet use it, but it is convenient to put the branch
+ name here to help you keep track of multiple upstreaming efforts.
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
+ Sets the cover letter contents for the series. The first line
+ will become the subject of the cover letter
+
+Cover-letter-cc: email / alias
+ Additional email addresses / aliases to send cover letter to (you
+ can add this multiple times)
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.
+ 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.
+
+Commit-notes:
+blah blah
+blah blah
+more blah blah
+END
+ Similar, but for a single commit (patch). These notes will appear
+ immediately below the --- cut in the patch file.
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 the default signoff that patman automatically adds.
+ 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 the default signoff that patman automatically adds.
+ Multiple duplicate signoffs will be removed.
Tested-by: Their Name <email>
+ Reviewed-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.
+ These indicate that someone has tested/reviewed/acked 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 (where duplicate change lines are merged).
-
- 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.
-
-Cc: Their Name <email>
- This copies a single patch to another email address.
+ 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 (where duplicate change lines are merged).
+
+ 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.
+
+Patch-cc: Their Name <email>
+ This copies a single patch to another email address. Note that the
+ Cc: used by git send-email is ignored by patman, but will be
+ interpreted by git send-email if you use it.
+
+Series-process-log: sort, uniq
+ This tells patman to sort and/or uniq the change logs. It is
+ assumed that each change log entry is only a single line long.
+ Use 'sort' to sort the entries, and 'uniq' to include only
+ unique entries. If omitted, no change log processing is done.
+ Separate each tag with a comma.
Various other tags are silently removed, like these Chrome OS and
Gerrit tags:
Change-Id:
Review URL:
Reviewed-on:
-Reviewed-by:
-
+Commit-xxxx: (except Commit-notes)
Exercise for the reader: Try adding some tags to one of your current
patch series and see how the patches turn out.
Where Patches Are Sent
======================
-Once the patches are created, patman sends them using gti send-email. The
+Once the patches are created, patman sends them using git send-email. The
whole series is sent to the recipients in Series-to: and Series-cc.
-You can Cc individual patches to other people with the Cc: tag. Tags in the
-subject are also picked up to Cc patches. For example, a commit like this:
+You can Cc individual patches to other people with the Patch-cc: tag. Tags
+in the subject are also picked up to Cc patches. For example, a commit like
+this:
>>>>
commit 10212537b85ff9b6e09c82045127522c0f0db981
Author: Mike Frysinger <vapier@gentoo.org>
-Date: Mon Nov 7 23:18:44 2011 -0500
+Date: Mon Nov 7 23:18:44 2011 -0500
x86: arm: add a git mailrc file for maintainers
This should make sending out e-mails to the right people easier.
- Cc: sandbox, mikef, ag
- Cc: afleming
+ Patch-cc: sandbox, mikef, ag
+ Patch-cc: afleming
<<<<
will create a patch which is copied to x86, arm, sandbox, mikef, ag and
afleming.
+If you have a cover letter it will get sent to the union of the Patch-cc
+lists of all of the other patches. If you want to sent it to additional
+people you can add a tag:
+
+Cover-letter-cc: <list of addresses>
+
+These people will get the cover letter even if they are not on the To/Cc
+list for any of the patches.
+
Example Work Flow
=================
Also, the patch on the list that you were waiting for has been merged,
so you can drop your wip commit. So you resync with upstream:
- git fetch origin (or whatever upstream is called)
+ git fetch origin (or whatever upstream is called)
git rebase origin/master
and use git rebase -i to edit the commits, dropping the wip one. You add
It would be nice if this could handle the In-reply-to side of things.
-The tests are incomplete, as is customary. Use the -t flag to run them,
-and make sure you are in the tools/scripts/patman directory first:
+The tests are incomplete, as is customary. Use the --test flag to run them,
+and make sure you are in the tools/patman directory first:
$ cd /path/to/u-boot
- $ cd tools/scripts/patman
- $ patman -t
+ $ cd tools/patman
+ $ ./patman --test
Error handling doesn't always produce friendly error messages - e.g.
putting an incorrect tag in a commit may provide a confusing message.