# 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:
-To add your own, create a file ~/.config/patman directory like this:
+ git config sendemail.aliasesfile doc/git-mailrc
+
+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.
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.
+
+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.
projects / u-boot / blobdiff