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 part of the `clang/tools/extra` (see 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 45 There is an integration for :program:`vim` which lets you run the 46 :program:`clang-format` standalone tool on your current buffer, optionally 47 selecting regions to reformat. The integration has the form of a `python`-file 48 which can be found under `clang/tools/extra/clang-format/clang-format.py`. 49 50 This can be integrated by adding the following to your `.vimrc`: 51 52 .. code-block:: vim 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 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). 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 74 a unified diff and reformats all contained lines with :program:`clang-format`. 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 87 So to reformat all the lines in the latest :program:`git` commit, just do: 88 89 .. code-block:: console 90 91 git diff -U0 HEAD^ | clang-format-diff.py 92 93 The :option:`-U0` will create a diff without context lines (the script would format 94 those as well). 95
