[PATCH v1] tools clang-format: Add a tools clang-format that overrides some kernel behaviors

[PATCH v1] tools clang-format: Add a tools clang-format that overrides some kernel behaviors

[Ian Rogers]

In particular, header file ordering is an issue in the tools/
directory given the larger number of depended upon libraries.

The order of header file includes was proposed in:
https://lore.kernel.org/linux-perf-users/CAP-5=fUitzKwJONTngiW17XkS7kVr2cDS4cDL_HccJKcnR2EgQ@mail.gmail.com/

Sorting headers is desirable to avoid issues like duplicate includes.

Signed-off-by: Ian Rogers <irogers@google.com>
---
 tools/.clang-format | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
 create mode 100644 tools/.clang-format

diff --git a/tools/.clang-format b/tools/.clang-format
new file mode 100644
index 000000000000..902b2f7456f6
--- /dev/null
+++ b/tools/.clang-format
@@ -0,0 +1,20 @@
+BasedOnStyle: InheritParentConfig
+SortIncludes: true
+IncludeBlocks: Regroup
+IncludeCategories:
+  # Implicitly the corresponding header for the C file has Priority 0
+  # C Standard Library Headers
+  - Regex:           '^<(assert|complex|ctype|errno|fenv|float|inttypes|iso646|limits|locale|math|setjmp|signal|stdalign|stdarg|stdatomic|stdbool|stddef|stdint|stdio|stdlib|stdnoreturn|string|tgmath|threads|time|uchar|wchar|wctype)\.h>'
+    Priority:        1
+  # OS/System-Specific Headers (directories)
+  - Regex:           '^<(sys|linux|asm|arpa|net|netinet|x86_64|machine)/.*>'
+    Priority:        2
+  # OS/System-Specific Headers (POSIX/System flat headers)
+  - Regex:           '^<(unistd|pthread|fcntl|dirent|dlfcn|poll|sched|semaphore|spawn|syslog|termios|pwd|grp|netdb|sysexits|err|paths|pty|utmp|resolv|ifaddrs|elf|libelf|gelf)\.h>'
+    Priority:        2
+  # Third-Party Library Headers
+  - Regex:           '^<.*>'
+    Priority:        3
+  # Your Project's Other Headers
+  - Regex:           '^".*"'
+    Priority:        4
-- 
2.53.0.1213.gd9a14994de-goog

Re: [PATCH v1] tools clang-format: Add a tools clang-format that overrides some kernel behaviors

[Joe Perches]

On Tue, 2026-04-07 at 09:55 -0700, Ian Rogers wrote:

> Sorting headers is desirable to avoid issues like duplicate includes.

Perhaps.

Some others prefer reverse-christmas-tree by length ordering for #includes
though I think it's poor style.

Re: [PATCH v1] tools clang-format: Add a tools clang-format that overrides some kernel behaviors

[Ian Rogers]

On Tue, Apr 7, 2026 at 10:11 AM Joe Perches <joe@perches.com> wrote:
>
> On Tue, 2026-04-07 at 09:55 -0700, Ian Rogers wrote:
>
> > Sorting headers is desirable to avoid issues like duplicate includes.
>
> Perhaps.
>
> Some others prefer reverse-christmas-tree by length ordering for #includes
> though I think it's poor style.

Thanks Joe. I second not switching to a reverse-christmas-tree style :-)

If this patch is okay, could we bring it in through the perf tree?
Namhyung/Arnaldo, are you okay with doing this? Being able to easily
`git clang-format` is useful for my work in perf, and the motivating
conversation occurred on linux-perf-users.

Thanks,
Ian

Re: [PATCH v1] tools clang-format: Add a tools clang-format that overrides some kernel behaviors

[Joe Perches]

On Mon, 2026-04-13 at 08:39 -0700, Ian Rogers wrote:
> On Tue, Apr 7, 2026 at 10:11 AM Joe Perches <[joe@perches.com](mailto:joe@perches.com)> wrote:
> > On Tue, 2026-04-07 at 09:55 -0700, Ian Rogers wrote:
> Sorting headers is desirable to avoid issues like duplicate includes.
> > Perhaps.
> > 
> > Some others prefer reverse-christmas-tree by length ordering for #includes
> > though I think it's poor style.
> 
> Thanks Joe. I second not switching to a reverse-christmas-tree style :-)
> 
> If this patch is okay, could we bring it in through the perf tree?

It's likely better to avoid this suggestion.

The issue is that others strongly prefer that reverse-christmas-tree
style and would object so nak.

Re: [PATCH v1] tools clang-format: Add a tools clang-format that overrides some kernel behaviors

[Ian Rogers]

On Mon, Apr 13, 2026 at 8:45 AM Joe Perches <joe@perches.com> wrote:
>
> On Mon, 2026-04-13 at 08:39 -0700, Ian Rogers wrote:
> > On Tue, Apr 7, 2026 at 10:11 AM Joe Perches <[joe@perches.com](mailto:joe@perches.com)> wrote:
> > > On Tue, 2026-04-07 at 09:55 -0700, Ian Rogers wrote:
> > Sorting headers is desirable to avoid issues like duplicate includes.
> > > Perhaps.
> > >
> > > Some others prefer reverse-christmas-tree by length ordering for #includes
> > > though I think it's poor style.
> >
> > Thanks Joe. I second not switching to a reverse-christmas-tree style :-)
> >
> > If this patch is okay, could we bring it in through the perf tree?
>
> It's likely better to avoid this suggestion.
>
> The issue is that others strongly prefer that reverse-christmas-tree
> style and would object so nak.

Presumably that is a kernel suggestion rather than a tools directory
suggestion. We can move the file into tools/perf, tools/lib/perf, etc.
if that removes more global concerns. perf hasn't adopted a
reverse-christmas-tree style.

Thanks,
Ian

Re: [PATCH v1] tools clang-format: Add a tools clang-format that overrides some kernel behaviors

[Miguel Ojeda]

On Tue, Apr 7, 2026 at 6:56 PM Ian Rogers <irogers@google.com> wrote:
>
> +BasedOnStyle: InheritParentConfig

I hope we see more of this (i.e. inheriting) elsewhere, since I think
it can help adoption :)

Acked-by: Miguel Ojeda <ojeda@kernel.org>

Thanks!

Cheers,
Miguel

Re: [PATCH v1] tools clang-format: Add a tools clang-format that overrides some kernel behaviors

[Joe Perches]

On Mon, 2026-04-13 at 09:19 -0700, Ian Rogers wrote:
> On Mon, Apr 13, 2026 at 8:45 AM Joe Perches <[joe@perches.com](mailto:joe@perches.com)> wrote:
> > On Mon, 2026-04-13 at 08:39 -0700, Ian Rogers wrote:
> On Tue, Apr 7, 2026 at 10:11 AM Joe Perches <[[joe@perches.com](mailto:joe@perches.com)](mailto:[joe@perches.com](mailto:joe@perches.com))> wrote:
> On Tue, 2026-04-07 at 09:55 -0700, Ian Rogers wrote:
> > > Sorting headers is desirable to avoid issues like duplicate includes.
> > > > Perhaps.
> > > > Some others prefer reverse-christmas-tree by length ordering for #includes
> > > > though I think it's poor style.
> > > Thanks Joe. I second not switching to a reverse-christmas-tree style :-)
> > > If this patch is okay, could we bring it in through the perf tree?
> > It's likely better to avoid this suggestion.
> > The issue is that others strongly prefer that reverse-christmas-tree
> > style and would object so nak.
> Presumably that is a kernel suggestion rather than a tools directory
> suggestion. We can move the file into tools/perf, tools/lib/perf, etc.
> if that removes more global concerns. perf hasn't adopted a
> reverse-christmas-tree style.

Fine by me.
Just curious: is this a style control file used by directory depth/path?

Re: [PATCH v1] tools clang-format: Add a tools clang-format that overrides some kernel behaviors

[Ian Rogers]

On Mon, Apr 13, 2026 at 9:54 AM Joe Perches <joe@perches.com> wrote:
>
> On Mon, 2026-04-13 at 09:19 -0700, Ian Rogers wrote:
> > On Mon, Apr 13, 2026 at 8:45 AM Joe Perches <[joe@perches.com](mailto:joe@perches.com)> wrote:
> > > On Mon, 2026-04-13 at 08:39 -0700, Ian Rogers wrote:
> > On Tue, Apr 7, 2026 at 10:11 AM Joe Perches <[[joe@perches.com](mailto:joe@perches.com)](mailto:[joe@perches.com](mailto:joe@perches.com))> wrote:
> > On Tue, 2026-04-07 at 09:55 -0700, Ian Rogers wrote:
> > > > Sorting headers is desirable to avoid issues like duplicate includes.
> > > > > Perhaps.
> > > > > Some others prefer reverse-christmas-tree by length ordering for #includes
> > > > > though I think it's poor style.
> > > > Thanks Joe. I second not switching to a reverse-christmas-tree style :-)
> > > > If this patch is okay, could we bring it in through the perf tree?
> > > It's likely better to avoid this suggestion.
> > > The issue is that others strongly prefer that reverse-christmas-tree
> > > style and would object so nak.
> > Presumably that is a kernel suggestion rather than a tools directory
> > suggestion. We can move the file into tools/perf, tools/lib/perf, etc.
> > if that removes more global concerns. perf hasn't adopted a
> > reverse-christmas-tree style.
>
> Fine by me.
> Just curious: is this a style control file used by directory depth/path?

clang-format searches from the directory containing the file to be
formatted upwards until it finds a .clang-format file. This change
places the style in tools/, which is my preferred location for
consistency across different tools and libraries. Header file ordering
is a different issue within the kernel tree because it generally only
references itself.

Thanks,
Ian

Re: [PATCH v1] tools clang-format: Add a tools clang-format that overrides some kernel behaviors

[Namhyung Kim]

On Mon, Apr 13, 2026 at 10:50:59AM -0700, Ian Rogers wrote:
> On Mon, Apr 13, 2026 at 9:54 AM Joe Perches <joe@perches.com> wrote:
> >
> > On Mon, 2026-04-13 at 09:19 -0700, Ian Rogers wrote:
> > > On Mon, Apr 13, 2026 at 8:45 AM Joe Perches <[joe@perches.com](mailto:joe@perches.com)> wrote:
> > > > On Mon, 2026-04-13 at 08:39 -0700, Ian Rogers wrote:
> > > On Tue, Apr 7, 2026 at 10:11 AM Joe Perches <[[joe@perches.com](mailto:joe@perches.com)](mailto:[joe@perches.com](mailto:joe@perches.com))> wrote:
> > > On Tue, 2026-04-07 at 09:55 -0700, Ian Rogers wrote:
> > > > > Sorting headers is desirable to avoid issues like duplicate includes.
> > > > > > Perhaps.
> > > > > > Some others prefer reverse-christmas-tree by length ordering for #includes
> > > > > > though I think it's poor style.
> > > > > Thanks Joe. I second not switching to a reverse-christmas-tree style :-)
> > > > > If this patch is okay, could we bring it in through the perf tree?
> > > > It's likely better to avoid this suggestion.
> > > > The issue is that others strongly prefer that reverse-christmas-tree
> > > > style and would object so nak.
> > > Presumably that is a kernel suggestion rather than a tools directory
> > > suggestion. We can move the file into tools/perf, tools/lib/perf, etc.
> > > if that removes more global concerns. perf hasn't adopted a
> > > reverse-christmas-tree style.
> >
> > Fine by me.
> > Just curious: is this a style control file used by directory depth/path?
> 
> clang-format searches from the directory containing the file to be
> formatted upwards until it finds a .clang-format file. This change
> places the style in tools/, which is my preferred location for
> consistency across different tools and libraries. Header file ordering
> is a different issue within the kernel tree because it generally only
> references itself.

I think we need confirmation from other folks in tools/ if we want to
put it there.

Thanks,
Namhyung