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