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++/Obj-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 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 -assume-filename=<string> - When reading from stdin, clang-format assumes this 34 filename to look for a style config file (with 35 -style=file) and to determine the language. 36 -cursor=<uint> - The position of the cursor when invoking 37 clang-format from an editor integration 38 -dump-config - Dump configuration options to stdout and exit. 39 Can be used with -style option. 40 -fallback-style=<string> - The name of the predefined style used as a 41 fallback in case clang-format is invoked with 42 -style=file, but can not find the .clang-format 43 file to use. 44 Use -fallback-style=none to skip formatting. 45 -i - Inplace edit <file>s, if specified. 46 -length=<uint> - Format a range of this length (in bytes). 47 Multiple ranges can be formatted by specifying 48 several -offset and -length pairs. 49 When only a single -offset is specified without 50 -length, clang-format will format up to the end 51 of the file. 52 Can only be used with one input file. 53 -lines=<string> - <start line>:<end line> - format a range of 54 lines (both 1-based). 55 Multiple ranges can be formatted by specifying 56 several -lines arguments. 57 Can't be used with -offset and -length. 58 Can only be used with one input file. 59 -offset=<uint> - Format a range starting at this byte offset. 60 Multiple ranges can be formatted by specifying 61 several -offset and -length pairs. 62 Can only be used with one input file. 63 -output-replacements-xml - Output replacements as XML. 64 -sort-includes - Sort touched include lines 65 -style=<string> - Coding style, currently supports: 66 LLVM, Google, Chromium, Mozilla, WebKit. 67 Use -style=file to load style configuration from 68 .clang-format file located in one of the parent 69 directories of the source file (or current 70 directory for stdin). 71 Use -style="{key: value, ...}" to set specific 72 parameters, e.g.: 73 -style="{BasedOnStyle: llvm, IndentWidth: 8}" 74 75 Generic Options: 76 77 -help - Display available options (-help-hidden for more) 78 -help-list - Display list of available options (-help-list-hidden for more) 79 -version - Display the version of this program 80 81 82 When the desired code formatting style is different from the available options, 83 the style can be customized using the ``-style="{key: value, ...}"`` option or 84 by putting your style configuration in the ``.clang-format`` or ``_clang-format`` 85 file in your project's directory and using ``clang-format -style=file``. 86 87 An easy way to create the ``.clang-format`` file is: 88 89 .. code-block:: console 90 91 clang-format -style=llvm -dump-config > .clang-format 92 93 Available style options are described in :doc:`ClangFormatStyleOptions`. 94 95 96 Vim Integration 97 =============== 98 99 There is an integration for :program:`vim` which lets you run the 100 :program:`clang-format` standalone tool on your current buffer, optionally 101 selecting regions to reformat. The integration has the form of a `python`-file 102 which can be found under `clang/tools/clang-format/clang-format.py`. 103 104 This can be integrated by adding the following to your `.vimrc`: 105 106 .. code-block:: vim 107 108 map <C-K> :pyf <path-to-this-file>/clang-format.py<cr> 109 imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr> 110 111 The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the 112 second line adds support for INSERT mode. Change "C-K" to another binding if 113 you need :program:`clang-format` on a different key (C-K stands for Ctrl+k). 114 115 With this integration you can press the bound key and clang-format will 116 format the current line in NORMAL and INSERT mode or the selected region in 117 VISUAL mode. The line or region is extended to the next bigger syntactic 118 entity. 119 120 It operates on the current, potentially unsaved buffer and does not create 121 or save any files. To revert a formatting, just undo. 122 123 124 Emacs Integration 125 ================= 126 127 Similar to the integration for :program:`vim`, there is an integration for 128 :program:`emacs`. It can be found at `clang/tools/clang-format/clang-format.el` 129 and used by adding this to your `.emacs`: 130 131 .. code-block:: common-lisp 132 133 (load "<path-to-clang>/tools/clang-format/clang-format.el") 134 (global-set-key [C-M-tab] 'clang-format-region) 135 136 This binds the function `clang-format-region` to C-M-tab, which then formats the 137 current line or selected region. 138 139 140 BBEdit Integration 141 ================== 142 143 :program:`clang-format` cannot be used as a text filter with BBEdit, but works 144 well via a script. The AppleScript to do this integration can be found at 145 `clang/tools/clang-format/clang-format-bbedit.applescript`; place a copy in 146 `~/Library/Application Support/BBEdit/Scripts`, and edit the path within it to 147 point to your local copy of :program:`clang-format`. 148 149 With this integration you can select the script from the Script menu and 150 :program:`clang-format` will format the selection. Note that you can rename the 151 menu item by renaming the script, and can assign the menu item a keyboard 152 shortcut in the BBEdit preferences, under Menus & Shortcuts. 153 154 155 Visual Studio Integration 156 ========================= 157 158 Download the latest Visual Studio extension from the `alpha build site 159 <http://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F. 160 161 162 Script for patch reformatting 163 ============================= 164 165 The python script `clang/tools/clang-format-diff.py` parses the output of 166 a unified diff and reformats all contained lines with :program:`clang-format`. 167 168 .. code-block:: console 169 170 usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE] 171 172 Reformat changed lines in diff. Without -i option just output the diff that 173 would be introduced. 174 175 optional arguments: 176 -h, --help show this help message and exit 177 -i apply edits to files instead of displaying a diff 178 -p NUM strip the smallest prefix containing P slashes 179 -regex PATTERN custom pattern selecting file paths to reformat 180 -style STYLE formatting style to apply (LLVM, Google, Chromium, Mozilla, 181 WebKit) 182 183 So to reformat all the lines in the latest :program:`git` commit, just do: 184 185 .. code-block:: console 186 187 git diff -U0 HEAD^ | clang-format-diff.py -i -p1 188 189 In an SVN client, you can do: 190 191 .. code-block:: console 192 193 svn diff --diff-cmd=diff -x -U0 | clang-format-diff.py -i 194 195 The option `-U0` will create a diff without context lines (the script would format 196 those as well). 197
