| 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 | 5 To automatically format a pending patch according to |
| 6 [Chromium style](http://www.chromium.org/developers/coding-style), from | 6 [Chromium style](https://www.chromium.org/developers/coding-style), from |
| 7 the command line, simply run: ``` git cl format ``` This should work on all | 7 the command line, simply run: ``` git cl format ``` This should work on all |
| 8 platforms _(yes, even Windows)_ without any set up or configuration: the tool | 8 platforms _(yes, even Windows)_ without any set up or configuration: the tool |
| 9 comes with your checkout. Like other `git-cl` commands, this operates on a diff | 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 | 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 | 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 | 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 | 13 clang-format changed. Alternatively, you can run `git cl format` with your |
| 14 changes uncommitted, and then commit your now-formatted code. | 14 changes uncommitted, and then commit your now-formatted code. |
| 15 | 15 |
| 16 ## Editor integrations | 16 ## Editor integrations |
| 17 | 17 |
| 18 Many developers find it useful to integrate the clang-format tool with their | 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 | 19 editor of choice. As a convenience, the scripts for this are also available in |
| 20 your checkout of Chrome under | 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/). | 21 [src/buildtools/clang_format/script/](https://code.google.com/p/chromium/codesea
rch#chromium/src/buildtools/clang_format/script/). |
| 22 | 22 |
| 23 If you use an editor integration, you should try to make sure that you're using | 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 | 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 | 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 | 26 other developers. The binary lives under `src/buildtools`, but it's also in your |
| 27 path indirectly via a `depot_tools` launcher script: | 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) | 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` | 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 | 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 | 31 checkout, the editor scripts (which anticipate clang-format on the path) should |
| 32 work. | 32 work. |
| 33 | 33 |
| 34 For further guidance on editor integration, see these specific pages: | 34 For further guidance on editor integration, see these specific pages: |
| 35 | 35 |
| 36 * [Sublime Text](http://www.chromium.org/developers/sublime-text#TOC-Format-se
lection-or-area-around-cursor-using-clang-format) | 36 * [Sublime Text](https://www.chromium.org/developers/sublime-text#TOC-Format-s
election-or-area-around-cursor-using-clang-format) |
| 37 * [llvm's guidelines for vim, emacs, and bbedit](http://clang.llvm.org/docs/Cl
angFormat.html) | 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) | 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. | 39 ctrl-shift-i (elsewhere) to indent the current line or current selection. |
| 40 | 40 |
| 41 ## Are robots taking over my freedom to choose where newlines go? | 41 ## Are robots taking over my freedom to choose where newlines go? |
| 42 | 42 |
| 43 No. For the project as a whole, using clang-format is just one optional way to | 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 | 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. | 45 formattings would also satisfy the style guide, and all are okay. |
| 46 | 46 |
| 47 Having said that, many clang-format converts have found that relying on a tool | 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 | 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 | 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 | 50 concerns whose resolution can't be automated, or to do something else that |
| 51 matters. | 51 matters. |
| 52 | 52 |
| 53 In directories where most contributors have already adopted clang-format, and | 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 | 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 | 55 intend to experiment with standardizing on clang-format. When these local |
| 56 standards apply, it will be enforced by a PRESUBMIT.py check. | 56 standards apply, it will be enforced by a PRESUBMIT.py check. |
| 57 | 57 |
| 58 ## Reporting problems | 58 ## Reporting problems |
| 59 | 59 |
| 60 If clang-format is broken, or produces badly formatted code, please file a | 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 | 61 [bug]. Assign it to thakis@chromium.org or nick@chromium.org who will route it |
| 62 upstream. | 62 upstream. |
| 63 | 63 |
| 64 [bug]: | 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-? | 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 |