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