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/Objective-C/Protobuf/C# code. 15 16.. code-block:: console 17 18 $ clang-format -help 19 OVERVIEW: A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf/C# code. 20 21 If no arguments are specified, it formats the code from standard input 22 and writes the result to the standard output. 23 If <file>s are given, it reformats the files. If -i is specified 24 together with <file>s, the files are edited in-place. Otherwise, the 25 result is written to the standard output. 26 27 USAGE: clang-format [options] [<file> ...] 28 29 OPTIONS: 30 31 Clang-format options: 32 33 --Werror - If set, changes formatting warnings to errors 34 --Wno-error=unknown - If set, unknown format options are only warned about. 35 This can be used to enable formatting, even if the 36 configuration contains unknown (newer) options. 37 Use with caution, as this might lead to dramatically 38 differing format depending on an option being 39 supported or not. 40 --assume-filename=<string> - Override filename used to determine the language. 41 When reading from stdin, clang-format assumes this 42 filename to determine the language. 43 --cursor=<uint> - The position of the cursor when invoking 44 clang-format from an editor integration 45 --dry-run - If set, do not actually make the formatting changes 46 --dump-config - Dump configuration options to stdout and exit. 47 Can be used with -style option. 48 --fallback-style=<string> - The name of the predefined style used as a 49 fallback in case clang-format is invoked with 50 -style=file, but can not find the .clang-format 51 file to use. 52 Use -fallback-style=none to skip formatting. 53 --ferror-limit=<uint> - Set the maximum number of clang-format errors to 54 emit before stopping (0 = no limit). Used only 55 with --dry-run or -n 56 -i - Inplace edit <file>s, if specified. 57 --length=<uint> - Format a range of this length (in bytes). 58 Multiple ranges can be formatted by specifying 59 several -offset and -length pairs. 60 When only a single -offset is specified without 61 -length, clang-format will format up to the end 62 of the file. 63 Can only be used with one input file. 64 --lines=<string> - <start line>:<end line> - format a range of 65 lines (both 1-based). 66 Multiple ranges can be formatted by specifying 67 several -lines arguments. 68 Can't be used with -offset and -length. 69 Can only be used with one input file. 70 -n - Alias for --dry-run 71 --offset=<uint> - Format a range starting at this byte offset. 72 Multiple ranges can be formatted by specifying 73 several -offset and -length pairs. 74 Can only be used with one input file. 75 --output-replacements-xml - Output replacements as XML. 76 --sort-includes - If set, overrides the include sorting behavior 77 determined by the SortIncludes style flag 78 --style=<string> - Coding style, currently supports: 79 LLVM, Google, Chromium, Mozilla, WebKit. 80 Use -style=file to load style configuration from 81 .clang-format file located in one of the parent 82 directories of the source file (or current 83 directory for stdin). 84 Use -style="{key: value, ...}" to set specific 85 parameters, e.g.: 86 -style="{BasedOnStyle: llvm, IndentWidth: 8}" 87 --verbose - If set, shows the list of processed files 88 89 Generic Options: 90 91 --help - Display available options (--help-hidden for more) 92 --help-list - Display list of available options (--help-list-hidden for more) 93 --version - Display the version of this program 94 95 96When the desired code formatting style is different from the available options, 97the style can be customized using the ``-style="{key: value, ...}"`` option or 98by putting your style configuration in the ``.clang-format`` or ``_clang-format`` 99file in your project's directory and using ``clang-format -style=file``. 100 101An easy way to create the ``.clang-format`` file is: 102 103.. code-block:: console 104 105 clang-format -style=llvm -dump-config > .clang-format 106 107Available style options are described in :doc:`ClangFormatStyleOptions`. 108 109 110Vim Integration 111=============== 112 113There is an integration for :program:`vim` which lets you run the 114:program:`clang-format` standalone tool on your current buffer, optionally 115selecting regions to reformat. The integration has the form of a `python`-file 116which can be found under `clang/tools/clang-format/clang-format.py`. 117 118This can be integrated by adding the following to your `.vimrc`: 119 120.. code-block:: vim 121 122 map <C-K> :pyf <path-to-this-file>/clang-format.py<cr> 123 imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr> 124 125The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the 126second line adds support for INSERT mode. Change "C-K" to another binding if 127you need :program:`clang-format` on a different key (C-K stands for Ctrl+k). 128 129With this integration you can press the bound key and clang-format will 130format the current line in NORMAL and INSERT mode or the selected region in 131VISUAL mode. The line or region is extended to the next bigger syntactic 132entity. 133 134It operates on the current, potentially unsaved buffer and does not create 135or save any files. To revert a formatting, just undo. 136 137An alternative option is to format changes when saving a file and thus to 138have a zero-effort integration into the coding workflow. To do this, add this to 139your `.vimrc`: 140 141.. code-block:: vim 142 143 function! Formatonsave() 144 let l:formatdiff = 1 145 pyf ~/llvm/tools/clang/tools/clang-format/clang-format.py 146 endfunction 147 autocmd BufWritePre *.h,*.cc,*.cpp call Formatonsave() 148 149 150Emacs Integration 151================= 152 153Similar to the integration for :program:`vim`, there is an integration for 154:program:`emacs`. It can be found at `clang/tools/clang-format/clang-format.el` 155and used by adding this to your `.emacs`: 156 157.. code-block:: common-lisp 158 159 (load "<path-to-clang>/tools/clang-format/clang-format.el") 160 (global-set-key [C-M-tab] 'clang-format-region) 161 162This binds the function `clang-format-region` to C-M-tab, which then formats the 163current line or selected region. 164 165 166BBEdit Integration 167================== 168 169:program:`clang-format` cannot be used as a text filter with BBEdit, but works 170well via a script. The AppleScript to do this integration can be found at 171`clang/tools/clang-format/clang-format-bbedit.applescript`; place a copy in 172`~/Library/Application Support/BBEdit/Scripts`, and edit the path within it to 173point to your local copy of :program:`clang-format`. 174 175With this integration you can select the script from the Script menu and 176:program:`clang-format` will format the selection. Note that you can rename the 177menu item by renaming the script, and can assign the menu item a keyboard 178shortcut in the BBEdit preferences, under Menus & Shortcuts. 179 180 181CLion Integration 182================= 183 184:program:`clang-format` is integrated into `CLion <https://www.jetbrains 185.com/clion/>`_ as an alternative code formatter. CLion turns it on 186automatically when there is a ``.clang-format`` file under the project root. 187Code style rules are applied as you type, including indentation, 188auto-completion, code generation, and refactorings. 189 190:program:`clang-format` can also be enabled without a ``.clang-format`` file. 191In this case, CLion prompts you to create one based on the current IDE settings 192or the default LLVM style. 193 194 195Visual Studio Integration 196========================= 197 198Download the latest Visual Studio extension from the `alpha build site 199<https://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F. 200 201 202Visual Studio Code Integration 203============================== 204 205Get 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. 206 207 208Script for patch reformatting 209============================= 210 211The python script `clang/tools/clang-format/clang-format-diff.py` parses the 212output of a unified diff and reformats all contained lines with 213:program:`clang-format`. 214 215.. code-block:: console 216 217 usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE] 218 219 Reformat changed lines in diff. Without -i option just output the diff that 220 would be introduced. 221 222 optional arguments: 223 -h, --help show this help message and exit 224 -i apply edits to files instead of displaying a diff 225 -p NUM strip the smallest prefix containing P slashes 226 -regex PATTERN custom pattern selecting file paths to reformat 227 -style STYLE formatting style to apply (LLVM, Google, Chromium, Mozilla, 228 WebKit) 229 230So to reformat all the lines in the latest :program:`git` commit, just do: 231 232.. code-block:: console 233 234 git diff -U0 --no-color HEAD^ | clang-format-diff.py -i -p1 235 236With Mercurial/:program:`hg`: 237 238.. code-block:: console 239 240 hg diff -U0 --color=never | clang-format-diff.py -i -p1 241 242In an SVN client, you can do: 243 244.. code-block:: console 245 246 svn diff --diff-cmd=diff -x -U0 | clang-format-diff.py -i 247 248The option `-U0` will create a diff without context lines (the script would format 249those as well). 250 251These commands use the file paths shown in the diff output 252so they will only work from the root of the repository. 253 254Current State of Clang Format for LLVM 255====================================== 256 257The following table :doc:`ClangFormattedStatus` shows the current status of clang-formatting for the entire LLVM source tree. 258