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