[clang] 1ab37d9 - [clang-format] Update documentation
Nico Weber via cfe-commits
cfe-commits at lists.llvm.org
Mon Jul 4 12:42:18 PDT 2022
Author: Nico Weber
Date: 2022-07-04T21:42:08+02:00
New Revision: 1ab37d996ce376129fa435b63ca50246cc8c2f8d
URL: https://github.com/llvm/llvm-project/commit/1ab37d996ce376129fa435b63ca50246cc8c2f8d
DIFF: https://github.com/llvm/llvm-project/commit/1ab37d996ce376129fa435b63ca50246cc8c2f8d.diff
LOG: [clang-format] Update documentation
- Update `clang-format --help` output after b1f0efc06acc.
- Update `clang-format-diff.py` help text, which apparently hasn't
been updated in a while. Since git and svn examples are now part
of the help text, remove them in the text following the help text.
Differential Revision: https://reviews.llvm.org/D129050
Added:
Modified:
clang/docs/ClangFormat.rst
Removed:
################################################################################
diff --git a/clang/docs/ClangFormat.rst b/clang/docs/ClangFormat.rst
index 16b316cdf0667..150f0aa009e93 100644
--- a/clang/docs/ClangFormat.rst
+++ b/clang/docs/ClangFormat.rst
@@ -17,7 +17,7 @@ to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.
.. code-block:: console
- $ clang-format -help
+ $ clang-format --help
OVERVIEW: A tool to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.
If no arguments are specified, it formats the code from standard input
@@ -40,9 +40,11 @@ to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.
Use with caution, as this might lead to dramatically
diff ering format depending on an option being
supported or not.
- --assume-filename=<string> - Override filename used to determine the language.
- When reading from stdin, clang-format assumes this
- filename to determine the language.
+ --assume-filename=<string> - Set filename used to determine the language and to find
+ .clang-format file.
+ Only used when reading from stdin.
+ If this is not passed, the .clang-format file is searched
+ relative to the current working directory when reading stdin.
Unrecognized filenames are treated as C++.
supported:
CSharp: .cs
@@ -62,7 +64,7 @@ to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.
--fallback-style=<string> - The name of the predefined style used as a
fallback in case clang-format is invoked with
-style=file, but can not find the .clang-format
- file to use.
+ file to use. Defaults to 'LLVM'.
Use -fallback-style=none to skip formatting.
--ferror-limit=<uint> - Set the maximum number of clang-format errors to emit
before stopping (0 = no limit).
@@ -92,17 +94,19 @@ to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.
determined by the QualifierAlignment style flag
--sort-includes - If set, overrides the include sorting behavior
determined by the SortIncludes style flag
- --style=<string> - Coding style, currently supports:
- LLVM, GNU, Google, Chromium, Microsoft, Mozilla, WebKit.
- Use -style=file to load style configuration from
- .clang-format file located in one of the parent
- directories of the source file (or current
- directory for stdin).
- Use -style=file:<format_file_path> to explicitly specify
- the configuration file.
- Use -style="{key: value, ...}" to set specific
- parameters, e.g.:
- -style="{BasedOnStyle: llvm, IndentWidth: 8}"
+ --style=<string> - Set coding style. <string> can be:
+ 1. A preset: LLVM, GNU, Google, Chromium, Microsoft,
+ Mozilla, WebKit.
+ 2. 'file' to load style configuration from a
+ .clang-format file in one of the parent directories
+ of the source file (for stdin, see --assume-filename).
+ If no .clang-format file is found, falls back to
+ --fallback-style.
+ --style=file is the default.
+ 3. 'file:<format_file_path>' to explicitly specify
+ the configuration file.
+ 4. "{key: value, ...}" to set specific parameters, e.g.:
+ --style="{BasedOnStyle: llvm, IndentWidth: 8}"
--verbose - If set, shows the list of processed files
Generic Options:
@@ -235,37 +239,41 @@ output of a unified
diff and reformats all contained lines with
.. code-block:: console
- usage: clang-format-
diff .py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE]
+ usage: clang-format-
diff .py [-h] [-i] [-p NUM] [-regex PATTERN] [-iregex PATTERN] [-sort-includes] [-v] [-style STYLE]
+ [-fallback-style FALLBACK_STYLE] [-binary BINARY]
- Reformat changed lines in
diff . Without -i option just output the
diff that
- would be introduced.
+ This script reads input from a unified
diff and reformats all the changed
+ lines. This is useful to reformat all the lines touched by a specific patch.
+ Example usage for git/svn users:
- optional arguments:
- -h, --help show this help message and exit
- -i apply edits to files instead of displaying a
diff
- -p NUM strip the smallest prefix containing P slashes
- -regex PATTERN custom pattern selecting file paths to reformat
- -style STYLE formatting style to apply (LLVM, Google, Chromium, Mozilla,
- WebKit)
-
-So to reformat all the lines in the latest :program:`git` commit, just do:
+ git
diff -U0 --no-color --relative HEAD^ | clang-format-
diff .py -p1 -i
+ svn
diff --
diff -cmd=
diff -x-U0 | clang-format-
diff .py -i
-.. code-block:: console
+ It should be noted that the filename contained in the
diff is used unmodified
+ to determine the source file to update. Users calling this script directly
+ should be careful to ensure that the path in the
diff is correct relative to the
+ current working directory.
- git
diff -U0 --no-color HEAD^ | clang-format-
diff .py -i -p1
-
-With Mercurial/:program:`hg`:
+ optional arguments:
+ -h, --help show this help message and exit
+ -i apply edits to files instead of displaying a
diff
+ -p NUM strip the smallest prefix containing P slashes
+ -regex PATTERN custom pattern selecting file paths to reformat (case sensitive, overrides -iregex)
+ -iregex PATTERN custom pattern selecting file paths to reformat (case insensitive, overridden by -regex)
+ -sort-includes let clang-format sort include blocks
+ -v, --verbose be more verbose, ineffective without -i
+ -style STYLE formatting style to apply (LLVM, GNU, Google, Chromium, Microsoft, Mozilla, WebKit)
+ -fallback-style FALLBACK_STYLE
+ The name of the predefined style used as afallback in case clang-format is invoked with-style=file, but can not
+ find the .clang-formatfile to use.
+ -binary BINARY location of binary to use for clang-format
+
+To reformat all the lines in the latest Mercurial/:program:`hg` commit, do:
.. code-block:: console
hg
diff -U0 --color=never | clang-format-
diff .py -i -p1
-In an SVN client, you can do:
-
-.. code-block:: console
-
- svn
diff --
diff -cmd=
diff -x -U0 | clang-format-
diff .py -i
-
The option `-U0` will create a
diff without context lines (the script would format
those as well).
More information about the cfe-commits
mailing list