How to exclude CMake generated project files from Git

I have a CMake project and I would like to exclude the generated project files from version control.

From my understanding there is no way to force CMake to use a certain build directory. The user can specify any directory they want and therefore I cant exclude it in my .gitignore. Usually the user would place it in a directory called build inside the source directory and I would put that in .gitignore. But I had the crazy idea to call it meta_build, which led me to this problem. Also, an inexperienced user might do an in-source build. It's just a matter of time until someone accidentally checks in the generated project files.

Any ideas or workarounds for this matter are much appreciated.

There are a few options to handle this:

Educate your users. Document clearly that generated build files should not be committed, and that an out-of-source build is recommended. This is not a technical solution but can be effective.

Use a pre-commit hook to check for generated files. You can write a script to run on pre-commit to check for common build file names and warn the user. They would still have to manually remove the files, but it alerts them to the issue.

Use CMake's EXCLUDE_FROM_ALL target property. You can mark the target that generates the build files as EXCLUDE_FROM_ALL, meaning it will not be built by default. Users would have to explicitly build that target to generate the build files. This makes it less likely they will be accidentally committed.

Generate the build files in a subdirectory. Have your top-level CMakeLists.txt generate the build files in a build_files subdirectory. Then you can add build_files/ to .gitignore. Users would have to run CMake from build_files for an in-source build, making it clear that directory should be ignored.

Consider not generating project files at all. If you build and distribute a binary library, you could provide just a CMakeLists.txt for people to link against the library. No project files are generated that could be accidentally committed. Of course, this doesn't work if you need project files to actually build your project!

I assume this is an issue for you because those other users are collaborating on the project and also potentially pushing to a shared remote. In that case, you have options:

• Set a convention for only building to a subdirectory with a common name. For example, The PitchFork Layout's build/. I personally put all my builds in a out/build/<build_name> directory. Then you can just gitignore that one directory.

• Allow your collaborating users to put build anywhere they want in their local clone, and in order to avoid arbitrary explosion of the gitignore, tell them to use their $XDG_CONFIG_HOME/git/ignore, or the local clone's $GIT_DIR/info/exclude (docs).

• You can hint users to use a particular build directory name(s) using presets: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html (see the binaryDir property for configuration presets).

• Technically you can write the gitignore on a filename basis independent of where the build directory is (Ex. listing out individually *.exe, etc.), but that sounds like a real pain in the butt- especially given that different buildsystem generators will have different build artifacts and specific buildsystem configuration files, and that different platforms have different prefixes and suffixes for target output file names (see for example CMAKE_EXECUTABLE_SUFFIX).