forked from OSchip/llvm-project
340 lines
16 KiB
ReStructuredText
340 lines
16 KiB
ReStructuredText
===========
|
|
ClangFormat
|
|
===========
|
|
|
|
`ClangFormat` describes a set of tools that are built on top of
|
|
:doc:`LibFormat`. It can support your workflow in a variety of ways including a
|
|
standalone tool and editor integrations.
|
|
|
|
|
|
Standalone Tool
|
|
===============
|
|
|
|
:program:`clang-format` is located in `clang/tools/clang-format` and can be used
|
|
to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.
|
|
|
|
.. START_FORMAT_HELP
|
|
|
|
.. code-block:: console
|
|
|
|
$ 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
|
|
and writes the result to the standard output.
|
|
If <file>s are given, it reformats the files. If -i is specified
|
|
together with <file>s, the files are edited in-place. Otherwise, the
|
|
result is written to the standard output.
|
|
|
|
USAGE: clang-format [options] [<file> ...]
|
|
|
|
OPTIONS:
|
|
|
|
Clang-format options:
|
|
|
|
--Werror - If set, changes formatting warnings to errors
|
|
--Wno-error=<value> - If set don't error out on the specified warning type.
|
|
=unknown - If set, unknown format options are only warned about.
|
|
This can be used to enable formatting, even if the
|
|
configuration contains unknown (newer) options.
|
|
Use with caution, as this might lead to dramatically
|
|
differing format depending on an option being
|
|
supported or not.
|
|
--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
|
|
Java: .java
|
|
JavaScript: .mjs .js .ts
|
|
Json: .json
|
|
Objective-C: .m .mm
|
|
Proto: .proto .protodevel
|
|
TableGen: .td
|
|
TextProto: .textpb .pb.txt .textproto .asciipb
|
|
Verilog: .sv .svh .v .vh
|
|
--cursor=<uint> - The position of the cursor when invoking
|
|
clang-format from an editor integration
|
|
--dry-run - If set, do not actually make the formatting changes
|
|
--dump-config - Dump configuration options to stdout and exit.
|
|
Can be used with -style option.
|
|
--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. 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).
|
|
Used only with --dry-run or -n
|
|
--files=<string> - Provide a list of files to run clang-format
|
|
-i - Inplace edit <file>s, if specified.
|
|
--length=<uint> - Format a range of this length (in bytes).
|
|
Multiple ranges can be formatted by specifying
|
|
several -offset and -length pairs.
|
|
When only a single -offset is specified without
|
|
-length, clang-format will format up to the end
|
|
of the file.
|
|
Can only be used with one input file.
|
|
--lines=<string> - <start line>:<end line> - format a range of
|
|
lines (both 1-based).
|
|
Multiple ranges can be formatted by specifying
|
|
several -lines arguments.
|
|
Can't be used with -offset and -length.
|
|
Can only be used with one input file.
|
|
-n - Alias for --dry-run
|
|
--offset=<uint> - Format a range starting at this byte offset.
|
|
Multiple ranges can be formatted by specifying
|
|
several -offset and -length pairs.
|
|
Can only be used with one input file.
|
|
--output-replacements-xml - Output replacements as XML.
|
|
--qualifier-alignment=<string> - If set, overrides the qualifier alignment style
|
|
determined by the QualifierAlignment style flag
|
|
--sort-includes - If set, overrides the include sorting behavior
|
|
determined by the SortIncludes style flag
|
|
--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:
|
|
|
|
--help - Display available options (--help-hidden for more)
|
|
--help-list - Display list of available options (--help-list-hidden for more)
|
|
--version - Display the version of this program
|
|
|
|
|
|
.. END_FORMAT_HELP
|
|
|
|
When the desired code formatting style is different from the available options,
|
|
the style can be customized using the ``-style="{key: value, ...}"`` option or
|
|
by putting your style configuration in the ``.clang-format`` or ``_clang-format``
|
|
file in your project's directory and using ``clang-format -style=file``.
|
|
|
|
An easy way to create the ``.clang-format`` file is:
|
|
|
|
.. code-block:: console
|
|
|
|
clang-format -style=llvm -dump-config > .clang-format
|
|
|
|
Available style options are described in :doc:`ClangFormatStyleOptions`.
|
|
|
|
|
|
Vim Integration
|
|
===============
|
|
|
|
There is an integration for :program:`vim` which lets you run the
|
|
:program:`clang-format` standalone tool on your current buffer, optionally
|
|
selecting regions to reformat. The integration has the form of a `python`-file
|
|
which can be found under `clang/tools/clang-format/clang-format.py`.
|
|
|
|
This can be integrated by adding the following to your `.vimrc`:
|
|
|
|
.. code-block:: vim
|
|
|
|
map <C-K> :pyf <path-to-this-file>/clang-format.py<cr>
|
|
imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr>
|
|
|
|
The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the
|
|
second line adds support for INSERT mode. Change "C-K" to another binding if
|
|
you need :program:`clang-format` on a different key (C-K stands for Ctrl+k).
|
|
|
|
With this integration you can press the bound key and clang-format will
|
|
format the current line in NORMAL and INSERT mode or the selected region in
|
|
VISUAL mode. The line or region is extended to the next bigger syntactic
|
|
entity.
|
|
|
|
It operates on the current, potentially unsaved buffer and does not create
|
|
or save any files. To revert a formatting, just undo.
|
|
|
|
An alternative option is to format changes when saving a file and thus to
|
|
have a zero-effort integration into the coding workflow. To do this, add this to
|
|
your `.vimrc`:
|
|
|
|
.. code-block:: vim
|
|
|
|
function! Formatonsave()
|
|
let l:formatdiff = 1
|
|
pyf ~/llvm/tools/clang/tools/clang-format/clang-format.py
|
|
endfunction
|
|
autocmd BufWritePre *.h,*.cc,*.cpp call Formatonsave()
|
|
|
|
|
|
Emacs Integration
|
|
=================
|
|
|
|
Similar to the integration for :program:`vim`, there is an integration for
|
|
:program:`emacs`. It can be found at `clang/tools/clang-format/clang-format.el`
|
|
and used by adding this to your `.emacs`:
|
|
|
|
.. code-block:: common-lisp
|
|
|
|
(load "<path-to-clang>/tools/clang-format/clang-format.el")
|
|
(global-set-key [C-M-tab] 'clang-format-region)
|
|
|
|
This binds the function `clang-format-region` to C-M-tab, which then formats the
|
|
current line or selected region.
|
|
|
|
|
|
BBEdit Integration
|
|
==================
|
|
|
|
:program:`clang-format` cannot be used as a text filter with BBEdit, but works
|
|
well via a script. The AppleScript to do this integration can be found at
|
|
`clang/tools/clang-format/clang-format-bbedit.applescript`; place a copy in
|
|
`~/Library/Application Support/BBEdit/Scripts`, and edit the path within it to
|
|
point to your local copy of :program:`clang-format`.
|
|
|
|
With this integration you can select the script from the Script menu and
|
|
:program:`clang-format` will format the selection. Note that you can rename the
|
|
menu item by renaming the script, and can assign the menu item a keyboard
|
|
shortcut in the BBEdit preferences, under Menus & Shortcuts.
|
|
|
|
|
|
CLion Integration
|
|
=================
|
|
|
|
:program:`clang-format` is integrated into `CLion <https://www.jetbrains
|
|
.com/clion/>`_ as an alternative code formatter. CLion turns it on
|
|
automatically when there is a ``.clang-format`` file under the project root.
|
|
Code style rules are applied as you type, including indentation,
|
|
auto-completion, code generation, and refactorings.
|
|
|
|
:program:`clang-format` can also be enabled without a ``.clang-format`` file.
|
|
In this case, CLion prompts you to create one based on the current IDE settings
|
|
or the default LLVM style.
|
|
|
|
|
|
Visual Studio Integration
|
|
=========================
|
|
|
|
Download the latest Visual Studio extension from the `alpha build site
|
|
<https://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F.
|
|
|
|
|
|
Visual Studio Code Integration
|
|
==============================
|
|
|
|
Get the latest Visual Studio Code extension from the `Visual Studio Marketplace <https://marketplace.visualstudio.com/items?itemName=xaver.clang-format>`_. The default key-binding is Alt-Shift-F.
|
|
|
|
Git integration
|
|
===============
|
|
|
|
The script `clang/tools/clang-format/git-clang-format` can be used to
|
|
format just the lines touched in git commits:
|
|
|
|
.. code-block:: console
|
|
|
|
% git clang-format -h
|
|
usage: git clang-format [OPTIONS] [<commit>] [<commit>|--staged] [--] [<file>...]
|
|
|
|
If zero or one commits are given, run clang-format on all lines that differ
|
|
between the working directory and <commit>, which defaults to HEAD. Changes are
|
|
only applied to the working directory, or in the stage/index.
|
|
|
|
Examples:
|
|
To format staged changes, i.e everything that's been `git add`ed:
|
|
git clang-format
|
|
|
|
To also format everything touched in the most recent commit:
|
|
git clang-format HEAD~1
|
|
|
|
If you're on a branch off main, to format everything touched on your branch:
|
|
git clang-format main
|
|
|
|
If two commits are given (requires --diff), run clang-format on all lines in the
|
|
second <commit> that differ from the first <commit>.
|
|
|
|
The following git-config settings set the default of the corresponding option:
|
|
clangFormat.binary
|
|
clangFormat.commit
|
|
clangFormat.extensions
|
|
clangFormat.style
|
|
|
|
positional arguments:
|
|
<commit> revision from which to compute the diff
|
|
<file>... if specified, only consider differences in these files
|
|
|
|
optional arguments:
|
|
-h, --help show this help message and exit
|
|
--binary BINARY path to clang-format
|
|
--commit COMMIT default commit to use if none is specified
|
|
--diff print a diff instead of applying the changes
|
|
--diffstat print a diffstat instead of applying the changes
|
|
--extensions EXTENSIONS
|
|
comma-separated list of file extensions to format, excluding the period and case-insensitive
|
|
-f, --force allow changes to unstaged files
|
|
-p, --patch select hunks interactively
|
|
-q, --quiet print less information
|
|
--staged, --cached format lines in the stage instead of the working dir
|
|
--style STYLE passed to clang-format
|
|
-v, --verbose print extra information
|
|
|
|
|
|
Script for patch reformatting
|
|
=============================
|
|
|
|
The python script `clang/tools/clang-format/clang-format-diff.py` parses the
|
|
output of a unified diff and reformats all contained lines with
|
|
:program:`clang-format`.
|
|
|
|
.. code-block:: console
|
|
|
|
usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-iregex PATTERN] [-sort-includes] [-v] [-style STYLE]
|
|
[-fallback-style FALLBACK_STYLE] [-binary BINARY]
|
|
|
|
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:
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
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 a fallback 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
|
|
|
|
The option `-U0` will create a diff without context lines (the script would format
|
|
those as well).
|
|
|
|
These commands use the file paths shown in the diff output
|
|
so they will only work from the root of the repository.
|
|
|
|
Current State of Clang Format for LLVM
|
|
======================================
|
|
|
|
The following table :doc:`ClangFormattedStatus` shows the current status of clang-formatting for the entire LLVM source tree.
|