Clang 3.3 documentation

ClangFormat

«  ClangCheck   ::   Contents   ::   “Clang” CFE Internals Manual  »

ClangFormat

ClangFormat describes a set of tools that are built on top of LibFormat. It can support your workflow in a variety of ways including a standalone tool and editor integrations.

Standalone Tool

clang-format is located in clang/tools/clang-format and can be used to format C/C++/Obj-C code.

$ clang-format --help
OVERVIEW: A tool to format C/C++/Obj-C code.

If no arguments are specified, it formats the code from standard input
and writes the result to the standard output.
If <file> is given, it reformats the file. If -i is specified together
with <file>, the file is edited in-place. Otherwise, the result is
written to the standard output.

USAGE: clang-format [options] [<file>]

OPTIONS:
  -fatal-assembler-warnings - Consider warnings as error
  -help                     - Display available options (-help-hidden for more)
  -i                        - Inplace edit <file>, if specified.
  -length=<int>             - Format a range of this length, -1 for end of file.
  -offset=<int>             - Format a range starting at this file offset.
  -stats                    - Enable statistics output from program
  -style=<string>           - Coding style, currently supports: LLVM, Google, Chromium.
  -version                  - Display the version of this program

Vim Integration

There is an integration for vim which lets you run the clang-format standalone tool on your current buffer, optionally selecting regions to reformat. The integration has the form of a python-file which can be found under clang/tools/clang-format/clang-format.py.

This can be integrated by adding the following to your .vimrc:

map <C-K> :pyf <path-to-this-file>/clang-format.py<CR>
imap <C-K> <ESC>:pyf <path-to-this-file>/clang-format.py<CR>i

The first line enables clang-format for NORMAL and VISUAL mode, the second line adds support for INSERT mode. Change “C-K” to another binding if you need clang-format on a different key (C-K stands for Ctrl+k).

With this integration you can press the bound key and clang-format will format the current line in NORMAL and INSERT mode or the selected region in VISUAL mode. The line or region is extended to the next bigger syntactic entity.

It operates on the current, potentially unsaved buffer and does not create or save any files. To revert a formatting, just undo.

Emacs Integration

Similar to the integration for vim, there is an integration for emacs. It can be found at clang/tools/clang-format/clang-format.el and used by adding this to your .emacs:

(load "<path-to-clang>/tools/clang-format/clang-format.el")
(global-set-key [C-M-tab] 'clang-format-region)

This binds the function clang-format-region to C-M-tab, which then formats the current line or selected region.

BBEdit Integration

clang-format cannot be used as a text filter with BBEdit, but works well via a script. The AppleScript to do this integration can be found at clang/tools/clang-format/clang-format-bbedit.applescript; place a copy in ~/Library/Application Support/BBEdit/Scripts, and edit the path within it to point to your local copy of clang-format.

With this integration you can select the script from the Script menu and clang-format will format the selection. Note that you can rename the menu item by renaming the script, and can assign the menu item a keyboard shortcut in the BBEdit preferences, under Menus & Shortcuts.

Script for patch reformatting

The python script clang/tools/clang-format-diff.py parses the output of a unified diff and reformats all contained lines with clang-format.

usage: clang-format-diff.py [-h] [-p P] [-style STYLE]

Reformat changed lines in diff

optional arguments:
  -h, --help    show this help message and exit
  -p P          strip the smallest prefix containing P slashes
  -style STYLE  formatting style to apply (LLVM, Google, Chromium)

So to reformat all the lines in the latest git commit, just do:

git diff -U0 HEAD^ | clang-format-diff.py

The -U0 will create a diff without context lines (the script would format those as well).

«  ClangCheck   ::   Contents   ::   “Clang” CFE Internals Manual  »