OLD | NEW |
1 ## Using clang-format on Chromium C++ Code | 1 # Using clang-format on Chromium C++ Code |
2 | 2 |
3 ### Easiest usage, from the command line | 3 ## Easiest usage, from the command line |
4 | 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: | 5 To automatically format a pending patch according to |
6 ``` | 6 [Chromium style](http://www.chromium.org/developers/coding-style), from |
7 git cl format | 7 the command line, simply run: ``` git cl format ``` This should work on all |
8 ``` | 8 platforms _(yes, even Windows)_ without any set up or configuration: the tool |
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. | 9 comes with your checkout. Like other `git-cl` commands, this operates on a diff |
| 10 relative to the upstream branch. Only the lines that you've already touched in |
| 11 your patch will be reformatted. You can commit your changes to your git branch |
| 12 and then run `git cl format`, after which `git diff` will show you what |
| 13 clang-format changed. Alternatively, you can run `git cl format` with your |
| 14 changes uncommitted, and then commit your now-formatted code. |
10 | 15 |
11 ### Editor integrations | 16 ## Editor integrations |
12 | 17 |
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>. | 18 Many developers find it useful to integrate the clang-format tool with their |
| 19 editor of choice. As a convenience, the scripts for this are also available in |
| 20 your checkout of Chrome under |
| 21 [src/buildtools/clang_format/script/](https://code.google.com/p/chromium/codesea
rch#chromium/src/buildtools/clang_format/script/). |
14 | 22 |
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. | 23 If you use an editor integration, you should try to make sure that you're using |
| 24 the version of clang-format that comes with your checkout. That way, you'll |
| 25 automatically get updates and be running a tool that formats consistently with |
| 26 other developers. The binary lives under `src/buildtools`, but it's also in your |
| 27 path indirectly via a `depot_tools` launcher script: |
| 28 [clang-format](https://code.google.com/p/chromium/codesearch#chromium/tools/depo
t_tools/clang-format) |
| 29 ([clang-format.bat](https://code.google.com/p/chromium/codesearch#chromium/tools
/depot_tools/clang-format.bat) on Windows). Assuming that `depot_tools` is in yo
ur editor's `PATH` |
| 30 and the editor command runs from a working directory inside the Chromium |
| 31 checkout, the editor scripts (which anticipate clang-format on the path) should |
| 32 work. |
16 | 33 |
17 For further guidance on editor integration, see these specific pages: | 34 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 | 35 |
22 ### Are robots taking over my freedom to choose where newlines go? | 36 * [Sublime Text](http://www.chromium.org/developers/sublime-text#TOC-Format-se
lection-or-area-around-cursor-using-clang-format) |
| 37 * [llvm's guidelines for vim, emacs, and bbedit](http://clang.llvm.org/docs/Cl
angFormat.html) |
| 38 * For vim, `:so tools/vim/clang-format.vim` and then hit cmd-shift-i (mac) |
| 39 ctrl-shift-i (elsewhere) to indent the current line or current selection. |
23 | 40 |
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. | 41 ## Are robots taking over my freedom to choose where newlines go? |
25 | 42 |
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. | 43 No. For the project as a whole, using clang-format is just one optional way to |
| 44 format your code. While it will produce style-guide conformant code, other |
| 45 formattings would also satisfy the style guide, and all are okay. |
27 | 46 |
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. | 47 Having said that, many clang-format converts have found that relying on a tool |
| 48 saves both them and their reviewers time. The saved time can then be used to |
| 49 discover functional defects in their patch, to address style/readability |
| 50 concerns whose resolution can't be automated, or to do something else that |
| 51 matters. |
29 | 52 |
30 ### Reporting problems | 53 In directories where most contributors have already adopted clang-format, and |
| 54 code is already consistent with what clang-format would produce, some teams |
| 55 intend to experiment with standardizing on clang-format. When these local |
| 56 standards apply, it will be enforced by a PRESUBMIT.py check. |
31 | 57 |
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. | 58 ## Reporting problems |
| 59 |
| 60 If clang-format is broken, or produces badly formatted code, please file a |
| 61 [bug]. Assign it to thakis@chromium.org or nick@chromium.org who will route it |
| 62 upstream. |
| 63 |
| 64 [bug]: |
| 65 https://code.google.com/p/chromium/issues/entry?comment=clang-format%20produced%
20code%20that%20(choose%20all%20that%20apply):%20%0A-%20Doesn%27t%20match%20Chro
mium%20style%0A-%20Doesn%27t%20match%20blink%20style%0A-%20Riles%20my%20finely%2
0honed%20stylistic%20dander%0A-%20No%20sane%20human%20would%20ever%20choose%0A%0
AHere%27s%20the%20code%20before%20formatting:%0A%0A%0AHere%27s%20the%20code%20af
ter%20formatting:%0A%0A%0AHere%27s%20how%20it%20ought%20to%20look:%0A%0A%0ACode%
20review%20link%20for%20full%20files/context:&summary=clang-format%20quality%20p
roblem&cc=thakis@chromium.org,%20nick@chromium.org&labels=Type-Bug,Build-Tools,O
S-? |
OLD | NEW |