1=========== 2ClangFormat 3=========== 4 5`ClangFormat` describes a set of tools that are built on top of 6:doc:`LibFormat`. It can support your workflow in a variety of ways including a 7standalone tool and editor integrations. 8 9 10Standalone Tool 11=============== 12 13:program:`clang-format` is located in `clang/tools/clang-format` and can be used 14to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code. 15 16.. START_FORMAT_HELP 17 18.. code-block:: console 19 20 $ clang-format --help 21 OVERVIEW: A tool to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code. 22 23 If no arguments are specified, it formats the code from standard input 24 and writes the result to the standard output. 25 If <file>s are given, it reformats the files. If -i is specified 26 together with <file>s, the files are edited in-place. Otherwise, the 27 result is written to the standard output. 28 29 USAGE: clang-format [options] [@<file>] [<file> ...] 30 31 OPTIONS: 32 33 Clang-format options: 34 35 --Werror - If set, changes formatting warnings to errors 36 --Wno-error=<value> - If set don't error out on the specified warning type. 37 =unknown - If set, unknown format options are only warned about. 38 This can be used to enable formatting, even if the 39 configuration contains unknown (newer) options. 40 Use with caution, as this might lead to dramatically 41 differing format depending on an option being 42 supported or not. 43 --assume-filename=<string> - Set filename used to determine the language and to find 44 .clang-format file. 45 Only used when reading from stdin. 46 If this is not passed, the .clang-format file is searched 47 relative to the current working directory when reading stdin. 48 Unrecognized filenames are treated as C++. 49 supported: 50 CSharp: .cs 51 Java: .java 52 JavaScript: .mjs .js .ts 53 Json: .json 54 Objective-C: .m .mm 55 Proto: .proto .protodevel 56 TableGen: .td 57 TextProto: .textpb .pb.txt .textproto .asciipb 58 Verilog: .sv .svh .v .vh 59 --cursor=<uint> - The position of the cursor when invoking 60 clang-format from an editor integration 61 --dry-run - If set, do not actually make the formatting changes 62 --dump-config - Dump configuration options to stdout and exit. 63 Can be used with -style option. 64 --fallback-style=<string> - The name of the predefined style used as a 65 fallback in case clang-format is invoked with 66 -style=file, but can not find the .clang-format 67 file to use. Defaults to 'LLVM'. 68 Use -fallback-style=none to skip formatting. 69 --ferror-limit=<uint> - Set the maximum number of clang-format errors to emit 70 before stopping (0 = no limit). 71 Used only with --dry-run or -n 72 --files=<filename> - A file containing a list of files to process, one 73 per line. 74 -i - Inplace edit <file>s, if specified. 75 --length=<uint> - Format a range of this length (in bytes). 76 Multiple ranges can be formatted by specifying 77 several -offset and -length pairs. 78 When only a single -offset is specified without 79 -length, clang-format will format up to the end 80 of the file. 81 Can only be used with one input file. 82 --lines=<string> - <start line>:<end line> - format a range of 83 lines (both 1-based). 84 Multiple ranges can be formatted by specifying 85 several -lines arguments. 86 Can't be used with -offset and -length. 87 Can only be used with one input file. 88 -n - Alias for --dry-run 89 --offset=<uint> - Format a range starting at this byte offset. 90 Multiple ranges can be formatted by specifying 91 several -offset and -length pairs. 92 Can only be used with one input file. 93 --output-replacements-xml - Output replacements as XML. 94 --qualifier-alignment=<string> - If set, overrides the qualifier alignment style 95 determined by the QualifierAlignment style flag 96 --sort-includes - If set, overrides the include sorting behavior 97 determined by the SortIncludes style flag 98 --style=<string> - Set coding style. <string> can be: 99 1. A preset: LLVM, GNU, Google, Chromium, Microsoft, 100 Mozilla, WebKit. 101 2. 'file' to load style configuration from a 102 .clang-format file in one of the parent directories 103 of the source file (for stdin, see --assume-filename). 104 If no .clang-format file is found, falls back to 105 --fallback-style. 106 --style=file is the default. 107 3. 'file:<format_file_path>' to explicitly specify 108 the configuration file. 109 4. "{key: value, ...}" to set specific parameters, e.g.: 110 --style="{BasedOnStyle: llvm, IndentWidth: 8}" 111 --verbose - If set, shows the list of processed files 112 113 Generic Options: 114 115 --help - Display available options (--help-hidden for more) 116 --help-list - Display list of available options (--help-list-hidden for more) 117 --version - Display the version of this program 118 119 120.. END_FORMAT_HELP 121 122When the desired code formatting style is different from the available options, 123the style can be customized using the ``-style="{key: value, ...}"`` option or 124by putting your style configuration in the ``.clang-format`` or ``_clang-format`` 125file in your project's directory and using ``clang-format -style=file``. 126 127An easy way to create the ``.clang-format`` file is: 128 129.. code-block:: console 130 131 clang-format -style=llvm -dump-config > .clang-format 132 133Available style options are described in :doc:`ClangFormatStyleOptions`. 134 135 136Vim Integration 137=============== 138 139There is an integration for :program:`vim` which lets you run the 140:program:`clang-format` standalone tool on your current buffer, optionally 141selecting regions to reformat. The integration has the form of a `python`-file 142which can be found under `clang/tools/clang-format/clang-format.py`. 143 144This can be integrated by adding the following to your `.vimrc`: 145 146.. code-block:: vim 147 148 map <C-K> :pyf <path-to-this-file>/clang-format.py<cr> 149 imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr> 150 151The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the 152second line adds support for INSERT mode. Change "C-K" to another binding if 153you need :program:`clang-format` on a different key (C-K stands for Ctrl+k). 154 155With this integration you can press the bound key and clang-format will 156format the current line in NORMAL and INSERT mode or the selected region in 157VISUAL mode. The line or region is extended to the next bigger syntactic 158entity. 159 160It operates on the current, potentially unsaved buffer and does not create 161or save any files. To revert a formatting, just undo. 162 163An alternative option is to format changes when saving a file and thus to 164have a zero-effort integration into the coding workflow. To do this, add this to 165your `.vimrc`: 166 167.. code-block:: vim 168 169 function! Formatonsave() 170 let l:formatdiff = 1 171 pyf <path-to-this-file>/clang-format.py 172 endfunction 173 autocmd BufWritePre *.h,*.cc,*.cpp call Formatonsave() 174 175 176Emacs Integration 177================= 178 179Similar to the integration for :program:`vim`, there is an integration for 180:program:`emacs`. It can be found at `clang/tools/clang-format/clang-format.el` 181and used by adding this to your `.emacs`: 182 183.. code-block:: common-lisp 184 185 (load "<path-to-clang>/tools/clang-format/clang-format.el") 186 (global-set-key [C-M-tab] 'clang-format-region) 187 188This binds the function `clang-format-region` to C-M-tab, which then formats the 189current line or selected region. 190 191 192BBEdit Integration 193================== 194 195:program:`clang-format` cannot be used as a text filter with BBEdit, but works 196well via a script. The AppleScript to do this integration can be found at 197`clang/tools/clang-format/clang-format-bbedit.applescript`; place a copy in 198`~/Library/Application Support/BBEdit/Scripts`, and edit the path within it to 199point to your local copy of :program:`clang-format`. 200 201With this integration you can select the script from the Script menu and 202:program:`clang-format` will format the selection. Note that you can rename the 203menu item by renaming the script, and can assign the menu item a keyboard 204shortcut in the BBEdit preferences, under Menus & Shortcuts. 205 206 207CLion Integration 208================= 209 210:program:`clang-format` is integrated into `CLion <https://www.jetbrains 211.com/clion/>`_ as an alternative code formatter. CLion turns it on 212automatically when there is a ``.clang-format`` file under the project root. 213Code style rules are applied as you type, including indentation, 214auto-completion, code generation, and refactorings. 215 216:program:`clang-format` can also be enabled without a ``.clang-format`` file. 217In this case, CLion prompts you to create one based on the current IDE settings 218or the default LLVM style. 219 220 221Visual Studio Integration 222========================= 223 224Download the latest Visual Studio extension from the `alpha build site 225<https://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F. 226 227 228Visual Studio Code Integration 229============================== 230 231Get 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. 232 233Git integration 234=============== 235 236The script `clang/tools/clang-format/git-clang-format` can be used to 237format just the lines touched in git commits: 238 239.. code-block:: console 240 241 % git clang-format -h 242 usage: git clang-format [OPTIONS] [<commit>] [<commit>|--staged] [--] [<file>...] 243 244 If zero or one commits are given, run clang-format on all lines that differ 245 between the working directory and <commit>, which defaults to HEAD. Changes are 246 only applied to the working directory, or in the stage/index. 247 248 Examples: 249 To format staged changes, i.e everything that's been `git add`ed: 250 git clang-format 251 252 To also format everything touched in the most recent commit: 253 git clang-format HEAD~1 254 255 If you're on a branch off main, to format everything touched on your branch: 256 git clang-format main 257 258 If two commits are given (requires --diff), run clang-format on all lines in the 259 second <commit> that differ from the first <commit>. 260 261 The following git-config settings set the default of the corresponding option: 262 clangFormat.binary 263 clangFormat.commit 264 clangFormat.extensions 265 clangFormat.style 266 267 positional arguments: 268 <commit> revision from which to compute the diff 269 <file>... if specified, only consider differences in these files 270 271 optional arguments: 272 -h, --help show this help message and exit 273 --binary BINARY path to clang-format 274 --commit COMMIT default commit to use if none is specified 275 --diff print a diff instead of applying the changes 276 --diffstat print a diffstat instead of applying the changes 277 --extensions EXTENSIONS 278 comma-separated list of file extensions to format, excluding the period and case-insensitive 279 -f, --force allow changes to unstaged files 280 -p, --patch select hunks interactively 281 -q, --quiet print less information 282 --staged, --cached format lines in the stage instead of the working dir 283 --style STYLE passed to clang-format 284 -v, --verbose print extra information 285 286 287Script for patch reformatting 288============================= 289 290The python script `clang/tools/clang-format/clang-format-diff.py` parses the 291output of a unified diff and reformats all contained lines with 292:program:`clang-format`. 293 294.. code-block:: console 295 296 usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-iregex PATTERN] [-sort-includes] [-v] [-style STYLE] 297 [-fallback-style FALLBACK_STYLE] [-binary BINARY] 298 299 This script reads input from a unified diff and reformats all the changed 300 lines. This is useful to reformat all the lines touched by a specific patch. 301 Example usage for git/svn users: 302 303 git diff -U0 --no-color --relative HEAD^ | clang-format-diff.py -p1 -i 304 svn diff --diff-cmd=diff -x-U0 | clang-format-diff.py -i 305 306 It should be noted that the filename contained in the diff is used unmodified 307 to determine the source file to update. Users calling this script directly 308 should be careful to ensure that the path in the diff is correct relative to the 309 current working directory. 310 311 optional arguments: 312 -h, --help show this help message and exit 313 -i apply edits to files instead of displaying a diff 314 -p NUM strip the smallest prefix containing P slashes 315 -regex PATTERN custom pattern selecting file paths to reformat (case sensitive, overrides -iregex) 316 -iregex PATTERN custom pattern selecting file paths to reformat (case insensitive, overridden by -regex) 317 -sort-includes let clang-format sort include blocks 318 -v, --verbose be more verbose, ineffective without -i 319 -style STYLE formatting style to apply (LLVM, GNU, Google, Chromium, Microsoft, Mozilla, WebKit) 320 -fallback-style FALLBACK_STYLE 321 The name of the predefined style used as a fallback in case clang-format is invoked with-style=file, but can not 322 find the .clang-formatfile to use. 323 -binary BINARY location of binary to use for clang-format 324 325To reformat all the lines in the latest Mercurial/:program:`hg` commit, do: 326 327.. code-block:: console 328 329 hg diff -U0 --color=never | clang-format-diff.py -i -p1 330 331The option `-U0` will create a diff without context lines (the script would format 332those as well). 333 334These commands use the file paths shown in the diff output 335so they will only work from the root of the repository. 336 337Current State of Clang Format for LLVM 338====================================== 339 340The following table :doc:`ClangFormattedStatus` shows the current status of clang-formatting for the entire LLVM source tree. 341