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