Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 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 | |
Daniel Jasper | 0292519 | 2013-03-22 12:44:20 +0000 | [diff] [blame] | 13 | :program:`clang-format` is located in `clang/tools/clang-format` and can be used |
| 14 | to format C/C++/Obj-C code. |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 15 | |
| 16 | .. code-block:: console |
| 17 | |
Alexander Kornienko | 7de13bb | 2013-09-02 15:30:26 +0000 | [diff] [blame] | 18 | $ clang-format -help |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 19 | OVERVIEW: A tool to format C/C++/Obj-C code. |
| 20 | |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 21 | If no arguments are specified, it formats the code from standard input |
| 22 | and writes the result to the standard output. |
Alexander Kornienko | 7de13bb | 2013-09-02 15:30:26 +0000 | [diff] [blame] | 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 |
Alexander Kornienko | 46529e5 | 2013-05-10 18:12:00 +0000 | [diff] [blame] | 25 | result is written to the standard output. |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 26 | |
Alexander Kornienko | 46529e5 | 2013-05-10 18:12:00 +0000 | [diff] [blame] | 27 | USAGE: clang-format [options] [<file> ...] |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 28 | |
| 29 | OPTIONS: |
Alexander Kornienko | 46529e5 | 2013-05-10 18:12:00 +0000 | [diff] [blame] | 30 | |
| 31 | Clang-format options: |
| 32 | |
Alexander Kornienko | 7de13bb | 2013-09-02 15:30:26 +0000 | [diff] [blame] | 33 | -cursor=<uint> - The position of the cursor when invoking |
| 34 | clang-format from an editor integration |
Alexander Kornienko | 46529e5 | 2013-05-10 18:12:00 +0000 | [diff] [blame] | 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. |
Alexander Kornienko | 7de13bb | 2013-09-02 15:30:26 +0000 | [diff] [blame] | 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. |
Alexander Kornienko | 46529e5 | 2013-05-10 18:12:00 +0000 | [diff] [blame] | 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: |
Alexander Kornienko | 4e65c98 | 2013-09-02 16:39:23 +0000 | [diff] [blame] | 57 | LLVM, Google, Chromium, Mozilla, WebKit. |
Alexander Kornienko | 885f87b | 2013-05-19 00:53:30 +0000 | [diff] [blame] | 58 | Use -style=file to load style configuration from |
Alexander Kornienko | 46529e5 | 2013-05-10 18:12:00 +0000 | [diff] [blame] | 59 | .clang-format file located in one of the parent |
| 60 | directories of the source file (or current |
| 61 | directory for stdin). |
Alexander Kornienko | 885f87b | 2013-05-19 00:53:30 +0000 | [diff] [blame] | 62 | Use -style="{key: value, ...}" to set specific |
| 63 | parameters, e.g.: |
| 64 | -style="{BasedOnStyle: llvm, IndentWidth: 8}" |
Alexander Kornienko | 46529e5 | 2013-05-10 18:12:00 +0000 | [diff] [blame] | 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 |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 71 | |
| 72 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 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 |
Hans Wennborg | 9a7a50e | 2013-09-10 15:41:12 +0000 | [diff] [blame] | 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``. |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 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 | |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 87 | Vim Integration |
| 88 | =============== |
| 89 | |
Dmitri Gribenko | ee1230c | 2013-01-09 22:18:55 +0000 | [diff] [blame] | 90 | There is an integration for :program:`vim` which lets you run the |
| 91 | :program:`clang-format` standalone tool on your current buffer, optionally |
Hans Wennborg | 280b956 | 2013-02-28 18:16:24 +0000 | [diff] [blame] | 92 | selecting regions to reformat. The integration has the form of a `python`-file |
Daniel Jasper | 0292519 | 2013-03-22 12:44:20 +0000 | [diff] [blame] | 93 | which can be found under `clang/tools/clang-format/clang-format.py`. |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 94 | |
Hans Wennborg | 280b956 | 2013-02-28 18:16:24 +0000 | [diff] [blame] | 95 | This can be integrated by adding the following to your `.vimrc`: |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 96 | |
Sean Silva | e7259ae | 2013-03-03 15:17:35 +0000 | [diff] [blame] | 97 | .. code-block:: vim |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 98 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame^] | 99 | map <C-K> :pyf <path-to-this-file>/clang-format.py<cr> |
| 100 | imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr> |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 101 | |
Dmitri Gribenko | ee1230c | 2013-01-09 22:18:55 +0000 | [diff] [blame] | 102 | The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the |
Daniel Jasper | 0292519 | 2013-03-22 12:44:20 +0000 | [diff] [blame] | 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). |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 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 | |
Daniel Jasper | a50b578 | 2013-04-17 07:55:02 +0000 | [diff] [blame] | 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 | |
Daniel Jasper | 82e3b47 | 2013-05-02 17:37:36 +0000 | [diff] [blame] | 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 | |
Manuel Klimek | 7454cdc | 2013-09-29 17:49:50 +0000 | [diff] [blame] | 146 | Visual Studio Integration |
| 147 | ========================= |
| 148 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 149 | Download the latest Visual Studio extension from the `alpha build site |
Manuel Klimek | 7454cdc | 2013-09-29 17:49:50 +0000 | [diff] [blame] | 150 | <http://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F. |
| 151 | |
| 152 | |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 153 | Script for patch reformatting |
| 154 | ============================= |
| 155 | |
Daniel Jasper | 0292519 | 2013-03-22 12:44:20 +0000 | [diff] [blame] | 156 | The python script `clang/tools/clang-format-diff.py` parses the output of |
Dmitri Gribenko | ee1230c | 2013-01-09 22:18:55 +0000 | [diff] [blame] | 157 | a unified diff and reformats all contained lines with :program:`clang-format`. |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 158 | |
| 159 | .. code-block:: console |
| 160 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 161 | usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE] |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 162 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 163 | Reformat changed lines in diff. Without -i option just output the diff that |
| 164 | would be introduced. |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 165 | |
| 166 | optional arguments: |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 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) |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 173 | |
Dmitri Gribenko | ee1230c | 2013-01-09 22:18:55 +0000 | [diff] [blame] | 174 | So to reformat all the lines in the latest :program:`git` commit, just do: |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 175 | |
| 176 | .. code-block:: console |
| 177 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 178 | git diff -U0 HEAD^ | clang-format-diff.py -i -p1 |
Dmitri Gribenko | ee1230c | 2013-01-09 22:18:55 +0000 | [diff] [blame] | 179 | |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 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 | |
Dmitri Gribenko | ee1230c | 2013-01-09 22:18:55 +0000 | [diff] [blame] | 186 | The :option:`-U0` will create a diff without context lines (the script would format |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 187 | those as well). |