1*67e74705SXin Li=========== 2*67e74705SXin LiClangFormat 3*67e74705SXin Li=========== 4*67e74705SXin Li 5*67e74705SXin Li`ClangFormat` describes a set of tools that are built on top of 6*67e74705SXin Li:doc:`LibFormat`. It can support your workflow in a variety of ways including a 7*67e74705SXin Listandalone tool and editor integrations. 8*67e74705SXin Li 9*67e74705SXin Li 10*67e74705SXin LiStandalone Tool 11*67e74705SXin Li=============== 12*67e74705SXin Li 13*67e74705SXin Li:program:`clang-format` is located in `clang/tools/clang-format` and can be used 14*67e74705SXin Lito format C/C++/Obj-C code. 15*67e74705SXin Li 16*67e74705SXin Li.. code-block:: console 17*67e74705SXin Li 18*67e74705SXin Li $ clang-format -help 19*67e74705SXin Li OVERVIEW: A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf code. 20*67e74705SXin Li 21*67e74705SXin Li If no arguments are specified, it formats the code from standard input 22*67e74705SXin Li and writes the result to the standard output. 23*67e74705SXin Li If <file>s are given, it reformats the files. If -i is specified 24*67e74705SXin Li together with <file>s, the files are edited in-place. Otherwise, the 25*67e74705SXin Li result is written to the standard output. 26*67e74705SXin Li 27*67e74705SXin Li USAGE: clang-format [options] [<file> ...] 28*67e74705SXin Li 29*67e74705SXin Li OPTIONS: 30*67e74705SXin Li 31*67e74705SXin Li Clang-format options: 32*67e74705SXin Li 33*67e74705SXin Li -assume-filename=<string> - When reading from stdin, clang-format assumes this 34*67e74705SXin Li filename to look for a style config file (with 35*67e74705SXin Li -style=file) and to determine the language. 36*67e74705SXin Li -cursor=<uint> - The position of the cursor when invoking 37*67e74705SXin Li clang-format from an editor integration 38*67e74705SXin Li -dump-config - Dump configuration options to stdout and exit. 39*67e74705SXin Li Can be used with -style option. 40*67e74705SXin Li -fallback-style=<string> - The name of the predefined style used as a 41*67e74705SXin Li fallback in case clang-format is invoked with 42*67e74705SXin Li -style=file, but can not find the .clang-format 43*67e74705SXin Li file to use. 44*67e74705SXin Li Use -fallback-style=none to skip formatting. 45*67e74705SXin Li -i - Inplace edit <file>s, if specified. 46*67e74705SXin Li -length=<uint> - Format a range of this length (in bytes). 47*67e74705SXin Li Multiple ranges can be formatted by specifying 48*67e74705SXin Li several -offset and -length pairs. 49*67e74705SXin Li When only a single -offset is specified without 50*67e74705SXin Li -length, clang-format will format up to the end 51*67e74705SXin Li of the file. 52*67e74705SXin Li Can only be used with one input file. 53*67e74705SXin Li -lines=<string> - <start line>:<end line> - format a range of 54*67e74705SXin Li lines (both 1-based). 55*67e74705SXin Li Multiple ranges can be formatted by specifying 56*67e74705SXin Li several -lines arguments. 57*67e74705SXin Li Can't be used with -offset and -length. 58*67e74705SXin Li Can only be used with one input file. 59*67e74705SXin Li -offset=<uint> - Format a range starting at this byte offset. 60*67e74705SXin Li Multiple ranges can be formatted by specifying 61*67e74705SXin Li several -offset and -length pairs. 62*67e74705SXin Li Can only be used with one input file. 63*67e74705SXin Li -output-replacements-xml - Output replacements as XML. 64*67e74705SXin Li -sort-includes - Sort touched include lines 65*67e74705SXin Li -style=<string> - Coding style, currently supports: 66*67e74705SXin Li LLVM, Google, Chromium, Mozilla, WebKit. 67*67e74705SXin Li Use -style=file to load style configuration from 68*67e74705SXin Li .clang-format file located in one of the parent 69*67e74705SXin Li directories of the source file (or current 70*67e74705SXin Li directory for stdin). 71*67e74705SXin Li Use -style="{key: value, ...}" to set specific 72*67e74705SXin Li parameters, e.g.: 73*67e74705SXin Li -style="{BasedOnStyle: llvm, IndentWidth: 8}" 74*67e74705SXin Li 75*67e74705SXin Li Generic Options: 76*67e74705SXin Li 77*67e74705SXin Li -help - Display available options (-help-hidden for more) 78*67e74705SXin Li -help-list - Display list of available options (-help-list-hidden for more) 79*67e74705SXin Li -version - Display the version of this program 80*67e74705SXin Li 81*67e74705SXin Li 82*67e74705SXin LiWhen the desired code formatting style is different from the available options, 83*67e74705SXin Lithe style can be customized using the ``-style="{key: value, ...}"`` option or 84*67e74705SXin Liby putting your style configuration in the ``.clang-format`` or ``_clang-format`` 85*67e74705SXin Lifile in your project's directory and using ``clang-format -style=file``. 86*67e74705SXin Li 87*67e74705SXin LiAn easy way to create the ``.clang-format`` file is: 88*67e74705SXin Li 89*67e74705SXin Li.. code-block:: console 90*67e74705SXin Li 91*67e74705SXin Li clang-format -style=llvm -dump-config > .clang-format 92*67e74705SXin Li 93*67e74705SXin LiAvailable style options are described in :doc:`ClangFormatStyleOptions`. 94*67e74705SXin Li 95*67e74705SXin Li 96*67e74705SXin LiVim Integration 97*67e74705SXin Li=============== 98*67e74705SXin Li 99*67e74705SXin LiThere is an integration for :program:`vim` which lets you run the 100*67e74705SXin Li:program:`clang-format` standalone tool on your current buffer, optionally 101*67e74705SXin Liselecting regions to reformat. The integration has the form of a `python`-file 102*67e74705SXin Liwhich can be found under `clang/tools/clang-format/clang-format.py`. 103*67e74705SXin Li 104*67e74705SXin LiThis can be integrated by adding the following to your `.vimrc`: 105*67e74705SXin Li 106*67e74705SXin Li.. code-block:: vim 107*67e74705SXin Li 108*67e74705SXin Li map <C-K> :pyf <path-to-this-file>/clang-format.py<cr> 109*67e74705SXin Li imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr> 110*67e74705SXin Li 111*67e74705SXin LiThe first line enables :program:`clang-format` for NORMAL and VISUAL mode, the 112*67e74705SXin Lisecond line adds support for INSERT mode. Change "C-K" to another binding if 113*67e74705SXin Liyou need :program:`clang-format` on a different key (C-K stands for Ctrl+k). 114*67e74705SXin Li 115*67e74705SXin LiWith this integration you can press the bound key and clang-format will 116*67e74705SXin Liformat the current line in NORMAL and INSERT mode or the selected region in 117*67e74705SXin LiVISUAL mode. The line or region is extended to the next bigger syntactic 118*67e74705SXin Lientity. 119*67e74705SXin Li 120*67e74705SXin LiIt operates on the current, potentially unsaved buffer and does not create 121*67e74705SXin Lior save any files. To revert a formatting, just undo. 122*67e74705SXin Li 123*67e74705SXin Li 124*67e74705SXin LiEmacs Integration 125*67e74705SXin Li================= 126*67e74705SXin Li 127*67e74705SXin LiSimilar to the integration for :program:`vim`, there is an integration for 128*67e74705SXin Li:program:`emacs`. It can be found at `clang/tools/clang-format/clang-format.el` 129*67e74705SXin Liand used by adding this to your `.emacs`: 130*67e74705SXin Li 131*67e74705SXin Li.. code-block:: common-lisp 132*67e74705SXin Li 133*67e74705SXin Li (load "<path-to-clang>/tools/clang-format/clang-format.el") 134*67e74705SXin Li (global-set-key [C-M-tab] 'clang-format-region) 135*67e74705SXin Li 136*67e74705SXin LiThis binds the function `clang-format-region` to C-M-tab, which then formats the 137*67e74705SXin Licurrent line or selected region. 138*67e74705SXin Li 139*67e74705SXin Li 140*67e74705SXin LiBBEdit Integration 141*67e74705SXin Li================== 142*67e74705SXin Li 143*67e74705SXin Li:program:`clang-format` cannot be used as a text filter with BBEdit, but works 144*67e74705SXin Liwell via a script. The AppleScript to do this integration can be found at 145*67e74705SXin Li`clang/tools/clang-format/clang-format-bbedit.applescript`; place a copy in 146*67e74705SXin Li`~/Library/Application Support/BBEdit/Scripts`, and edit the path within it to 147*67e74705SXin Lipoint to your local copy of :program:`clang-format`. 148*67e74705SXin Li 149*67e74705SXin LiWith this integration you can select the script from the Script menu and 150*67e74705SXin Li:program:`clang-format` will format the selection. Note that you can rename the 151*67e74705SXin Limenu item by renaming the script, and can assign the menu item a keyboard 152*67e74705SXin Lishortcut in the BBEdit preferences, under Menus & Shortcuts. 153*67e74705SXin Li 154*67e74705SXin Li 155*67e74705SXin LiVisual Studio Integration 156*67e74705SXin Li========================= 157*67e74705SXin Li 158*67e74705SXin LiDownload the latest Visual Studio extension from the `alpha build site 159*67e74705SXin Li<http://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F. 160*67e74705SXin Li 161*67e74705SXin Li 162*67e74705SXin LiScript for patch reformatting 163*67e74705SXin Li============================= 164*67e74705SXin Li 165*67e74705SXin LiThe python script `clang/tools/clang-format-diff.py` parses the output of 166*67e74705SXin Lia unified diff and reformats all contained lines with :program:`clang-format`. 167*67e74705SXin Li 168*67e74705SXin Li.. code-block:: console 169*67e74705SXin Li 170*67e74705SXin Li usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE] 171*67e74705SXin Li 172*67e74705SXin Li Reformat changed lines in diff. Without -i option just output the diff that 173*67e74705SXin Li would be introduced. 174*67e74705SXin Li 175*67e74705SXin Li optional arguments: 176*67e74705SXin Li -h, --help show this help message and exit 177*67e74705SXin Li -i apply edits to files instead of displaying a diff 178*67e74705SXin Li -p NUM strip the smallest prefix containing P slashes 179*67e74705SXin Li -regex PATTERN custom pattern selecting file paths to reformat 180*67e74705SXin Li -style STYLE formatting style to apply (LLVM, Google, Chromium, Mozilla, 181*67e74705SXin Li WebKit) 182*67e74705SXin Li 183*67e74705SXin LiSo to reformat all the lines in the latest :program:`git` commit, just do: 184*67e74705SXin Li 185*67e74705SXin Li.. code-block:: console 186*67e74705SXin Li 187*67e74705SXin Li git diff -U0 HEAD^ | clang-format-diff.py -i -p1 188*67e74705SXin Li 189*67e74705SXin LiIn an SVN client, you can do: 190*67e74705SXin Li 191*67e74705SXin Li.. code-block:: console 192*67e74705SXin Li 193*67e74705SXin Li svn diff --diff-cmd=diff -x -U0 | clang-format-diff.py -i 194*67e74705SXin Li 195*67e74705SXin LiThe option `-U0` will create a diff without context lines (the script would format 196*67e74705SXin Lithose as well). 197