OLD | NEW |
(Empty) | |
| 1 ## Using clang-format on Chromium C++ Code |
| 2 |
| 3 ### Easiest usage, from the command line |
| 4 |
| 5 To automatically format a pending patch according to <a href='http://www.chromiu
m.org/developers/coding-style'>Chromium style</a>, from the command line, simply
run: |
| 6 ``` |
| 7 git cl format |
| 8 ``` |
| 9 This should work on all platforms _(yes, even Windows)_ without any set up or co
nfiguration: the tool comes with your checkout. Like other `git-cl` commands, th
is operates on a diff relative to the upstream branch. Only the lines that you'v
e already touched in your patch will be reformatted. You can commit your changes
to your git branch and then run `git cl format`, after which `git diff` will sh
ow you what clang-format changed. Alternatively, you can run `git cl format` wit
h your changes uncommitted, and then commit your now-formatted code. |
| 10 |
| 11 ### Editor integrations |
| 12 |
| 13 Many developers find it useful to integrate the clang-format tool with their edi
tor of choice. As a convenience, the scripts for this are also available in your
checkout of Chrome under <a href='https://code.google.com/p/chromium/codesearch
#chromium/src/buildtools/clang_format/script/'><code>src/buildtools/clang_format
/script/</code></a>. |
| 14 |
| 15 If you use an editor integration, you should try to make sure that you're using
the version of clang-format that comes with your checkout. That way, you'll auto
matically get updates and be running a tool that formats consistently with other
developers. The binary lives under `src/buildtools`, but it's also in your path
indirectly via a `depot_tools` launcher script: <a href='https://code.google.co
m/p/chromium/codesearch#chromium/tools/depot_tools/clang-format'><code>clang-for
mat</code></a> (<a href='https://code.google.com/p/chromium/codesearch#chromium/
tools/depot_tools/clang-format.bat'><code>clang-format.bat</code></a> on Windows
). Assuming that `depot_tools` is in your editor's `PATH` and the editor command
runs from a working directory inside the Chromium checkout, the editor scripts
(which anticipate clang-format on the path) should work. |
| 16 |
| 17 For further guidance on editor integration, see these specific pages: |
| 18 * <a href='http://www.chromium.org/developers/sublime-text#TOC-Format-selectio
n-or-area-around-cursor-using-clang-format'>Sublime Text</a> |
| 19 * <a href='http://clang.llvm.org/docs/ClangFormat.html '>llvm's guidelines for
vim, emacs, and bbedit</a> |
| 20 * For vim, `:so tools/vim/clang-format.vim` and then hit cmd-shift-i (mac) c
trl-shift-i (elsewhere) to indent the current line or current selection. |
| 21 |
| 22 ### Are robots taking over my freedom to choose where newlines go? |
| 23 |
| 24 No. For the project as a whole, using clang-format is just one optional way to f
ormat your code. While it will produce style-guide conformant code, other format
tings would also satisfy the style guide, and all are okay. |
| 25 |
| 26 Having said that, many clang-format converts have found that relying on a tool s
aves both them and their reviewers time. The saved time can then be used to disc
over functional defects in their patch, to address style/readability concerns wh
ose resolution can't be automated, or to do something else that matters. |
| 27 |
| 28 In directories where most contributors have already adopted clang-format, and co
de is already consistent with what clang-format would produce, some teams intend
to experiment with standardizing on clang-format. When these local standards ap
ply, it will be enforced by a PRESUBMIT.py check. |
| 29 |
| 30 ### Reporting problems |
| 31 |
| 32 If clang-format is broken, or produces badly formatted code, please file a <a hr
ef='https://code.google.com/p/chromium/issues/entry?comment=clang-format%20produ
ced%20code%20that%20(choose%20all%20that%20apply):%20%0A-%20Doesn%27t%20match%20
Chromium%20style%0A-%20Doesn%27t%20match%20blink%20style%0A-%20Riles%20my%20fine
ly%20honed%20stylistic%20dander%0A-%20No%20sane%20human%20would%20ever%20choose%
0A%0AHere%27s%20the%20code%20before%20formatting:%0A%0A%0AHere%27s%20the%20code%
20after%20formatting:%0A%0A%0AHere%27s%20how%20it%20ought%20to%20look:%0A%0A%0AC
ode%20review%20link%20for%20full%20files/context:&summary=clang-format%20quality
%20problem&cc=thakis@chromium.org,%20nick@chromium.org&labels=Type-Bug,Build-Too
ls,OS-?'>Chromium bug using this link</a>. Assign it to thakis@chromium.org or n
ick@chromium.org who will route it upstream. |
OLD | NEW |