xref: /aosp_15_r20/external/clang/docs/ClangFormat.rst (revision 67e74705e28f6214e480b399dd47ea732279e315)
1*67e74705SXin Li===========
2*67e74705SXin LiClangFormat
3*67e74705SXin Li===========
4*67e74705SXin Li
5*67e74705SXin Li`ClangFormat` describes a set of tools that are built on top of
6*67e74705SXin Li:doc:`LibFormat`. It can support your workflow in a variety of ways including a
7*67e74705SXin Listandalone tool and editor integrations.
8*67e74705SXin Li
9*67e74705SXin Li
10*67e74705SXin LiStandalone Tool
11*67e74705SXin Li===============
12*67e74705SXin Li
13*67e74705SXin Li:program:`clang-format` is located in `clang/tools/clang-format` and can be used
14*67e74705SXin Lito format C/C++/Obj-C code.
15*67e74705SXin Li
16*67e74705SXin Li.. code-block:: console
17*67e74705SXin Li
18*67e74705SXin Li  $ clang-format -help
19*67e74705SXin Li  OVERVIEW: A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf code.
20*67e74705SXin Li
21*67e74705SXin Li  If no arguments are specified, it formats the code from standard input
22*67e74705SXin Li  and writes the result to the standard output.
23*67e74705SXin Li  If <file>s are given, it reformats the files. If -i is specified
24*67e74705SXin Li  together with <file>s, the files are edited in-place. Otherwise, the
25*67e74705SXin Li  result is written to the standard output.
26*67e74705SXin Li
27*67e74705SXin Li  USAGE: clang-format [options] [<file> ...]
28*67e74705SXin Li
29*67e74705SXin Li  OPTIONS:
30*67e74705SXin Li
31*67e74705SXin Li  Clang-format options:
32*67e74705SXin Li
33*67e74705SXin Li    -assume-filename=<string> - When reading from stdin, clang-format assumes this
34*67e74705SXin Li                                filename to look for a style config file (with
35*67e74705SXin Li                                -style=file) and to determine the language.
36*67e74705SXin Li    -cursor=<uint>            - The position of the cursor when invoking
37*67e74705SXin Li                                clang-format from an editor integration
38*67e74705SXin Li    -dump-config              - Dump configuration options to stdout and exit.
39*67e74705SXin Li                                Can be used with -style option.
40*67e74705SXin Li    -fallback-style=<string>  - The name of the predefined style used as a
41*67e74705SXin Li                                fallback in case clang-format is invoked with
42*67e74705SXin Li                                -style=file, but can not find the .clang-format
43*67e74705SXin Li                                file to use.
44*67e74705SXin Li                                Use -fallback-style=none to skip formatting.
45*67e74705SXin Li    -i                        - Inplace edit <file>s, if specified.
46*67e74705SXin Li    -length=<uint>            - Format a range of this length (in bytes).
47*67e74705SXin Li                                Multiple ranges can be formatted by specifying
48*67e74705SXin Li                                several -offset and -length pairs.
49*67e74705SXin Li                                When only a single -offset is specified without
50*67e74705SXin Li                                -length, clang-format will format up to the end
51*67e74705SXin Li                                of the file.
52*67e74705SXin Li                                Can only be used with one input file.
53*67e74705SXin Li    -lines=<string>           - <start line>:<end line> - format a range of
54*67e74705SXin Li                                lines (both 1-based).
55*67e74705SXin Li                                Multiple ranges can be formatted by specifying
56*67e74705SXin Li                                several -lines arguments.
57*67e74705SXin Li                                Can't be used with -offset and -length.
58*67e74705SXin Li                                Can only be used with one input file.
59*67e74705SXin Li    -offset=<uint>            - Format a range starting at this byte offset.
60*67e74705SXin Li                                Multiple ranges can be formatted by specifying
61*67e74705SXin Li                                several -offset and -length pairs.
62*67e74705SXin Li                                Can only be used with one input file.
63*67e74705SXin Li    -output-replacements-xml  - Output replacements as XML.
64*67e74705SXin Li    -sort-includes            - Sort touched include lines
65*67e74705SXin Li    -style=<string>           - Coding style, currently supports:
66*67e74705SXin Li                                  LLVM, Google, Chromium, Mozilla, WebKit.
67*67e74705SXin Li                                Use -style=file to load style configuration from
68*67e74705SXin Li                                .clang-format file located in one of the parent
69*67e74705SXin Li                                directories of the source file (or current
70*67e74705SXin Li                                directory for stdin).
71*67e74705SXin Li                                Use -style="{key: value, ...}" to set specific
72*67e74705SXin Li                                parameters, e.g.:
73*67e74705SXin Li                                  -style="{BasedOnStyle: llvm, IndentWidth: 8}"
74*67e74705SXin Li
75*67e74705SXin Li  Generic Options:
76*67e74705SXin Li
77*67e74705SXin Li    -help                     - Display available options (-help-hidden for more)
78*67e74705SXin Li    -help-list                - Display list of available options (-help-list-hidden for more)
79*67e74705SXin Li    -version                  - Display the version of this program
80*67e74705SXin Li
81*67e74705SXin Li
82*67e74705SXin LiWhen the desired code formatting style is different from the available options,
83*67e74705SXin Lithe style can be customized using the ``-style="{key: value, ...}"`` option or
84*67e74705SXin Liby putting your style configuration in the ``.clang-format`` or ``_clang-format``
85*67e74705SXin Lifile in your project's directory and using ``clang-format -style=file``.
86*67e74705SXin Li
87*67e74705SXin LiAn easy way to create the ``.clang-format`` file is:
88*67e74705SXin Li
89*67e74705SXin Li.. code-block:: console
90*67e74705SXin Li
91*67e74705SXin Li  clang-format -style=llvm -dump-config > .clang-format
92*67e74705SXin Li
93*67e74705SXin LiAvailable style options are described in :doc:`ClangFormatStyleOptions`.
94*67e74705SXin Li
95*67e74705SXin Li
96*67e74705SXin LiVim Integration
97*67e74705SXin Li===============
98*67e74705SXin Li
99*67e74705SXin LiThere is an integration for :program:`vim` which lets you run the
100*67e74705SXin Li:program:`clang-format` standalone tool on your current buffer, optionally
101*67e74705SXin Liselecting regions to reformat. The integration has the form of a `python`-file
102*67e74705SXin Liwhich can be found under `clang/tools/clang-format/clang-format.py`.
103*67e74705SXin Li
104*67e74705SXin LiThis can be integrated by adding the following to your `.vimrc`:
105*67e74705SXin Li
106*67e74705SXin Li.. code-block:: vim
107*67e74705SXin Li
108*67e74705SXin Li  map <C-K> :pyf <path-to-this-file>/clang-format.py<cr>
109*67e74705SXin Li  imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr>
110*67e74705SXin Li
111*67e74705SXin LiThe first line enables :program:`clang-format` for NORMAL and VISUAL mode, the
112*67e74705SXin Lisecond line adds support for INSERT mode. Change "C-K" to another binding if
113*67e74705SXin Liyou need :program:`clang-format` on a different key (C-K stands for Ctrl+k).
114*67e74705SXin Li
115*67e74705SXin LiWith this integration you can press the bound key and clang-format will
116*67e74705SXin Liformat the current line in NORMAL and INSERT mode or the selected region in
117*67e74705SXin LiVISUAL mode. The line or region is extended to the next bigger syntactic
118*67e74705SXin Lientity.
119*67e74705SXin Li
120*67e74705SXin LiIt operates on the current, potentially unsaved buffer and does not create
121*67e74705SXin Lior save any files. To revert a formatting, just undo.
122*67e74705SXin Li
123*67e74705SXin Li
124*67e74705SXin LiEmacs Integration
125*67e74705SXin Li=================
126*67e74705SXin Li
127*67e74705SXin LiSimilar to the integration for :program:`vim`, there is an integration for
128*67e74705SXin Li:program:`emacs`. It can be found at `clang/tools/clang-format/clang-format.el`
129*67e74705SXin Liand used by adding this to your `.emacs`:
130*67e74705SXin Li
131*67e74705SXin Li.. code-block:: common-lisp
132*67e74705SXin Li
133*67e74705SXin Li  (load "<path-to-clang>/tools/clang-format/clang-format.el")
134*67e74705SXin Li  (global-set-key [C-M-tab] 'clang-format-region)
135*67e74705SXin Li
136*67e74705SXin LiThis binds the function `clang-format-region` to C-M-tab, which then formats the
137*67e74705SXin Licurrent line or selected region.
138*67e74705SXin Li
139*67e74705SXin Li
140*67e74705SXin LiBBEdit Integration
141*67e74705SXin Li==================
142*67e74705SXin Li
143*67e74705SXin Li:program:`clang-format` cannot be used as a text filter with BBEdit, but works
144*67e74705SXin Liwell via a script. The AppleScript to do this integration can be found at
145*67e74705SXin Li`clang/tools/clang-format/clang-format-bbedit.applescript`; place a copy in
146*67e74705SXin Li`~/Library/Application Support/BBEdit/Scripts`, and edit the path within it to
147*67e74705SXin Lipoint to your local copy of :program:`clang-format`.
148*67e74705SXin Li
149*67e74705SXin LiWith this integration you can select the script from the Script menu and
150*67e74705SXin Li:program:`clang-format` will format the selection. Note that you can rename the
151*67e74705SXin Limenu item by renaming the script, and can assign the menu item a keyboard
152*67e74705SXin Lishortcut in the BBEdit preferences, under Menus & Shortcuts.
153*67e74705SXin Li
154*67e74705SXin Li
155*67e74705SXin LiVisual Studio Integration
156*67e74705SXin Li=========================
157*67e74705SXin Li
158*67e74705SXin LiDownload the latest Visual Studio extension from the `alpha build site
159*67e74705SXin Li<http://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F.
160*67e74705SXin Li
161*67e74705SXin Li
162*67e74705SXin LiScript for patch reformatting
163*67e74705SXin Li=============================
164*67e74705SXin Li
165*67e74705SXin LiThe python script `clang/tools/clang-format-diff.py` parses the output of
166*67e74705SXin Lia unified diff and reformats all contained lines with :program:`clang-format`.
167*67e74705SXin Li
168*67e74705SXin Li.. code-block:: console
169*67e74705SXin Li
170*67e74705SXin Li  usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE]
171*67e74705SXin Li
172*67e74705SXin Li  Reformat changed lines in diff. Without -i option just output the diff that
173*67e74705SXin Li  would be introduced.
174*67e74705SXin Li
175*67e74705SXin Li  optional arguments:
176*67e74705SXin Li    -h, --help      show this help message and exit
177*67e74705SXin Li    -i              apply edits to files instead of displaying a diff
178*67e74705SXin Li    -p NUM          strip the smallest prefix containing P slashes
179*67e74705SXin Li    -regex PATTERN  custom pattern selecting file paths to reformat
180*67e74705SXin Li    -style STYLE    formatting style to apply (LLVM, Google, Chromium, Mozilla,
181*67e74705SXin Li                    WebKit)
182*67e74705SXin Li
183*67e74705SXin LiSo to reformat all the lines in the latest :program:`git` commit, just do:
184*67e74705SXin Li
185*67e74705SXin Li.. code-block:: console
186*67e74705SXin Li
187*67e74705SXin Li  git diff -U0 HEAD^ | clang-format-diff.py -i -p1
188*67e74705SXin Li
189*67e74705SXin LiIn an SVN client, you can do:
190*67e74705SXin Li
191*67e74705SXin Li.. code-block:: console
192*67e74705SXin Li
193*67e74705SXin Li  svn diff --diff-cmd=diff -x -U0 | clang-format-diff.py -i
194*67e74705SXin Li
195*67e74705SXin LiThe option `-U0` will create a diff without context lines (the script would format
196*67e74705SXin Lithose as well).
197