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 | |
Dmitri Gribenko | ee1230c | 2013-01-09 22:18:55 +0000 | [diff] [blame] | 13 | :program:`clang-format` is part of the `clang/tools/extra` (see |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 14 | :doc:`ClangTools <ClangTools>`) repository and can be used to format |
| 15 | C/C++/Obj-C code. |
| 16 | |
| 17 | .. code-block:: console |
| 18 | |
| 19 | $ clang-format --help |
| 20 | OVERVIEW: A tool to format C/C++/Obj-C code. |
| 21 | |
| 22 | Currently supports LLVM and Google style guides. |
| 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> is given, it reformats the file. If -i is specified together |
| 26 | with <file>, the file is edited in-place. Otherwise, the result is |
| 27 | written to the standard output. |
| 28 | |
| 29 | USAGE: clang-format [options] [<file>] |
| 30 | |
| 31 | OPTIONS: |
| 32 | -fatal-assembler-warnings - Consider warnings as error |
| 33 | -help - Display available options (-help-hidden for more) |
| 34 | -i - Inplace edit <file>, if specified. |
| 35 | -length=<int> - Format a range of this length, -1 for end of file. |
| 36 | -offset=<int> - Format a range starting at this file offset. |
| 37 | -stats - Enable statistics output from program |
| 38 | -style=<string> - Coding style, currently supports: LLVM, Google. |
| 39 | -version - Display the version of this program |
| 40 | |
| 41 | |
| 42 | Vim Integration |
| 43 | =============== |
| 44 | |
Dmitri Gribenko | ee1230c | 2013-01-09 22:18:55 +0000 | [diff] [blame] | 45 | There is an integration for :program:`vim` which lets you run the |
| 46 | :program:`clang-format` standalone tool on your current buffer, optionally |
Hans Wennborg | 280b956 | 2013-02-28 18:16:24 +0000 | [diff] [blame] | 47 | selecting regions to reformat. The integration has the form of a `python`-file |
Dmitri Gribenko | ee1230c | 2013-01-09 22:18:55 +0000 | [diff] [blame] | 48 | which can be found under `clang/tools/extra/clang-format/clang-format.py`. |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 49 | |
Hans Wennborg | 280b956 | 2013-02-28 18:16:24 +0000 | [diff] [blame] | 50 | This can be integrated by adding the following to your `.vimrc`: |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 51 | |
Sean Silva | e7259ae | 2013-03-03 15:17:35 +0000 | [diff] [blame] | 52 | .. code-block:: vim |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 53 | |
| 54 | map <C-I> :pyf <path-to-this-file>/clang-format.py<CR> |
| 55 | imap <C-I> <ESC>:pyf <path-to-this-file>/clang-format.py<CR>i |
| 56 | |
Dmitri Gribenko | ee1230c | 2013-01-09 22:18:55 +0000 | [diff] [blame] | 57 | The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the |
| 58 | second line adds support for INSERT mode. Change "C-I" to another binding if |
| 59 | you need :program:`clang-format` on a different key (C-I stands for Ctrl+i). |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 60 | |
| 61 | With this integration you can press the bound key and clang-format will |
| 62 | format the current line in NORMAL and INSERT mode or the selected region in |
| 63 | VISUAL mode. The line or region is extended to the next bigger syntactic |
| 64 | entity. |
| 65 | |
| 66 | It operates on the current, potentially unsaved buffer and does not create |
| 67 | or save any files. To revert a formatting, just undo. |
| 68 | |
| 69 | |
| 70 | Script for patch reformatting |
| 71 | ============================= |
| 72 | |
| 73 | The python script `clang/tools/extra/clang-format-diff.py` parses the output of |
Dmitri Gribenko | ee1230c | 2013-01-09 22:18:55 +0000 | [diff] [blame] | 74 | a unified diff and reformats all contained lines with :program:`clang-format`. |
Daniel Jasper | 6d5b57a | 2013-01-09 21:49:28 +0000 | [diff] [blame] | 75 | |
| 76 | .. code-block:: console |
| 77 | |
| 78 | usage: clang-format-diff.py [-h] [-p P] [-style STYLE] |
| 79 | |
| 80 | Reformat changed lines in diff |
| 81 | |
| 82 | optional arguments: |
| 83 | -h, --help show this help message and exit |
| 84 | -p P strip the smallest prefix containing P slashes |
| 85 | -style STYLE formatting style to apply (LLVM, Google) |
| 86 | |
Dmitri Gribenko | ee1230c | 2013-01-09 22:18:55 +0000 | [diff] [blame] | 87 | 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] | 88 | |
| 89 | .. code-block:: console |
| 90 | |
| 91 | git diff -U0 HEAD^ | clang-format-diff.py |
Dmitri Gribenko | ee1230c | 2013-01-09 22:18:55 +0000 | [diff] [blame] | 92 | |
| 93 | 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] | 94 | those as well). |