Documentation/dev-tools/clang-format.rst

3 clang-format
6 ``clang-format`` is a tool to format C/C++/... code according to
10 ``clang-format`` can be used for several purposes:
12   - Quickly reformat a block of code to the kernel style. Specially useful
15   - Spot style mistakes, typos and possible improvements in files
18   - Help you follow the coding style rules, specially useful for those
22 Its configuration file is ``.clang-format`` in the root of the kernel tree.
24 coding style. They also try to follow :ref:`Documentation/process/coding-style.rst <codingstyle>`
28 another ``.clang-format`` file in a subfolder.
31 Linux distributions for a long time. Search for ``clang-format`` in
32 your repositories. Otherwise, you can either download pre-built
47 -----------------------------------------
49 By running the tool in its inline mode, you can review full subsystems,
55     clang-format -i kernel/*.[ch]
61 ``clang-format`` features/versions.
63 ``clang-format`` also supports reading unified diffs, so you can review
66     https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting
68 To avoid ``clang-format`` formatting some portion of a file, you can do::
71     // clang-format off
73     // clang-format on
77 ``clang-format``, specially if you are writing new files or if you are
79 ``clang-format`` versions or not have it available at all. Therefore,
81 at least until we see if ``clang-format`` becomes commonplace.
87 ---------------------------
92 for multi-line macros (and aligning their backslashes), etc.
99 like vim, emacs, BBEdit and Visual Studio you can find support built-in.
105 editors and IDEs you should be able to find ready-to-use plugins.
107 For this use case, consider using a secondary ``.clang-format``
114 ---------------
116 ``clang-format`` is missing support for some things that are common
122   - Aligned blocks of one-line ``#defines``, e.g.::
134   - Aligned designated initializers, e.g.::
160 ----------------------
165 which makes reviewing full-file style, as well diffs and patches as easy
168 In other cases (e.g. particular subsystems/folders/files), the kernel style
174   - Aligning assignments (``AlignConsecutiveAssignments``).
176   - Aligning declarations (``AlignConsecutiveDeclarations``).
178   - Reflowing text in comments (``ReflowComments``).
180   - Sorting ``#includes`` (``SortIncludes``).
182 They are typically useful for block re-formatting, rather than full-file.
183 You might want to create another ``.clang-format`` file and use that one