docs/ClangFormat.rst

   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 located in `clang/tools/clang-format` and can be used
  14 to format C/C++/Obj-C code.
  15
  16 .. code-block:: console
  17
  18   $ clang-format -help
  19   OVERVIEW: A tool to format C/C++/Obj-C code.
  20
  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>s are given, it reformats the files. If -i is specified
  24   together with <file>s, the files are edited in-place. Otherwise, the
  25   result is written to the standard output.
  26
  27   USAGE: clang-format [options] [<file> ...]
  28
  29   OPTIONS:
  30
  31   Clang-format options:
  32
  33     -cursor=<uint>           - The position of the cursor when invoking
  34                                clang-format from an editor integration
  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.
  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.
  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:
  57                                  LLVM, Google, Chromium, Mozilla, WebKit.
  58                                Use -style=file to load style configuration from
  59                                .clang-format file located in one of the parent
  60                                directories of the source file (or current
  61                                directory for stdin).
  62                                Use -style="{key: value, ...}" to set specific
  63                                parameters, e.g.:
  64                                  -style="{BasedOnStyle: llvm, IndentWidth: 8}"
  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
  71
  72
  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
  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``.
  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
  87 Vim Integration
  88 ===============
  89
  90 There is an integration for :program:`vim` which lets you run the
  91 :program:`clang-format` standalone tool on your current buffer, optionally
  92 selecting regions to reformat. The integration has the form of a `python`-file
  93 which can be found under `clang/tools/clang-format/clang-format.py`.
  94
  95 This can be integrated by adding the following to your `.vimrc`:
  96
  97 .. code-block:: vim
  98
  99   map <C-K> :pyf <path-to-this-file>/clang-format.py<CR>
 100   imap <C-K> <ESC>:pyf <path-to-this-file>/clang-format.py<CR>i
 101
 102 The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the
 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).
 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
 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
 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
 146 Visual Studio Integration
 147 =========================
 148
 149 Download the latest Visual Studio plugin from the `alpha build site
 150 <http://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F.
 151
 152
 153 Script for patch reformatting
 154 =============================
 155
 156 The python script `clang/tools/clang-format-diff.py` parses the output of
 157 a unified diff and reformats all contained lines with :program:`clang-format`.
 158
 159 .. code-block:: console
 160
 161   usage: clang-format-diff.py [-h] [-p P] [-style STYLE]
 162
 163   Reformat changed lines in diff.
 164
 165   optional arguments:
 166     -h, --help    show this help message and exit
 167     -p P          strip the smallest prefix containing P slashes
 168     -style STYLE  formatting style to apply (LLVM, Google, Chromium, Mozilla,
 169                   WebKit)
 170
 171 So to reformat all the lines in the latest :program:`git` commit, just do:
 172
 173 .. code-block:: console
 174
 175   git diff -U0 HEAD^ | clang-format-diff.py -p1
 176
 177 The :option:`-U0` will create a diff without context lines (the script would format
 178 those as well).