clang_format.md

Using clang-format on Chromium C++ Code

[TOC]

*** note NOTE: This page does not apply to the Chromium OS project. See Chromium Issue 878506 for updates.

---

Easiest usage, from the command line

To automatically format a pending patch according to Chromium style, run: git cl format from the command line. This should work on all platforms without any extra set up: the tool is integrated with depot_tools and the Chromium checkout.

Like other git-cl commands, this operates on a diff relative to the upstream branch. Only the lines that changed in a CL will be reformatted. To see what clang-format would choose, commit any local changes and then run git cl format followed by git diff. Alternatively, run git cl format and commit the now-formatted code.

Editor integrations

Many developers find it useful to integrate the clang-format tool with their editor of choice. As a convenience, the scripts for this are also available in your checkout of Chrome under src/buildtools/clang_format/script/.

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 automatically 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: clang-format (clang-format.bat 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.

For further guidance on editor integration, see these specific pages:

• Sublime Text
• llvm's guidelines for vim, emacs, and bbedit
• For vim, :so tools/vim/clang-format.vim and then hit cmd-shift-i (mac) ctrl-shift-i (elsewhere) to indent the current line or current selection.

Reporting problems

If clang-format is broken, or produces badly formatted code, please file a bug. Assign it to thakis@chromium.org or dcheng@chromium.org, who will route it upstream.

Are robots taking over my freedom to choose where newlines go?

Mostly. At upload time, a presubmit check warns if a CL is not clang-formatted, but this is a non-blocking warning, and the CL may still be submitted. Even so, try to prefer clang-format's output when possible:

• While clang-format does not necessarily format code the exact same way a human might choose, it produces style-conformat code by design. This can allow development and review time to be focused on discovering functional defects, addressing readability/understandability concerns that can't be automatically fixed by tooling, et cetera.
• Continually fighting the tooling is a losing battle. Most Chromium developers use clang-format. Large-scale changes will simply run git cl format once to avoid having to deal with the particulars of formatting. Over time, this will likely undo any carefully-curated manual formatting of the affected lines.

There is one notable exception where clang-format is often disabled: large tables of data are often surrounded by // clang-format off and // clang-format on. Try to use this option sparingly, as widespread usage makes tool-assisted refactoring more difficult.

Again, if clang-format produces something odd, please err on the side of reporting an issue: bugs that aren't reported can't be fixed.