Skip to content

Commit d0f501c

Browse files
rwgkrwgk
committed
docs: simplify filtered clone instructions
— codex GPT-6 on behalf of Ralf — Use Git's native submodule filtering in each clone example and retain the ordinary update instructions. Preserve full commit history and release tags while keeping the filtered recipe directly visible to users and agents. Signed-off-by: Ralf W. Grosse-Kunstleve <[email protected]>
1 parent 5a37bd6 commit d0f501c

3 files changed

Lines changed: 27 additions & 41 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 14 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -69,27 +69,26 @@ ran and any validation gaps.
6969
including the Developer Mode registry check.** Complete that setup before
7070
running the clone command.
7171

72-
From the directory where you want to create the checkout, run:
72+
With Git 2.36 or newer, run this from the directory where you want to
73+
create the checkout:
7374

7475
```console
75-
$ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git
76+
$ 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
7677
$ cd cuda-python
77-
$ git submodule update --init --depth=1 --filter=blob:none --recursive
7878
```
7979

8080
This recipe sets up the repository for source builds and development:
8181

8282
- `core.symlinks=true` materializes symlinks during checkout, including the
8383
build-critical `cuda_core/_build_shared.py`.
84-
- The separate submodule update initializes the pinned CCCL headers needed to
85-
build `cuda.core`, fetching only one commit of submodule history.
86-
- `--filter=blob:none` skips historical file contents in both repositories.
87-
Git downloads file contents as needed for checkout.
84+
- `--recurse-submodules` initializes the CCCL headers needed to build `cuda.core`.
85+
- `--filter=blob:none --also-filter-submodules` skips historical file
86+
contents in the repository and CCCL. Git downloads those contents
87+
when needed; commit history and release tags remain available.
8888
- `submodule.recurse=true` keeps initialized submodules in sync on `git pull`,
8989
`git checkout`, and `git switch`.
90-
- The root clone retains history and release tags for correct package versions.
91-
Do not add `--depth` or `--no-tags` to `git clone`; the depth limit applies
92-
only to submodules.
90+
- The clone retains history and release tags for correct package versions.
91+
Do not add `--depth` or `--no-tags`.
9392

9493
Both configuration settings are stored in the new clone. Next, follow the
9594
build and test instructions for
@@ -102,15 +101,13 @@ build and test instructions for
102101
From the repository root, run:
103102

104103
```console
105-
$ git pull --no-recurse-submodules
106-
$ git submodule sync --recursive
107-
$ git submodule update --init --depth=1 --filter=blob:none --recursive
104+
$ git pull --recurse-submodules
105+
$ git submodule update --init
108106
```
109107

110-
Pull the root repository first, then sync submodule URLs and update the pinned
111-
revisions, including any newly added submodules. The explicit
112-
`--no-recurse-submodules` overrides `submodule.recurse=true` for the pull so
113-
submodules are fetched separately with the requested depth and filter.
108+
The recommended clone configures `submodule.recurse=true`, so you can omit
109+
`--recurse-submodules` from `git pull`. The second command initializes any
110+
newly added submodules; it is usually a no-op.
114111

115112
If you work from a fork, periodically fetch release tags from NVIDIA upstream
116113
so package versions stay current:

‎cuda_core/docs/source/install.rst‎

Lines changed: 9 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -130,29 +130,24 @@ recipe below. On native Windows outside WSL, complete its Windows setup
130130

131131
.. code-block:: console
132132
133-
$ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git
134-
$ cd cuda-python
135-
$ git submodule update --init --depth=1 --filter=blob:none --recursive
136-
$ cd cuda_core
133+
$ 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
134+
$ cd cuda-python/cuda_core
137135
$ pip install .
138136
139137
.. note::
140138

141-
The submodule update is required: the build compiles against the CCCL
139+
``--recurse-submodules`` is required: the build compiles against the CCCL
142140
headers pinned in the ``cuda_core/third_party/cccl`` submodule, and fails
143141
without them. For a clone that already exists, run the following from the
144142
repository root:
145-
``git submodule update --init --depth=1 --filter=blob:none --recursive``.
146-
Only the submodule history is shallow; the root clone retains its history
147-
and release tags.
143+
``git submodule update --init cuda_core/third_party/cccl``.
148144

149145
.. note::
150146

151147
The version is derived from git tags via ``setuptools-scm``, so the clone
152148
must include tags reaching back to at least the latest ``cuda-core-v*`` tag.
153-
Do not add ``--depth`` or ``--no-tags`` to ``git clone``: a shallow root
154-
clone builds without error but produces a bogus version such as
155-
``0.1.dev1+g0d22cb444``. See
149+
Do not use ``--depth`` or ``--no-tags``: a shallow clone builds without
150+
error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See
156151
`Cloning the repository
157152
<https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md>`_
158153
for details.
@@ -166,10 +161,8 @@ For example, to work on ``cuda-core`` against CUDA 13:
166161

167162
.. code-block:: console
168163
169-
$ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git
170-
$ cd cuda-python
171-
$ git submodule update --init --depth=1 --filter=blob:none --recursive
172-
$ cd cuda_core
164+
$ 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
165+
$ cd cuda-python/cuda_core
173166
$ uv venv
174167
$ source .venv/bin/activate # On Windows: .venv\Scripts\activate
175168
$ uv pip install -e .[cu13] --group test
@@ -191,9 +184,8 @@ For example, to work against CUDA 13:
191184

192185
.. code-block:: console
193186
194-
$ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git
187+
$ 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
195188
$ cd cuda-python
196-
$ git submodule update --init --depth=1 --filter=blob:none --recursive
197189
$ pixi run -e cu13 test-core
198190
199191
To run all repository tests (pathfinder → bindings → core):

‎cuda_pathfinder/docs/source/install.rst‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -64,10 +64,8 @@ before cloning.
6464

6565
.. code-block:: console
6666
67-
$ git clone --config core.symlinks=true --config submodule.recurse=true --filter=blob:none https://github.com/NVIDIA/cuda-python.git
68-
$ cd cuda-python
69-
$ git submodule update --init --depth=1 --filter=blob:none --recursive
70-
$ cd cuda_pathfinder
67+
$ 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
68+
$ cd cuda-python/cuda_pathfinder
7169
$ pip install .
7270
7371
For an editable install (e.g. when developing ``cuda.pathfinder`` itself):
@@ -80,9 +78,8 @@ For an editable install (e.g. when developing ``cuda.pathfinder`` itself):
8078

8179
The version is derived from git tags via ``setuptools-scm``, so the clone
8280
must include tags reaching back to at least the latest ``cuda-pathfinder-v*``
83-
tag. Do not add ``--depth`` or ``--no-tags`` to ``git clone``: a shallow root
84-
clone builds without error but produces a bogus version such as
85-
``0.1.dev1+g0d22cb444``. See
81+
tag. Do not use ``--depth`` or ``--no-tags``: a shallow clone builds without
82+
error but produces a bogus version such as ``0.1.dev1+g0d22cb444``. See
8683
`Cloning the repository
8784
<https://github.com/NVIDIA/cuda-python/blob/main/CONTRIBUTING.md>`_
8885
for details.

0 commit comments

Comments
 (0)