From: Dwaipayan Ray <dwaipayanray1@gmail.com>
To: joe@perches.com
Cc: linux-kernel-mentees@lists.linuxfoundation.org,
lukas.bulwahn@gmail.com, linux-kernel@vger.kernel.org,
Dwaipayan Ray <dwaipayanray1@gmail.com>
Subject: [PATCH RFC 2/3] docs: add documentation for checkpatch
Date: Wed, 27 Jan 2021 00:05:20 +0530 [thread overview]
Message-ID: <20210126183521.26535-3-dwaipayanray1@gmail.com> (raw)
In-Reply-To: <20210126183521.26535-1-dwaipayanray1@gmail.com>
Add documentation for kernel script checkpatch.pl.
This documentation is also parsed by checkpatch to
enable a verbose mode.
The test descriptions are potentially incomplete
and will be added over time to document all the
message types in checkpatch.
Signed-off-by: Dwaipayan Ray <dwaipayanray1@gmail.com>
---
Documentation/dev-tools/checkpatch.rst | 283 +++++++++++++++++++++++++
1 file changed, 283 insertions(+)
create mode 100644 Documentation/dev-tools/checkpatch.rst
diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
new file mode 100644
index 000000000000..b0f1cab108c8
--- /dev/null
+++ b/Documentation/dev-tools/checkpatch.rst
@@ -0,0 +1,283 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+==========
+Checkpatch
+==========
+
+This document describes the kernel script checkpatch.pl.
+
+.. Table of Contents
+
+ === 1 Introduction
+ === 2 Options
+ === 3 Message Levels
+ === 4 Type Descriptions
+
+1 Introduction
+--------------
+
+Checkpatch (scripts/checkpatch.pl) is a perl script which checks for trivial style
+violations in patches and optionally corrects them. Checkpatch can also be run on
+file contexts and without the kernel tree.
+
+It should be noted that checkpatch may not be always right. At times the human
+judgement should take preference over what checkpatch has to say. If your code looks
+better with the violations, then its probably best left alone.
+
+
+2 Options
+---------
+
+This section will describe the options checkpatch can be run with.
+
+Usage::
+
+ ./scripts/checkpatch.pl [OPTION]... [FILE]...
+
+Available options:
+
+ - -q, --quiet
+
+ Enable quiet mode. All information messages are disabled. Only the
+ messages and a summary report is output.
+
+ - --no-tree
+
+ Run checkpatch without the kernel tree.
+
+ - --no-signoff
+
+ Disable the 'Signed-off-by' line check. The sign-off is a simple line at
+ the end of the explanation for the patch, which certifies that you wrote it
+ or otherwise have the right to pass it on as an open-source patch.
+
+ Example::
+
+ Signed-off-by: Random J Developer <random@developer.example.org>
+
+ Setting this flag effectively stops a message for a missing signed-off-by line
+ in a patch context.
+
+ - --patch
+
+ Treat FILE as a patch. This is the default option and need not be
+ explicitly specified.
+
+ - --emacs
+
+ Set output to emacs compile window format. This allows emacs users to jump
+ from the error in the compile window directly to the offending line in the patch.
+
+ - --terse
+
+ Output only one line per report.
+
+ - --showfile
+
+ Show the diffed file position instead of the input file position.
+
+ - -g, --git
+
+ Treat FILE as a single commit or a git revision range.
+
+ Single commit with:
+
+ - <rev>
+ - <rev>^
+ - <rev>~n
+
+ Multiple commits with:
+
+ - <rev1>..<rev2>
+ - <rev1>...<rev2>
+ - <rev>-<count>
+
+ - -f, --file
+
+ Treat FILE as a regular source file. This option must be used when running
+ checkpatch on source files in the kernel.
+
+ - --subjective, --strict
+
+ Enable stricter tests in checkpatch. By default the tests emitted as CHECK
+ do not activate by default. Use this flag to activate the CHECK tests.
+
+ - --list-types
+
+ Every message emitted by checkpatch has an associated TYPE. Add this flag to
+ display all the types in checkpatch.
+
+ Note that when this flag is active, checkpatch does not read the input FILE, and
+ no message is emitted. Only a list of types in checkpatch is output.
+
+ - --types TYPE(,TYPE2...)
+
+ Only display messages with the given types.
+
+ Example::
+
+ ./scripts/checkpatch.pl mypatch.patch --types EMAIL_SUBJECT,NO_AUTHOR_SIGN_OFF
+
+ - --ignore TYPE(,TYPE2...)
+
+ Strip off messages with the given types.
+
+ Example::
+
+ ./scripts/checkpatch.pl mypatch.patch --ignore EMAIL_SUBJECT,NO_AUTHOR_SIGN_OFF
+
+ - --show-types
+
+ By default checkpatch doesn't display the type associated with the messages.
+ Set this flag to show the message type in the output.
+
+ - --max-line-length=n
+
+ Set the max line length (default 100). On exceeding the given length, a message
+ is emitted.
+
+ The message level is different for patch and file contexts. For patches, a WARNING is
+ emitted. While a milder CHECK is emitted for files. So for file contexts, the --strict
+ flag must also be enabled.
+
+ - --min-conf-desc-length=n
+
+ Set the min description length, if shorter, warn.
+
+ - --tab-size=n
+
+ Set the number of spaces for tab (default 8).
+
+ - --root=PATH
+
+ PATH to the kernel tree root.
+
+ This option must be specified when invoking checkpatch from outside
+ the kernel root.
+
+ - --no-summary
+
+ Suppress the per file summary.
+
+ - --mailback
+
+ Only produce a report in case of Warnings or Errors. Milder Checks are
+ excluded from this.
+
+ - --summary-file
+
+ Include the filename in summary.
+
+ - --debug KEY=[0|1]
+
+ Turn on/off debugging of KEY, where KEY is one of 'values', 'possible',
+ 'type', and 'attr' (default is all off).
+
+ - --fix
+
+ This is an EXPERIMENTAL feature. If correctable errors exists, a file
+ <inputfile>.EXPERIMENTAL-checkpatch-fixes is created which has the
+ automatically fixable errors corrected.
+
+ - --fix-inplace
+
+ EXPERIMENTAL - Similar to --fix but the input file is overwritten with fixes.
+
+ DO NOT USE this flag unless you are absolutely sure and you have a backup in place.
+
+ - --ignore-perl-version
+
+ Override checking of perl version. Runtime errors maybe encountered after
+ enabling this flag if the perl version does not meet the minimum specified.
+
+ - --codespell
+
+ Use the codespell dictionary for checking spelling errors.
+
+ - --codespellfile
+
+ Use the specified codespell file. Default is '/usr/share/codespell/dictionary.txt'.
+
+ - --typedefsfile
+
+ Read additional types from this file.
+
+ - --color[=WHEN]
+
+ Use colors 'always', 'never', or only when output is a terminal ('auto').
+ Default is 'auto'.
+
+ - --kconfig-prefix=WORD
+
+ Use WORD as a prefix for Kconfig symbols (default is `CONFIG_`).
+
+ - -h, --help, --version
+
+ Display the help text.
+
+3 Message Levels
+----------------
+
+Messages in checkpatch are divided into three levels. The levels of messages in
+checkpatch denote the severity of the error. They are:
+
+ - ERROR
+
+ This is the most strict level. Messages of type ERROR must be taken
+ seriously as they denote things that are very likely to be wrong.
+
+ - WARNING
+
+ This is the next stricter level. Messages of type WARNING requires a
+ more careful review. But it is milder than an ERROR.
+
+ - CHECK
+
+ This is the mildest level. These are things which may require some thought.
+
+4 Type Descriptions
+-------------------
+
+This section contains a description of all the message types in checkpatch.
+
+.. Types in this section are also parsed by checkpatch.
+.. Please keep the types sorted alphabetically.
+.. CHECKPATCH_START
+
+EMAIL_SUBJECT
+
+ The subject line should describe the change not the tool used to find
+ the change. Consider a patch entitled:
+
+ 'Fix warning detected by tool <some tool>'.
+
+ This is potentially a bad practice and the actual changes should be
+ summarised in the subject line.
+
+MISSING_SIGN_OFF
+
+ The patch is missing a Signed-off-by line. This error must be taken
+ care of and a Signed-off-by line should be added according to
+ Developer's certificate of Origin.
+
+NO_AUTHOR_SIGN_OFF
+
+ The author of the patch has not signed off the patch. It is required
+ that a simple sign off line should be present at the end of explanation
+ of the patch to denote that the author has written it or otherwise has
+ the rights to pass it on as an open source patch.
+
+ Sometimes this particular warning can also occur when both email address
+ and name of the author do not match the sign off line because checkpatch
+ has no mechanism to say if it is the same person.
+
+ Consider::
+
+ From: John Doe <john.doe@example.com>
+ ...
+ Signed-off-by: J. Doe <john@example2.com>
+
+ While these may point that both the persons are same, checkpatch cannot
+ understand that and in such cases this warning can be ignored.
+
+.. CHECKPATCH_END
--
2.30.0
next prev parent reply other threads:[~2021-01-27 1:35 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-01-26 18:35 [PATCH RFC 0/3] checkpatch: add verbose mode Dwaipayan Ray
2021-01-26 18:35 ` [PATCH RFC 1/3] " Dwaipayan Ray
2021-01-26 20:11 ` Joe Perches
2021-01-26 20:27 ` Dwaipayan Ray
2021-01-26 22:44 ` Joe Perches
2021-01-26 18:35 ` Dwaipayan Ray [this message]
2021-01-26 18:35 ` [PATCH RFC 3/3] docs: add documentation for checkpatch Dwaipayan Ray
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210126183521.26535-3-dwaipayanray1@gmail.com \
--to=dwaipayanray1@gmail.com \
--cc=joe@perches.com \
--cc=linux-kernel-mentees@lists.linuxfoundation.org \
--cc=linux-kernel@vger.kernel.org \
--cc=lukas.bulwahn@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).