Invariant layout between clang-format versions?

Dear Clang Developers,

this may not be the right place to ask this question so please redirect me if I’m mistaken.

We are using clang-format for automatic code layout within our project.
A problem we are facing is that developers have different versions of clang-format installed.
Even with identical style configuration this results in different output, leading to unnecessary diffs.

While this can be fixed by mandating a specific clang-format version, this may not be practical.
It would be helpful if one could pin a particular layout behavior in a forwards compatible way.

If that is not possible, it would be nice to know when version changes result in layout changes.
E.g. should we mandate version 5.0.0 or is 5.0.x or even 5.x enough?

Thanks in advance.

Kind regards,

Pim Schellart

I have the issue as well, I used to have a clang-format checker on my CI builds, but this was annoying as my clang version updates more often than the one on CI, leading to inconsistencies and thus failed builds.

I don’t think there is a useful way of doing this. If you want developers to get the same layout, they have to use the same version of the tool. You can assume that every single version change leads to a different layout somewhere, or else we wouldn’t be making the change. Often these changes affect a rare corner case of the syntax, but in a reasonably large codebase, they are still always triggered. Is it impractical to ship the same version of clang-format to all contributors? clang-format is reasonably small and you could just check in the version that the CI uses into your repository for everyone to use. That also enables you to update that version together with the formatting changes that it entails.

However, I would also argue that a format check on CI builds is not useful. The polly project inside LLVM does that and it seems rather painful. Instead, verify that the changed version of a file adheres to what clang-format produces at the time the change is submitted. This is what Chromium and other large projects do and has proven to be effective. Then, even if the versions differ a bit, there won’t be unnecessary churn as a formatting change is always bundled with an actually code change.

I don't think there is a useful way of doing this. If you want developers
to get the same layout, they have to use the same version of the tool. You
can assume that every single version change leads to a different layout
somewhere, or else we wouldn't be making the change. Often these changes
affect a rare corner case of the syntax, but in a reasonably large
codebase, they are still always triggered. Is it impractical to ship the
same version of clang-format to all contributors? clang-format is
reasonably small and you could just check in the version that the CI uses
into your repository for everyone to use. That also enables you to update
that version together with the formatting changes that it entails.

However, I would also argue that a format check on CI builds is not
useful. The polly project inside LLVM does that and it seems rather
painful. Instead, verify that the changed version of a file adheres to what
clang-format produces at the time the change is submitted. This is what
Chromium and other large projects do and has proven to be effective. Then,
even if the versions differ a bit, there won't be unnecessary churn as a
formatting change is always bundled with an actually code change.

To add some more detail: We run `git diff -U0` to get a diff of the current
branch with trunk and then pipe that into clang-format-diff.py -i from the
LLVM tree, which then formats only the bits of each file that have been
modified.

In a presubmit, we do the same thing (without -i) and check
that clang-format-diff.py produces no output.