1. We are using clang-format.

1. We use the current stable release, with an eye to good new options coming from the next release. As of writing we're using release 10, the configuration options are documented here.

2. As mentioned in the style guide, the format style is based on Google C style guide, but mixed in with Postgres formatting rules (break before braces, 4-space tabbing, etc)

3. We should use an explicit, complete (locked down) specification for the .clang-format file.

4. But our intent is better expressed as well organized, commented yaml. We use a simple script to generate the complete config file from the intent file. For example, on my Linux laptop, I run:

   CLANG_FORMAT=clang-format-10 scripts/fmt gen

   If the correct version of clang-format is installed as clang-format (as is the case in macOS), you can omit the environment variable override.

5. To check for formatting conformance, one can run

   scripts/fmt chk

   It will succeed quietly (with return code 0) or point out the first few places that need to be formatted.

6. To wholesale format all of ORCA and GPOPT

   scripts/fmt fmt

   On my laptop this takes about 2.5 seconds.

7. Of course, when you're writing code, 2.5 seconds is an eternity. Here's a non-exhaustive list of editor / IDE plugins that provide an integrated formatting experience. The in-editor formatting typically takes around 50ms. Depending on your plugin / editor, the formatting either happens automatically as you type, on save, or when you invoke it explicitly.

   • LLVM's official Emacs integration provides the clang-format-region macro.
   • Vim integration as documented by the official LLVM project
   • A community VIM plugin that looks promising and claims to be better than the official VIM integration
   • Clion detects .clang-format automatically and switches to using it for the built-in "Reformat Code" and "Reformat File...".
   • Similar to CLion, Visual Studio Code has it built in.
   • Plugin for Xcode 8

1. It's usually desirable to skip past formatting commits when doing a git blame. Fortunately, git blame has two options that are extremely helpful:
   1. -w ignore whitespace
   2. --ignore-rev / --ignore-revs-file accepts commits to skip while annotating

When combined, -w --ignore-revs-file produces a perfectly clean annotation, unencumbered by a noisy history. This also gives us a peace of mind in changing our formats more frequently without worrying about hindering the git blame experience, rather than "do it once, set it in stone, and forget about it".

ORCA is actively developed, that means when the "big bang" formatting change is merged, there will inevitably be a number of patches that were started well before the formatting change, and these patches will now need to conform to the new format. The following steps are used to convert in-flight branches to the new format.

1. Get the format script

   git restore --source master -- scripts/fmt

2. Get the format configuration files

   git restore --source master -- src/include/gpopt/.clang-format src/backend/gpopt/.clang-format src/backend/gporca/.clang-format

3. Use git filter-branch to rewrite the branch history

   git filter-branch --tree-filter 'scripts/fmt fmt' master..

4. Now that we have reformatted the history, rebase on top of master

   git rebase master