Looks like clang/docs/tools/clang-formatted-files.txt is essentially an unused file that was generated by a script and committed a while back. It has an incomplete list of source file in the git repo, and is updated mostly as a part of other changes that add/remove/rename files (but not consistently).
I have a PR to delete it but there are some concerns whether it’s really unused. @mydeveloperday or others, can you comment if it’s safe to delete. If so, we can delete it and avoid having to update that file unnecessarily.
This is related, but not 100% relevant to the file in question, but I find that gitattributes are far better to control these kinds of things. I wrote a tool that does format enforcement based on that. The issue with doing this during the build is that clang-format is not stable with a given configuration between versions. So it may succeed on a machine using clang-format-14 but fail when building with clang-format-15 (or vice versa). Instead, we perform the checking as part of automated review and offer a way to run the reformat action to rewrite code to conform to the expected formatting. This way CI can expect a specific version of the formatter and not have such version skew issues. It knows which files to enforce based on gitattributes set on the files in question.
I really need to get the blog post about this reformatting tool published…
Right, this is unrelated to automated clang-formatting. This file is the output of clang/docs/tools/generate_formatted_state.py. Looking more closely, this and clang/docs/ClangFormattedStatus.rst are snapshots of clang-format conformance of files within the LLVM repo. These files are generated by the script above and have been updated > 2 years ago.
The issue is that anyone else who is adding/removing or renaming files inadvertently ends up updating the file, which is extra unnecessary work. I don’t think these files are intended to be kept up-to-date as new files are added or removed. In fact, I’d argue that do not belong as checked-in artifacts to the repo. @mydeveloperday can you comment on the intended use of these files and why they should stay in the repo? The RST file also does not format correctly: llvm-project/clang/docs/ClangFormattedStatus.rst at main · llvm/llvm-project
I propose we delete these 2 files from the repo as they are script generated. I don’t know if there is any value is keeping a 2-year-old snapshot of the clang-format conformance status of various files in the LLVM git repo, given that folks have been unnecessarily updating these files for no good reason.
Thanks. I’ll update my PR to delete the generated RST as well.
+1 to removing the file
The recommended practice in clang / LLVM is to use git clang-format so that new/modified code is properly formatted. We avoid changing the formatting of the codebase wholesale as this is disruptive without much benefit. we disable formatting in specific sub-trees with .clang-format
