Using clang-format on Chromium C++ Code

Easiest usage, from the command line

To automatically format a pending patch according toChromium 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 othergit-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 rungit cl format followed bygit diff. Alternatively, rungit 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 undersrc/third_party/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 undersrc/buildtools, but it‘s also in your path indirectly via adepot_tools launcher script:clang-format (clang-format.bat on Windows). Assuming thatdepot_tools is in your editor’sPATH 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
• Visual Studio Code
• 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 abug. Assign it tothakis@chromium.org ordcheng@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 rungit 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 ofreporting an issue: bugs that aren‘t reported can’t be fixed.