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