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
  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
 122 When the desired code formatting style is different from the available options,
 123 the style can be customized using the ``-style="{key: value, ...}"`` option or
 124 by putting your style configuration in the ``.clang-format`` or ``_clang-format``
 125 file in your project's directory and using ``clang-format -style=file``.
 126
 127 An 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
 133 Available style options are described in :doc:`ClangFormatStyleOptions`.
 134
 135
 136 Vim Integration
 137 ===============
 138
 139 There is an integration for :program:`vim` which lets you run the
 140 :program:`clang-format` standalone tool on your current buffer, optionally
 141 selecting regions to reformat. The integration has the form of a `python`-file
 142 which can be found under `clang/tools/clang-format/clang-format.py`.
 143
 144 This 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
 151 The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the
 152 second line adds support for INSERT mode. Change "C-K" to another binding if
 153 you need :program:`clang-format` on a different key (C-K stands for Ctrl+k).
 154
 155 With this integration you can press the bound key and clang-format will
 156 format the current line in NORMAL and INSERT mode or the selected region in
 157 VISUAL mode. The line or region is extended to the next bigger syntactic
 158 entity.
 159
 160 It operates on the current, potentially unsaved buffer and does not create
 161 or save any files. To revert a formatting, just undo.
 162
 163 An alternative option is to format changes when saving a file and thus to
 164 have a zero-effort integration into the coding workflow. To do this, add this to
 165 your `.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
 176 Emacs Integration
 177 =================
 178
 179 Similar 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`
 181 and 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
 188 This binds the function `clang-format-region` to C-M-tab, which then formats the
 189 current line or selected region.
 190
 191
 192 BBEdit Integration
 193 ==================
 194
 195 :program:`clang-format` cannot be used as a text filter with BBEdit, but works
 196 well 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
 199 point to your local copy of :program:`clang-format`.
 200
 201 With 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
 203 menu item by renaming the script, and can assign the menu item a keyboard
 204 shortcut in the BBEdit preferences, under Menus & Shortcuts.
 205
 206
 207 CLion 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
 212 automatically when there is a ``.clang-format`` file under the project root.
 213 Code style rules are applied as you type, including indentation,
 214 auto-completion, code generation, and refactorings.
 215
 216 :program:`clang-format` can also be enabled without a ``.clang-format`` file.
 217 In this case, CLion prompts you to create one based on the current IDE settings
 218 or the default LLVM style.
 219
 220
 221 Visual Studio Integration
 222 =========================
 223
 224 Download 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
 228 Visual Studio Code Integration
 229 ==============================
 230
 231 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.
 232
 233 Git integration
 234 ===============
 235
 236 The script `clang/tools/clang-format/git-clang-format` can be used to
 237 format 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
 287 Script for patch reformatting
 288 =============================
 289
 290 The python script `clang/tools/clang-format/clang-format-diff.py` parses the
 291 output 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
 325 To 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
 331 The option `-U0` will create a diff without context lines (the script would format
 332 those as well).
 333
 334 These commands use the file paths shown in the diff output
 335 so they will only work from the root of the repository.
 336
 337 Current State of Clang Format for LLVM
 338 ======================================
 339
 340 The following table :doc:`ClangFormattedStatus` shows the current status of clang-formatting for the entire LLVM source tree.