367 lines · plain
1===========2ClangFormat3===========4 5`ClangFormat` describes a set of tools that are built on top of6:doc:`LibFormat`. It can support your workflow in a variety of ways including a7standalone tool and editor integrations.8 9 10Standalone Tool11===============12 13:program:`clang-format` is located in `clang/tools/clang-format` and can be used14to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.15 16.. START_FORMAT_HELP17 18.. code-block:: console19 20 $ clang-format --help21 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 input24 and writes the result to the standard output.25 If <file>s are given, it reformats the files. If -i is specified26 together with <file>s, the files are edited in-place. Otherwise, the27 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 errors36 --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 the39 configuration contains unknown (newer) options.40 Use with caution, as this might lead to dramatically41 differing format depending on an option being42 supported or not.43 --assume-filename=<string> - Set filename used to determine the language and to find44 .clang-format file.45 Only used when reading from stdin.46 If this is not passed, the .clang-format file is searched47 relative to the current working directory when reading stdin.48 Unrecognized filenames are treated as C++.49 supported:50 CSharp: .cs51 Java: .java52 JavaScript: .js .mjs .cjs .ts53 JSON: .json .ipynb54 Objective-C: .m .mm55 Proto: .proto .protodevel56 TableGen: .td57 TextProto: .txtpb .textpb .pb.txt .textproto .asciipb58 Verilog: .sv .svh .v .vh59 --cursor=<uint> - The position of the cursor when invoking60 clang-format from an editor integration61 --dry-run - If set, do not actually make the formatting changes62 --dump-config - Dump configuration options to stdout and exit.63 Can be used with -style option.64 --fail-on-incomplete-format - If set, fail with exit code 1 on incomplete format.65 --fallback-style=<string> - The name of the predefined style used as a66 fallback in case clang-format is invoked with67 -style=file, but can not find the .clang-format68 file to use. Defaults to 'LLVM'.69 Use -fallback-style=none to skip formatting.70 --ferror-limit=<uint> - Set the maximum number of clang-format errors to emit71 before stopping (0 = no limit).72 Used only with --dry-run or -n73 --files=<filename> - A file containing a list of files to process, one 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 specifying77 several -offset and -length pairs.78 When only a single -offset is specified without79 -length, clang-format will format up to the end80 of the file.81 Can only be used with one input file.82 --lines=<string> - <start line>:<end line> - format a range of83 lines (both 1-based).84 Multiple ranges can be formatted by specifying85 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-run89 --offset=<uint> - Format a range starting at this byte offset.90 Multiple ranges can be formatted by specifying91 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 style95 determined by the QualifierAlignment style flag96 --sort-includes - If set, overrides the include sorting behavior97 determined by the SortIncludes style flag98 --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 a102 .clang-format file in one of the parent directories103 of the source file (for stdin, see --assume-filename).104 If no .clang-format file is found, falls back to105 --fallback-style.106 --style=file is the default.107 3. 'file:<format_file_path>' to explicitly specify108 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 files112 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 program118 119 120.. END_FORMAT_HELP121 122When the desired code formatting style is different from the available options,123the style can be customized using the ``-style="{key: value, ...}"`` option or124by 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:: console130 131 clang-format -style=llvm -dump-config > .clang-format132 133Available style options are described in :doc:`ClangFormatStyleOptions`.134 135.clang-format-ignore136====================137 138You can create ``.clang-format-ignore`` files to make ``clang-format`` ignore139certain files. A ``.clang-format-ignore`` file consists of patterns of file path140names. It has the following format:141 142* A blank line is skipped.143* Leading and trailing spaces of a line are trimmed.144* A line starting with a hash (``#``) is a comment.145* A non-comment line is a single pattern.146* The slash (``/``) is used as the directory separator.147* A pattern is relative to the directory of the ``.clang-format-ignore`` file148 (or the root directory if the pattern starts with a slash). Patterns149 containing drive names (e.g. ``C:``) are not supported.150* Patterns follow the rules specified in `POSIX 2.13.1, 2.13.2, and Rule 1 of151 2.13.3 <https://pubs.opengroup.org/onlinepubs/9699919799/utilities/152 V3_chap02.html#tag_18_13>`_.153* Bash globstar (``**``) is supported.154* A pattern is negated if it starts with a bang (``!``).155 156To match all files in a directory, use e.g. ``foo/bar/*``. To match all files in157the directory of the ``.clang-format-ignore`` file, use ``*``.158Multiple ``.clang-format-ignore`` files are supported similar to the159``.clang-format`` files, with a lower directory level file voiding the higher160level ones.161 162Vim Integration163===============164 165There is an integration for :program:`vim` which lets you run the166:program:`clang-format` standalone tool on your current buffer, optionally167selecting regions to reformat. The integration has the form of a `python`-file168which can be found under `clang/tools/clang-format/clang-format.py`.169 170This can be integrated by adding the following to your `.vimrc`:171 172.. code-block:: vim173 174 if has('python')175 map <C-K> :pyf <path-to-this-file>/clang-format.py<cr>176 imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr>177 elseif has('python3')178 map <C-K> :py3f <path-to-this-file>/clang-format.py<cr>179 imap <C-K> <c-o>:py3f <path-to-this-file>/clang-format.py<cr>180 endif181 182The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the183second line adds support for INSERT mode. Change "C-K" to another binding if184you need :program:`clang-format` on a different key (C-K stands for Ctrl+k).185 186With this integration you can press the bound key and clang-format will187format the current line in NORMAL and INSERT mode or the selected region in188VISUAL mode. The line or region is extended to the next bigger syntactic189entity.190 191It operates on the current, potentially unsaved buffer and does not create192or save any files. To revert a formatting, just undo.193 194An alternative option is to format changes when saving a file and thus to195have a zero-effort integration into the coding workflow. To do this, add this to196your `.vimrc`:197 198.. code-block:: vim199 200 function! Formatonsave()201 let l:formatdiff = 1202 pyf <path-to-this-file>/clang-format.py203 endfunction204 autocmd BufWritePre *.h,*.cc,*.cpp call Formatonsave()205 206 207Emacs Integration208=================209 210Similar to the integration for :program:`vim`, there is an integration for211:program:`emacs`. It can be found at `clang/tools/clang-format/clang-format.el`212and used by adding this to your `.emacs`:213 214.. code-block:: common-lisp215 216 (load "<path-to-clang>/tools/clang-format/clang-format.el")217 (global-set-key [C-M-tab] 'clang-format-region)218 219This binds the function `clang-format-region` to C-M-tab, which then formats the220current line or selected region.221 222 223BBEdit Integration224==================225 226:program:`clang-format` cannot be used as a text filter with BBEdit, but works227well via a script. The AppleScript to do this integration can be found at228`clang/tools/clang-format/clang-format-bbedit.applescript`; place a copy in229`~/Library/Application Support/BBEdit/Scripts`, and edit the path within it to230point to your local copy of :program:`clang-format`.231 232With this integration you can select the script from the Script menu and233:program:`clang-format` will format the selection. Note that you can rename the234menu item by renaming the script, and can assign the menu item a keyboard235shortcut in the BBEdit preferences, under Menus & Shortcuts.236 237 238CLion Integration239=================240 241:program:`clang-format` is integrated into `CLion <https://www.jetbrains242.com/clion/>`_ as an alternative code formatter. CLion turns it on243automatically when there is a ``.clang-format`` file under the project root.244Code style rules are applied as you type, including indentation,245auto-completion, code generation, and refactorings.246 247:program:`clang-format` can also be enabled without a ``.clang-format`` file.248In this case, CLion prompts you to create one based on the current IDE settings249or the default LLVM style.250 251 252Visual Studio Integration253=========================254 255Download the latest Visual Studio extension from the `alpha build site256<https://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F.257 258 259Visual Studio Code Integration260==============================261 262Get 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.263 264Git integration265===============266 267The script `clang/tools/clang-format/git-clang-format` can be used to268format just the lines touched in git commits:269 270.. code-block:: console271 272 % git clang-format -h273 usage: git clang-format [OPTIONS] [<commit>] [<commit>|--staged] [--] [<file>...]274 275 If zero or one commits are given, run clang-format on all lines that differ276 between the working directory and <commit>, which defaults to HEAD. Changes are277 only applied to the working directory, or in the stage/index.278 279 Examples:280 To format staged changes, i.e everything that's been `git add`ed:281 git clang-format282 283 To also format everything touched in the most recent commit:284 git clang-format HEAD~1285 286 If you're on a branch off main, to format everything touched on your branch:287 git clang-format main288 289 If two commits are given (requires --diff), run clang-format on all lines in the290 second <commit> that differ from the first <commit>.291 292 The following git-config settings set the default of the corresponding option:293 clangFormat.binary294 clangFormat.commit295 clangFormat.extensions296 clangFormat.style297 298 positional arguments:299 <commit> revision from which to compute the diff300 <file>... if specified, only consider differences in these files301 302 optional arguments:303 -h, --help show this help message and exit304 --binary BINARY path to clang-format305 --commit COMMIT default commit to use if none is specified306 --diff print a diff instead of applying the changes307 --diffstat print a diffstat instead of applying the changes308 --extensions EXTENSIONS309 comma-separated list of file extensions to format, excluding the period and case-insensitive310 -f, --force allow changes to unstaged files311 -p, --patch select hunks interactively312 -q, --quiet print less information313 --staged, --cached format lines in the stage instead of the working dir314 --style STYLE passed to clang-format315 -v, --verbose print extra information316 317 318Script for patch reformatting319=============================320 321The python script `clang/tools/clang-format/clang-format-diff.py` parses the322output of a unified diff and reformats all contained lines with323:program:`clang-format`.324 325.. code-block:: console326 327 usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-iregex PATTERN] [-sort-includes] [-v] [-style STYLE]328 [-fallback-style FALLBACK_STYLE] [-binary BINARY]329 330 This script reads input from a unified diff and reformats all the changed331 lines. This is useful to reformat all the lines touched by a specific patch.332 Example usage for git/svn users:333 334 git diff -U0 --no-color --relative HEAD^ | clang-format-diff.py -p1 -i335 svn diff --diff-cmd=diff -x-U0 | clang-format-diff.py -i336 337 It should be noted that the filename contained in the diff is used unmodified338 to determine the source file to update. Users calling this script directly339 should be careful to ensure that the path in the diff is correct relative to the340 current working directory.341 342 optional arguments:343 -h, --help show this help message and exit344 -i apply edits to files instead of displaying a diff345 -p NUM strip the smallest prefix containing P slashes346 -regex PATTERN custom pattern selecting file paths to reformat (case sensitive, overrides -iregex)347 -iregex PATTERN custom pattern selecting file paths to reformat (case insensitive, overridden by -regex)348 -sort-includes let clang-format sort include blocks349 -v, --verbose be more verbose, ineffective without -i350 -style STYLE formatting style to apply (LLVM, GNU, Google, Chromium, Microsoft, Mozilla, WebKit)351 -fallback-style FALLBACK_STYLE352 The name of the predefined style used as a fallback in case clang-format is invoked with-style=file, but can not353 find the .clang-formatfile to use.354 -binary BINARY location of binary to use for clang-format355 356To reformat all the lines in the latest Mercurial/:program:`hg` commit, do:357 358.. code-block:: console359 360 hg diff -U0 --color=never | clang-format-diff.py -i -p1361 362The option `-U0` will create a diff without context lines (the script would format363those as well).364 365These commands use the file paths shown in the diff output366so they will only work from the root of the repository.367