clang/docs/ClangFormat.rst

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