docs/clang_format.md

   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
   6 [Chromium style](http://www.chromium.org/developers/coding-style), from
   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
   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.
  15
  16 ## Editor integrations
  17
  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/codesearch#chromium/src/buildtools/clang_format/script/).
  22
  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/depot_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 your 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.
  33
  34 For further guidance on editor integration, see these specific pages:
  35
  36 *   [Sublime Text](http://www.chromium.org/developers/sublime-text#TOC-Format-selection-or-area-around-cursor-using-clang-format)
  37 *   [llvm's guidelines for vim, emacs, and bbedit](http://clang.llvm.org/docs/ClangFormat.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.
  40
  41 ## Are robots taking over my freedom to choose where newlines go?
  42
  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.
  46
  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.
  52
  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.
  57
  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%20Chromium%20style%0A-%20Doesn%27t%20match%20blink%20style%0A-%20Riles%20my%20finely%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%0ACode%20review%20link%20for%20full%20files/context:&summary=clang-format%20quality%20problem&cc=thakis@chromium.org,%20nick@chromium.org&labels=Type-Bug,Build-Tools,OS-?