FetchContent default shallow clone depth and tag propagation

Answer

By default, FetchContent_Declare performs a git clone with --depth 1, which is a shallow repository containing only the latest commit of the requested branch. Because a shallow clone does not download other refs, remote tags are not present unless shallow cloning is disabled.

Confirmed facts

• The default behavior can be verified with git rev-parse --is-shallow-repo returning true inside the fetched source tree.
• git tag -l returns no output under the default shallow clone.
• Setting the GIT_SHALLOW property to FALSE (or omitting it) forces a full clone, after which git tag -l lists tags and git rev-parse --is-shallow-repo returns false.

How to control shallow depth and tag propagation

• To change the depth for all subsequent declarations, set the variable FETCHCONTENT_GIT_SHALLOW before any FetchContent_Declare call, e.g. set(FETCHCONTENT_GIT_SHALLOW FALSE). This acts as a global default unless overridden per‑declaration.
• For a single declaration, include the property directly: FetchContent_Declare(mylib GIT_REPOSITORY ... GIT_SHALLOW FALSE).
• Tag propagation follows the same rule: when GIT_SHALLOW is FALSE, a full clone fetches all refs, including tags. You can also explicitly set GIT_TAG (or FETCHCONTENT_GIT_TAG) to request a specific tag; the variable is inherited in the same way as GIT_SHALLOW.
• Nested FetchContent calls inherit these variables from the parent scope unless they reset them. Therefore, placing set(FETCHCONTENT_GIT_SHALLOW FALSE) and/or set(FETCHCONTENT_GIT_TAG "v1.2.3") in the top‑level CMakeLists.txt ensures that subprojects automatically use the same settings.

Backward compatibility considerations

If CMake were to introduce an explicit default shallow depth (e.g., --depth 1) as a documented option, the functional behavior would remain unchanged because the current implementation already uses a depth‑1 shallow clone by default. Projects that rely on a full clone or on tags must already override GIT_SHALLOW to FALSE; adding a default would not affect them. Only a change to a different depth (e.g., --depth 2) would alter tag availability and could break version‑checking steps, requiring those projects to adjust their GIT_SHALLOW setting.

Verification steps (optional)

1. Create a minimal CMake project that calls FetchContent_Declare for a public repo (e.g., googletest).
2. After configuration, run git -C ${FETCHCONTENT_BASE_DIR}/googletest-src rev-parse --is-shallow-repo; expect true.
3. Run git -C ${FETCHCONTENT_BASE_DIR}/googletest-src tag -l; expect no output.
4. Re‑configure with set(FETCHCONTENT_GIT_SHALLOW FALSE) before the declaration, then repeat the two git commands; the shallow check should be false and tags should appear.

If you need to know whether your CI workflow requires tags for version checks, let me know so I can advise whether to keep the shallow clone or disable it.