Branch cleanup

[mdboom]

We should try to reduce the number of branches in the main fork of the project.

copy-pr-bot

Branches of the form pull-request/XXXX come from copy-pr-bot. This is a necessary part of the security of our CI, so we need to keep these around and live with the noise.

Coding-agent-created branches

Some users' coding agents seem to be creating branches on the main fork.

These ones have an open PR associated with them. Deleting them immediately would invalidate those PRs. We can just wait until these PRs are naturally merged or closed.

Author	Branch	PR	Title
@kkraus14	codex/docs-pyobj-reference-fixes	#2167	[codex] Regenerate CUDA bindings docs references
@kkraus14	codex/fix-cuda-bindings-problematic-doc-anchors	#2186	[codex] Fix generated cuda-bindings problematic doc anchors
@kkraus14	cursor/env-setup-830c	#2071	Add Cursor Cloud specific instructions to AGENTS.md
@rwgk	check-release-notes_with_backport-git-tag	#2161	[no-ci] Fix backport release checks and add release dry-run
@rwgk	rwgk/stacked/pathfinder/utils_driver_and_toolkit_info	#2012	pathfinder: add toolkit-info parser and display-driver release helpers

These branches do not have an open PR associated with them. They should be deleted if no longer required.

Author	Branch
@rparolin	cursor/cloud-dev-env-docs-d4d7
@kkraus14	codex/fix-build-docs-pixi

We should

• [no-ci] docs: instruct agents to use personal fork, not upstream, for PRs #2191 Add instructions to AGENTS.md to never do this
• Each user should set upstream to read-only in their own checkout:

git remote set-url upstream --push "Don't push to me"

Other random branches

I think these were temporary experiments.

@leofang | ci/sanitizer-restrict-cuda13

Branch protection rules

• Set up rules so that new branches (other than the ones required by our bots) can not be created

[rwgk]

Mostly generated with Cursor GPT-5.5

---

I looked at this issue from the angle of reducing git clone times.

My read is: cleaning up stale branches is good repository hygiene and will reduce ref noise, but most of the branches listed here are unlikely to materially improve full clone runtimes if deleted.

For a normal full clone, Git fetches all advertised branch heads from the remote, so branches can affect clone time when they make otherwise-unreachable objects reachable. In other words, deleting a branch helps clone size/runtime only to the extent that the branch points to commits, trees, or blobs that are not already reachable from another retained ref such as main, release branches, tags, or bot branches.

I checked the current upstream refs from a local checkout of NVIDIA/cuda-python:

• Upstream currently advertises 36 branch heads.
• 16 of those are pull-request/* branches.
• Objects reachable from upstream branches but not from upstream/main account for about 1.17 GiB.
• The pull-request/* branches account for only about 1.4 MiB beyond upstream/main.
• The agent-created / temporary branches listed in this issue are small, mostly KB-scale and under 1 MiB each.

The large outliers are:

• gh-pages: about 1.17 GiB beyond upstream/main
• gh-pages-dry-run: about 1.09 GiB beyond upstream/main

For comparison, the branches called out in this issue were approximately:

• codex/docs-pyobj-reference-fixes: 792 KiB
• codex/fix-cuda-bindings-problematic-doc-anchors: 385 KiB
• cursor/env-setup-830c: 4.5 KiB
• check-release-notes_with_backport-git-tag: 13 KiB
• rwgk/stacked/pathfinder/utils_driver_and_toolkit_info: 12 KiB
• cursor/cloud-dev-env-docs-d4d7: 1.7 KiB
• codex/fix-build-docs-pixi: 33 KiB
• ci/sanitizer-restrict-cuda13: 2.5 KiB

So I would not expect deleting the stale coding-agent branches to noticeably improve clone runtime. It will help keep the branch list clean and avoid accidental pushes to the main fork, which is still worthwhile.

If the goal is specifically to reduce full clone time, the higher-impact options seem to be:

• delete gh-pages-dry-run (I will do that straightaway; I just didn't know it's adding this much weight);
• investigate whether gh-pages needs to live as a branch in the main repository;
• consider moving generated docs artifacts to a separate repository or release artifact flow if they keep dominating repository history;
• document git clone --single-branch or partial clone workflows for developers who only need main.

[rwgk]

• delete gh-pages-dry-run (I will do that straightaway; I just didn't know it's adding this much weight);

Done. The gh-pages-dry-run branch does not exist anymore. It will only ever be needed temporarily, in case we want an easy way to preview the generated documentation before posting the actual release; see PR #2161.

[rwgk]

Generated with Cursor GPT-5.5

---

Follow-up after deleting gh-pages-dry-run:

This was a useful experiment, but the measured impact on full clone size appears to be negligible.

Before deleting gh-pages-dry-run, I measured the objects reachable from upstream branches but not from upstream/main at approximately:

1,171,742,686 bytes

After deleting gh-pages-dry-run and pruning local remote-tracking refs, the same estimate is now:

1,171,727,714 bytes

So the apparent reduction is only about 15 KiB.

The reason is that gh-pages-dry-run looked large when considered by itself relative to main, but almost all of its objects are also reachable from the retained gh-pages branch. Deleting gh-pages-dry-run removed the branch ref, but it did not remove much from the object set that a normal full clone still needs to fetch, because gh-pages continues to keep those docs-related objects reachable.

This means the clone-time / clone-size impact is dominated by gh-pages, not by gh-pages-dry-run specifically. The dry-run branch cleanup was still good hygiene, but if we want a material reduction in full clone weight, we would need to address the retained gh-pages history or use clone workflows that exclude non-main branches, such as --single-branch or partial clone workflows.

[rwgk]

Generated with Cursor GPT-5.5

---

Summary

I ran a local-only experiment to estimate the impact of deleting gh-pages from the upstream branch set. The result is that gh-pages appears to account for almost all of the remaining full-clone object weight.

In this experiment:

• Simulated upstream with gh-pages: .git size after local file:// clone was about 1.2G.
• Simulated upstream without gh-pages: .git size after local file:// clone was about 38M.
• Estimated clone weight reduction: about 1.19 GB by filesystem size, or about 1.17 GB by Git object disk-usage accounting.
• Local file:// clone time dropped from 47.44 seconds to 1.79 seconds on this machine.

The wall-clock timings are local-machine measurements and should not be treated as exact GitHub clone timings. The size delta is the higher-confidence result. It strongly suggests that deleting or otherwise moving gh-pages would materially reduce normal full-clone weight.

---

Details

This was a local simulation. I did not modify upstream.

The experiment was run after gh-pages-dry-run had already been deleted. So this estimates the additional impact of deleting gh-pages from the repository's current state.

I used the local checkout at:

/wrk/forked/cuda-python

and the experiment directory:

/wrk/gh-pages-weight-exp

First I refreshed local upstream refs:

git -C /wrk/forked/cuda-python fetch upstream --prune --tags

At that point the local checkout had:

upstream branch heads: 34
tags: 85
gh-pages-dry-run remote ref: absent

I then created a bare local repository representing the current upstream branch and tag namespace. The fetch maps local remote-tracking refs under refs/remotes/upstream/* to branch refs under refs/heads/* in the bare repository:

base=/wrk/gh-pages-weight-exp

git init --bare "$base/with-gh-pages.git"
git -C "$base/with-gh-pages.git" fetch --quiet /wrk/forked/cuda-python \
  '+refs/remotes/upstream/*:refs/heads/*' \
  '+refs/tags/*:refs/tags/*'
git -C "$base/with-gh-pages.git" update-ref -d refs/heads/HEAD 2>/dev/null || true
git -C "$base/with-gh-pages.git" symbolic-ref HEAD refs/heads/main
git -C "$base/with-gh-pages.git" gc --prune=now

Then I copied that bare repo, deleted only refs/heads/gh-pages, and garbage-collected the copy:

cp -a "$base/with-gh-pages.git" "$base/without-gh-pages.git"

git -C "$base/without-gh-pages.git" update-ref -d refs/heads/gh-pages
git -C "$base/without-gh-pages.git" reflog expire --expire=now --all
git -C "$base/without-gh-pages.git" gc --prune=now

The simulated refs were:

with-gh-pages.git:    34 branch heads, 85 tags
without-gh-pages.git: 33 branch heads, 85 tags

Bare repository measurements:

with-gh-pages.git
  rev-list --disk-usage --objects --all: 1,204,634,857 bytes
  rev-list object count:                  688,500
  git count-objects size-pack:            1.13 GiB
  du -sb:                                 1,230,067,781 bytes
  du -sh:                                 1.2G

without-gh-pages.git
  rev-list --disk-usage --objects --all: 37,810,322 bytes
  rev-list object count:                 23,315
  git count-objects size-pack:           36.68 MiB
  du -sb:                                38,904,496 bytes
  du -sh:                                38M

Bare repository deltas:

rev-list disk-usage delta: 1,166,824,535 bytes
object-count delta:          665,185 objects
du -sb delta:              1,191,163,285 bytes

To approximate what a normal full clone has to receive, I also cloned each bare repo via file://. This is important: cloning from a plain local path can hardlink or copy objects and distort the measurement, while file:// forces Git to use normal fetch/pack negotiation.

Commands:

/usr/bin/time -f 'clone-with-gh-pages-elapsed-seconds: %e' \
  git clone --quiet "file://$base/with-gh-pages.git" "$base/clone-with-gh-pages"

/usr/bin/time -f 'clone-without-gh-pages-elapsed-seconds: %e' \
  git clone --quiet "file://$base/without-gh-pages.git" "$base/clone-without-gh-pages"

Clone measurements:

clone-with-gh-pages
  elapsed:                    47.44 seconds
  git count-objects size-pack: 1.13 GiB
  .git du -sb:                1,226,796,847 bytes
  .git du -sh:                1.2G

clone-without-gh-pages
  elapsed:                    1.79 seconds
  git count-objects size-pack: 36.68 MiB
  .git du -sb:                38,686,334 bytes
  .git du -sh:                38M

Clone deltas:

.git du -sb delta: 1,188,110,513 bytes
elapsed delta:       45.65 seconds locally

Conclusion:

Deleting gh-pages-dry-run was a good cleanup, but it did not reduce clone weight because almost all of its objects were still reachable from gh-pages.

Deleting gh-pages is different. In this local simulation, removing gh-pages reduced the all-branches clone object set from roughly 1.2G to roughly 38M. That suggests gh-pages is currently the dominant cause of full-clone weight.

If we still need the published docs content, we may want to consider moving that history/artifact flow somewhere that does not live as a branch in the main source repository, or at least document --single-branch / partial-clone workflows for developers who only need main.

[rwgk]

Generated with Cursor GPT-5.5

---

Question

Can we keep the gh-pages branch in NVIDIA/cuda-python, but make it so that gh-pages is not included in a normal git clone?

Answer

Probably not, as long as gh-pages remains a normal branch under refs/heads/gh-pages on GitHub.

---

Details

A normal full clone from GitHub fetches the repository's normal branch heads and tags. In practice, that means refs such as:

refs/heads/main
refs/heads/gh-pages
refs/heads/release/...
refs/tags/...

GitHub also has other refs, such as PR refs under refs/pull/*, that are not included in a normal clone. But gh-pages is not one of those hidden refs. If it exists as refs/heads/gh-pages, then a normal full clone will see it and will need to fetch the objects reachable from it.

So I do not think there is a GitHub repository setting that says: "keep this as a normal branch, but hide only this branch from default clones."

The important distinction is between server-side refs and client-side clone choices.

On the server side, GitHub exposes normal branches under refs/heads/*. A default clone uses those refs to decide what branch tips and reachable objects to fetch. Since gh-pages is a normal branch, it participates in that default clone negotiation.

On the client side, developers can opt out of fetching all branches. For example:

git clone --single-branch --branch main https://github.com/NVIDIA/cuda-python.git

That avoids fetching gh-pages, but it requires the person or automation doing the clone to choose that narrower clone mode. It does not change what a normal full clone does by default.

Possible options if the goal is to keep docs publishing while reducing normal clone weight:

1. Move generated docs to a separate repository.

   For example, publish docs from a dedicated cuda-python-docs repository or a repository whose main purpose is GitHub Pages output. This keeps generated docs history out of the main source repository's normal branch namespace.

2. Use a publishing mechanism that does not store generated docs as a long-lived branch in the main repository.

   For example, use release artifacts, external hosting, or another docs deployment flow where generated output is not retained as ordinary source-repository Git history.

3. Keep gh-pages, but rewrite or squash its history.

   This could reduce the amount of data reachable from refs/heads/gh-pages while preserving the branch. However, as long as the branch remains under refs/heads/*, it will still be included in normal full clones. This option reduces weight; it does not hide the branch.

4. Keep gh-pages as-is, but document narrower clone workflows.

   Developers who only need main can use:

   git clone --single-branch --branch main https://github.com/NVIDIA/cuda-python.git

   This helps individual users and automation that can opt in, but it does not improve the behavior of a default full clone.

In short: GitHub can have refs that are not part of a normal clone, but a normal gh-pages branch is not in that category. To keep gh-pages from affecting normal full clone weight, the practical choices are to move it out of the main repository's normal branch set, reduce its reachable history, or have clients explicitly choose a narrower clone.

[leofang]

@leofang | ci/sanitizer-restrict-cuda13

Thanks, Mike! I have deleted this branch. It was meant to work around a CI issue that caused compute-sanitizer to fail and Andy eventually fixed it.