CI: use shallow, blob-filtered CCCL submodule checkouts

.github/workflows/build-wheel.yml

@@ -72,8 +72,13 @@ jobs:
           # but not historical blobs.
           fetch-depth: 0
           filter: blob:none
-          # third_party/cccl provides the CCCL headers cuda.core compiles against.
-          submodules: true
+          # Fetch CCCL separately: checkout's filter does not apply to submodules.
+          submodules: false
+
+      - name: Checkout CCCL submodule
+        run: |
+          git submodule sync --recursive
+          git submodule update --init --force --depth=1 --filter=blob:none --recursive
 
       - name: Register problem matchers
         # Compiler and Cython errors from the wheel builds become annotations

.github/workflows/ci-pixi-source-test.yml

@@ -88,8 +88,13 @@ jobs:
           # cuda.core's "cuda.bindings 12.x or 13.x must be installed" guard.
           fetch-depth: 0
           filter: blob:none
-          # third_party/cccl provides the CCCL headers cuda.core compiles against.
-          submodules: true
+          # Fetch CCCL separately: checkout's filter does not apply to submodules.
+          submodules: false
+
+      - name: Checkout CCCL submodule
+        run: |
+          git submodule sync --recursive
+          git submodule update --init --force --depth=1 --filter=blob:none --recursive
 
       - name: Setup pixi
         uses: ./.github/actions/setup-pixi
@@ -147,8 +152,13 @@ jobs:
           # cuda.core's "cuda.bindings 12.x or 13.x must be installed" guard.
           fetch-depth: 0
           filter: blob:none
-          # third_party/cccl provides the CCCL headers cuda.core compiles against.
-          submodules: true
+          # Fetch CCCL separately: checkout's filter does not apply to submodules.
+          submodules: false
+
+      - name: Checkout CCCL submodule
+        run: |
+          git submodule sync --recursive
+          git submodule update --init --force --depth=1 --filter=blob:none --recursive
 
       - name: Setup pixi
         uses: ./.github/actions/setup-pixi
@@ -215,8 +225,13 @@ jobs:
           # cuda.core's "cuda.bindings 12.x or 13.x must be installed" guard.
           fetch-depth: 0
           filter: blob:none
-          # third_party/cccl provides the CCCL headers cuda.core compiles against.
-          submodules: true
+          # Fetch CCCL separately: checkout's filter does not apply to submodules.
+          submodules: false
+
+      - name: Checkout CCCL submodule
+        run: |
+          git submodule sync --recursive
+          git submodule update --init --force --depth=1 --filter=blob:none --recursive
 
       - name: Setup proxy cache
         uses: nv-gha-runners/setup-proxy-cache@main

.github/workflows/coverage.yml

@@ -71,8 +71,13 @@ jobs:
           # but not historical blobs.
           fetch-depth: 0
           filter: blob:none
-          # third_party/cccl provides the CCCL headers cuda.core compiles against.
-          submodules: true
+          # Fetch CCCL separately: checkout's filter does not apply to submodules.
+          submodules: false
+
+      - name: Checkout CCCL submodule
+        run: |
+          git submodule sync --recursive
+          git submodule update --init --force --depth=1 --filter=blob:none --recursive
 
       - name: Fix workspace ownership
         run: |
@@ -238,8 +243,13 @@ jobs:
           # but not historical blobs.
           fetch-depth: 0
           filter: blob:none
-          # third_party/cccl provides the CCCL headers cuda.core compiles against.
-          submodules: true
+          # Fetch CCCL separately: checkout's filter does not apply to submodules.
+          submodules: false
+
+      - name: Checkout CCCL submodule
+        run: |
+          git submodule sync --recursive
+          git submodule update --init --force --depth=1 --filter=blob:none --recursive
 
       - name: Set up Python
         uses: $/.github/actions/setup-hardened-python

.github/workflows/lychee.yml

@@ -63,8 +63,14 @@ jobs:
           # Keep SCM history/tags without downloading historical source blobs.
           filter: blob:none
           persist-credentials: false
-          # Rendered docs build cuda.core against the pinned CCCL headers.
-          submodules: ${{ matrix.kind == 'rendered' }}
+          # Fetch CCCL separately: checkout's filter does not apply to submodules.
+          submodules: false
+
+      - name: Checkout CCCL submodule
+        if: ${{ matrix.kind == 'rendered' }}
+        run: |
+          git submodule sync --recursive
+          git submodule update --init --force --depth=1 --filter=blob:none --recursive
 
       - name: Set up Python
         id: python

.github/workflows/test-sdist-linux.yml

@@ -47,7 +47,13 @@ jobs:
           # the commit graph (`git describe`) but not historical blobs.
           fetch-depth: 0
           filter: blob:none
-          submodules: true
+          # Fetch CCCL separately: checkout's filter does not apply to submodules.
+          submodules: false
+
+      - name: Checkout CCCL submodule
+        run: |
+          git submodule sync --recursive
+          git submodule update --init --force --depth=1 --filter=blob:none --recursive
 
       - name: Set up Python
         uses: ./.github/actions/setup-hardened-python

.github/workflows/test-sdist-windows.yml

@@ -56,7 +56,13 @@ jobs:
           # the commit graph (`git describe`) but not historical blobs.
           fetch-depth: 0
           filter: blob:none
-          submodules: true
+          # Fetch CCCL separately: checkout's filter does not apply to submodules.
+          submodules: false
+
+      - name: Checkout CCCL submodule
+        run: |
+          git submodule sync --recursive
+          git submodule update --init --force --depth=1 --filter=blob:none --recursive
 
       - name: Set up Python
         uses: ./.github/actions/setup-hardened-python

CONTRIBUTING.md

@@ -69,10 +69,11 @@ ran and any validation gaps.
 including the Developer Mode registry check.** Complete that setup before
 running the clone command.
 
-From the directory where you want to create the checkout, run:
+With Git 2.36 or newer, run this from the directory where you want to
+create the checkout:
 
 ```console
-$ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules https://github.com/NVIDIA/cuda-python.git
+$ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules --filter=blob:none --also-filter-submodules https://github.com/NVIDIA/cuda-python.git
 $ cd cuda-python
 ```
 
@@ -81,6 +82,9 @@ This recipe sets up the repository for source builds and development:
 - `core.symlinks=true` materializes symlinks during checkout, including the
   build-critical `cuda_core/_build_shared.py`.
 - `--recurse-submodules` initializes the CCCL headers needed to build `cuda.core`.
+- `--filter=blob:none --also-filter-submodules` skips historical file
+  contents in the repository and CCCL. Git downloads those contents
+  when needed; commit history and release tags remain available.
 - `submodule.recurse=true` keeps initialized submodules in sync on `git pull`,
   `git checkout`, and `git switch`.
 - The clone retains history and release tags for correct package versions.

ci/README.md

@@ -24,6 +24,25 @@ The pinned checkout action's
 [`README`](https://github.com/actions/checkout/blob/3d3c42e5aac5ba805825da76410c181273ba90b1/README.md#fetch-all-history-for-all-tags-and-branches)
 documents `fetch-depth: 0` for fetching all history, branches, and tags.
 
+## CCCL Submodule Checkout
+
+Jobs that build `cuda.core` fetch its pinned CCCL headers in a separate step:
+set `submodules: false` on `actions/checkout`, then run:
+
+```bash
+git submodule sync --recursive
+git submodule update --init --force --depth=1 --filter=blob:none --recursive
+```
+
+The checkout action's `filter` input applies only to the root repository, so
+letting it fetch submodules downloads CCCL's unfiltered history. The separate
+step limits submodule history to one commit and skips historical blobs, while
+checking out the exact revision pinned by the root repository. Syncing URLs
+and forcing checkout preserve the action's behavior on reused workspaces.
+Keep `fetch-depth: 0` and `filter: blob:none` on the root checkout: package
+versioning still needs its complete ancestry and release tags. See
+[issue #3351](https://github.com/NVIDIA/cuda-python/issues/3351).
+
 ## Documentation Link Checks
 
 Two pre-commit hooks check links with one pinned native wheel (`lychee-bin`,

cuda_core/docs/source/install.rst

@@ -130,7 +130,7 @@ recipe below. On native Windows outside WSL, complete its Windows setup
 
 .. code-block:: console
 
-   $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules https://github.com/NVIDIA/cuda-python.git
+   $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules --filter=blob:none --also-filter-submodules https://github.com/NVIDIA/cuda-python.git
    $ cd cuda-python/cuda_core
    $ pip install .
 
@@ -161,7 +161,7 @@ For example, to work on ``cuda-core`` against CUDA 13:
 
 .. code-block:: console
 
-   $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules https://github.com/NVIDIA/cuda-python.git
+   $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules --filter=blob:none --also-filter-submodules https://github.com/NVIDIA/cuda-python.git
    $ cd cuda-python/cuda_core
    $ uv venv
    $ source .venv/bin/activate   # On Windows: .venv\Scripts\activate
@@ -184,7 +184,7 @@ For example, to work against CUDA 13:
 
 .. code-block:: console
 
-   $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules https://github.com/NVIDIA/cuda-python.git
+   $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules --filter=blob:none --also-filter-submodules https://github.com/NVIDIA/cuda-python.git
    $ cd cuda-python
    $ pixi run -e cu13 test-core
 

cuda_pathfinder/docs/source/install.rst

@@ -64,7 +64,7 @@ before cloning.
 
 .. code-block:: console
 
-   $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules https://github.com/NVIDIA/cuda-python.git
+   $ git clone --config core.symlinks=true --config submodule.recurse=true --recurse-submodules --filter=blob:none --also-filter-submodules https://github.com/NVIDIA/cuda-python.git
    $ cd cuda-python/cuda_pathfinder
    $ pip install .