You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Investigate gh-pages impact on full clone size and time #2197
Additional real-world measurements from two NVIDIA-internal wired-network machines (see comments below for details):
Machine
Clone mode
Elapsed time
Received
.git size
Git pack size
Packed objects
smc120-0009
normal full clone
122.85 s
1.25 GiB
1.3G
1.27 GiB
692,924
smc120-0009
--single-branch --branch main
5.77 s
36.11 MiB
38M
36.66 MiB
20,389
smc120-0009
--depth 1 --branch main
2.46 s
2.66 MiB
3.0M
2.68 MiB
903
Dell Precision 7875
normal full clone
92.60 s
1.25 GiB
1.3G
1.27 GiB
692,924
Dell Precision 7875
--single-branch --branch main
4.55 s
36.17 MiB
38M
36.72 MiB
20,389
Dell Precision 7875
--depth 1 --branch main
2.11 s
2.66 MiB
3.0M
2.68 MiB
903
In both runs, the normal clone fetched about 693k packed objects and 1.25 GiB, while the single-branch main clone fetched about 20k objects and 36 MiB.
If gh-pages were removed from the normal branch ref set, what would we expect a normal real-world GitHub SSH clone time to be?
Answer
Based on the two GitHub SSH measurements above, removing gh-pages from the default branch ref set would likely make a normal full clone comparable to today's --single-branch --branch main clone: roughly 5-8 seconds instead of roughly 90-125 seconds on the measured NVIDIA-internal machines.
Details
I would not use the local file:// result of 1.79 seconds as the expected real GitHub clone time. That local experiment is most useful for estimating the object-set delta.
For real GitHub SSH clone timing, the better anchor is the observed single-branch full-depth clone:
smc120-0009: --single-branch --branch main took 5.77 seconds.
Dell Precision 7875: --single-branch --branch main took 4.55 seconds.
The local simulation without gh-pages produced a .git size of about 38M, essentially the same scale as the real single-branch clones. Its object set was also only modestly larger than single-branch main: about 23k objects in the simulation versus about 20k objects in the real single-branch clone.
Current normal GitHub SSH clones fetched about 1.25 GiB and 692,924 packed objects in both runs. Removing gh-pages appears to remove nearly all of that excess.
This improvement should not depend on GitHub pruning orphan blobs. Once gh-pages is no longer an advertised branch ref, its old objects should stop being part of normal clone negotiation, even if GitHub still stores them internally for a while.
I ran a local-only experiment to estimate the effect of compacting gh-pages to a single snapshot commit while keeping it as a normal branch.
In this experiment, compacting gh-pages reduced the simulated all-refs clone payload from about 1.2G to about 96M. Removing gh-pages entirely reduced it to about 37M.
Local file:// clone timings:
Scenario
Branch heads
.git size after clone
Git pack size
Packed objects
Local file:// clone time
Current gh-pages history
34
1.2G
1.14 GiB
692,960
61.80 s
No gh-pages branch
33
37M
36.49 MiB
23,161
2.29 s
Compacted gh-pages snapshot
34
96M
94.75 MiB
49,534
7.37 s
So compacting gh-pages would not get us all the way to the no-gh-pages case, but it appears to remove most of the current clone weight while preserving a normal gh-pages branch.
Method
This was a local simulation. I did not modify upstream.
For the compacted gh-pages case, I copied the current bare repo, created a new orphan commit whose tree is exactly the current gh-pages tree, repointed refs/heads/gh-pages to that commit, expired reflogs, and garbage-collected:
Using file:// is important here: 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.
Bare Repository Measurements
Scenario
Branch heads
Tags
rev-list --disk-usage --objects --all
Object count
count-objects pack size
du -sh
Current gh-pages history
34
85
1,211,852,901 bytes
692,960
1.14 GiB
1.2G
No gh-pages branch
33
85
37,610,382 bytes
23,161
36.49 MiB
38M
Compacted gh-pages snapshot
34
85
97,959,486 bytes
49,534
94.75 MiB
96M
Compared with the current repository shape, compacting gh-pages reduced the bare-repo rev-list --disk-usage estimate by:
1,113,893,415 bytes
Compared with deleting gh-pages entirely, keeping a compacted gh-pages snapshot added:
60,349,104 bytes
26,373 objects
Clone Measurements
Scenario
Local file:// clone time
.git du -sb
.git du -sh
Git pack size
Packed objects
Current gh-pages history
61.80 s
1,234,157,728 bytes
1.2G
1.14 GiB
692,960
No gh-pages branch
2.29 s
38,481,551 bytes
37M
36.49 MiB
23,161
Compacted gh-pages snapshot
7.37 s
99,674,689 bytes
96M
94.75 MiB
49,534
Compared with the current repository shape, compacting gh-pages reduced the cloned .git filesystem size by:
1,134,483,039 bytes
Compared with deleting gh-pages entirely, keeping a compacted gh-pages snapshot added:
61,193,138 bytes
5.08 seconds in this local file:// clone experiment
Interpretation
This experiment suggests that compacting gh-pages to a single snapshot commit would achieve most of the clone-size improvement while preserving the branch.
The result is not as small as deleting gh-pages entirely, because the current generated docs snapshot would still be reachable from refs/heads/gh-pages. But the retained snapshot is much smaller than the accumulated gh-pages history.
This experiment does not directly measure GitHub SSH clone time. It measures the object-set and local fetch/pack behavior after compacting the branch. For real GitHub SSH clone estimates, this should be interpreted together with the earlier real-world measurements:
Current normal GitHub SSH clone: about 90-125 seconds, about 1.25 GiB received.
Current --single-branch --branch main GitHub SSH clone: about 4.5-5.8 seconds, about 36 MiB received.
The compacted case is about 95 MiB by Git pack size, so I would expect real-world GitHub SSH clone time to land above the current single-branch main clone, but far below the current normal full clone.
This also should not depend on GitHub pruning orphan blobs for normal clone behavior. Once old gh-pages history is no longer reachable from an advertised branch ref, it should stop participating in normal clone negotiation, even if GitHub retains unreachable objects internally for a while.
There are two broad ways to get a durable clone-size improvement from the gh-pages side:
Move gh-pages content to another repository.
Keep gh-pages in NVIDIA/cuda-python, but periodically compact its history.
Move gh-pages To Another Repo
I think we should discard this option for now.
The main reason is that we almost certainly need to preserve the existing public URL exactly:
https://nvidia.github.io/cuda-python/...
Moving the Pages content to another repository would normally change the GitHub Pages project URL. That would introduce a much larger compatibility problem than the clone-size problem we are trying to solve. Existing links to release docs, latest docs, PR previews, and coverage pages may be embedded in issues, PRs, release notes, external docs, bookmarks, and downstream references.
If exact URL preservation is required, moving to another repository becomes much less attractive. It would likely require additional GitHub Pages/custom-domain/routing machinery, and that complexity does not seem justified when there is a simpler path that keeps the current URL.
Periodically Compact Upstream gh-pages
This seems like the more realistic option.
The experiment above suggests that compacting gh-pages to a single snapshot commit would preserve the current branch and URL structure while removing most of the clone-size overhead:
Scenario
.git size after local file:// clone
Git pack size
Packed objects
Local file:// clone time
Current gh-pages history
1.2G
1.14 GiB
692,960
61.80 s
No gh-pages branch
37M
36.49 MiB
23,161
2.29 s
Compacted gh-pages snapshot
96M
94.75 MiB
49,534
7.37 s
So compacting does not get all the way to the no-gh-pages case, because the current generated docs snapshot still has to remain reachable. But it appears to remove most of the accumulated history cost while preserving the branch.
This could be done periodically, for example after releases or whenever the normal clone cost grows beyond a threshold. The required operational pieces would be:
A documented procedure or workflow that replaces gh-pages history with one orphan snapshot commit.
A pre-cleanup backup/archive point, likely a tag or branch in a maintainer fork, in case rollback is needed.
Post-cleanup smoke tests for the public docs, release docs, PR previews, and coverage pages.
Agreement that gh-pages history is not relied on for audit/debugging and can be rewritten.
CCCL Reference Point
CCCL appears to have gone further than periodic manual compaction. Its current docs deployment workflow keeps gh-pages compact by construction.
In NVIDIA/cccl, the current docs deploy workflow uses:
This suggests a durable model: instead of treating compaction as a rare manual cleanup, make the normal docs deployment path maintain a compact gh-pages branch.
CUDA Python Difference
CUDA Python has more gh-pages writers than CCCL appears to have in its current setup.
Today, CUDA Python writes to gh-pages from at least:
Release/latest docs deployment under docs/.
PR preview deployment under docs/pr-preview/pr-N/.
PR preview cleanup.
Coverage report deployment under docs/coverage/.
That makes a direct CCCL-style switch less trivial. If multiple workflows independently write to gh-pages, then any workflow that force-orphans the branch needs to preserve the other published subtrees correctly, and concurrent writes become a real operational concern.
The key question is whether CUDA Python can safely adopt a single compacting deployment model, or whether we first need to consolidate the gh-pages writers. The highest-confidence version would have one deployment/maintenance path responsible for materializing the complete desired Pages tree, then publishing it as a compact orphan commit. A lower-effort version might keep the current writers but add a periodic compacting maintenance workflow after confirming that the existing deploy actions tolerate the rewritten history.
My current preference would be:
Keep gh-pages in NVIDIA/cuda-python to preserve https://nvidia.github.io/cuda-python/....
Treat compacting gh-pages as the realistic improvement path.
Learn from CCCL's keep_files: true + force_orphan: true deployment model.
Before implementing, audit whether CUDA Python's multiple gh-pages writers can be made compatible with that model, or whether they should be consolidated first.
@jrhemstad We are looking at ways to reduce the clone-size impact of gh-pages in NVIDIA/cuda-python while preserving https://nvidia.github.io/cuda-python/....
I noticed that NVIDIA/cccl now deploys docs to gh-pages with peaceiris/actions-gh-pages using both keep_files: true and force_orphan: true, and that the current CCCL gh-pages branch has exactly one commit.
Did that setup cause any operational issues in CCCL, especially around GitHub Pages serving, concurrent docs deploys, or preserving existing published subdirectories? Any lessons learned before we consider a similar compacting model for CUDA Python?
This strikeks me as a bit dangerous. If something unfortunate were to happen during doc generation, then you could lose all your older docs.
This requires the gh-pages ruleset to remove the "Block forced pushes" from the rules. (Or we'd have to create a dedicated app, and set gh-pages rule to bypass the github app, always allow, and have the deployment jobs create a short-lived token with actions/github-app-token).
A significant part of this change is to assure that concurrent runs don't overwrite each other. This is an existing problem, though probably rare.
The ci/cleanup-pr-previews is intentionally no longer allowed to push from a local view, since there's no way to avoid concurrency problems. I guess you can still manually force push.
This shouldn't have been closed, the commit message was old. But I'm removing myself from assigned as we're not going to look at the size problem at the moment.
Activity
rwgk commentedon Jun 11, 2026
Quick script to get some real-world measurements (will post the outputs in following comments):
rwgk commentedon Jun 11, 2026
A general colossus machine with great but in no way special network connectivity (smc120-0009):
rwgk commentedon Jun 11, 2026
My Dell Precision 7875 Tower, internal wired network, with great but in no way special connectivity:
rwgk commentedon Jun 11, 2026
Question
If
gh-pageswere removed from the normal branch ref set, what would we expect a normal real-world GitHub SSH clone time to be?Answer
Based on the two GitHub SSH measurements above, removing
gh-pagesfrom the default branch ref set would likely make a normal full clone comparable to today's--single-branch --branch mainclone: roughly 5-8 seconds instead of roughly 90-125 seconds on the measured NVIDIA-internal machines.Details
I would not use the local
file://result of 1.79 seconds as the expected real GitHub clone time. That local experiment is most useful for estimating the object-set delta.For real GitHub SSH clone timing, the better anchor is the observed single-branch full-depth clone:
smc120-0009:--single-branch --branch maintook 5.77 seconds.--single-branch --branch maintook 4.55 seconds.The local simulation without
gh-pagesproduced a.gitsize of about 38M, essentially the same scale as the real single-branch clones. Its object set was also only modestly larger than single-branchmain: about 23k objects in the simulation versus about 20k objects in the real single-branch clone.Current normal GitHub SSH clones fetched about 1.25 GiB and 692,924 packed objects in both runs. Removing
gh-pagesappears to remove nearly all of that excess.This improvement should not depend on GitHub pruning orphan blobs. Once
gh-pagesis no longer an advertised branch ref, its old objects should stop being part of normal clone negotiation, even if GitHub still stores them internally for a while.rwgk commentedon Jun 11, 2026
Entirely designed, run, and reported by GTP-5.5
Summary
I ran a local-only experiment to estimate the effect of compacting
gh-pagesto a single snapshot commit while keeping it as a normal branch.In this experiment, compacting
gh-pagesreduced the simulated all-refs clone payload from about 1.2G to about 96M. Removinggh-pagesentirely reduced it to about 37M.Local
file://clone timings:.gitsize after clonefile://clone timegh-pageshistorygh-pagesbranchgh-pagessnapshotSo compacting
gh-pageswould not get us all the way to the no-gh-pagescase, but it appears to remove most of the current clone weight while preserving a normalgh-pagesbranch.Method
This was a local simulation. I did not modify upstream.
Experiment directory:
I first refreshed local upstream refs:
At that point, the fetch updated:
I then created a bare local repository representing the current upstream branch and tag namespace:
For the no-
gh-pagescontrol, I copied that bare repo, deleted onlyrefs/heads/gh-pages, expired reflogs, and garbage-collected:For the compacted
gh-pagescase, I copied the current bare repo, created a new orphan commit whose tree is exactly the currentgh-pagestree, repointedrefs/heads/gh-pagesto that commit, expired reflogs, and garbage-collected:The compacted snapshot used:
Finally, I cloned each bare repo via
file://:Using
file://is important here: cloning from a plain local path can hardlink or copy objects and distort the measurement, whilefile://forces Git to use normal fetch/pack negotiation.Bare Repository Measurements
rev-list --disk-usage --objects --allcount-objectspack sizedu -shgh-pageshistorygh-pagesbranchgh-pagessnapshotCompared with the current repository shape, compacting
gh-pagesreduced the bare-reporev-list --disk-usageestimate by:Compared with deleting
gh-pagesentirely, keeping a compactedgh-pagessnapshot added:Clone Measurements
file://clone time.git du -sb.git du -shgh-pageshistorygh-pagesbranchgh-pagessnapshotCompared with the current repository shape, compacting
gh-pagesreduced the cloned.gitfilesystem size by:Compared with deleting
gh-pagesentirely, keeping a compactedgh-pagessnapshot added:Interpretation
This experiment suggests that compacting
gh-pagesto a single snapshot commit would achieve most of the clone-size improvement while preserving the branch.The result is not as small as deleting
gh-pagesentirely, because the current generated docs snapshot would still be reachable fromrefs/heads/gh-pages. But the retained snapshot is much smaller than the accumulatedgh-pageshistory.This experiment does not directly measure GitHub SSH clone time. It measures the object-set and local fetch/pack behavior after compacting the branch. For real GitHub SSH clone estimates, this should be interpreted together with the earlier real-world measurements:
--single-branch --branch mainGitHub SSH clone: about 4.5-5.8 seconds, about 36 MiB received.The compacted case is about 95 MiB by Git pack size, so I would expect real-world GitHub SSH clone time to land above the current single-branch
mainclone, but far below the current normal full clone.This also should not depend on GitHub pruning orphan blobs for normal clone behavior. Once old
gh-pageshistory is no longer reachable from an advertised branch ref, it should stop participating in normal clone negotiation, even if GitHub retains unreachable objects internally for a while.rwgk commentedon Jun 11, 2026
GPT-5.5 Analysis
Options for durable clone-size improvement
There are two broad ways to get a durable clone-size improvement from the
gh-pagesside:gh-pagescontent to another repository.gh-pagesinNVIDIA/cuda-python, but periodically compact its history.Move
gh-pagesTo Another RepoI think we should discard this option for now.
The main reason is that we almost certainly need to preserve the existing public URL exactly:
Moving the Pages content to another repository would normally change the GitHub Pages project URL. That would introduce a much larger compatibility problem than the clone-size problem we are trying to solve. Existing links to release docs, latest docs, PR previews, and coverage pages may be embedded in issues, PRs, release notes, external docs, bookmarks, and downstream references.
If exact URL preservation is required, moving to another repository becomes much less attractive. It would likely require additional GitHub Pages/custom-domain/routing machinery, and that complexity does not seem justified when there is a simpler path that keeps the current URL.
Periodically Compact Upstream
gh-pagesThis seems like the more realistic option.
The experiment above suggests that compacting
gh-pagesto a single snapshot commit would preserve the current branch and URL structure while removing most of the clone-size overhead:.gitsize after localfile://clonefile://clone timegh-pageshistorygh-pagesbranchgh-pagessnapshotSo compacting does not get all the way to the no-
gh-pagescase, because the current generated docs snapshot still has to remain reachable. But it appears to remove most of the accumulated history cost while preserving the branch.This could be done periodically, for example after releases or whenever the normal clone cost grows beyond a threshold. The required operational pieces would be:
gh-pageshistory with one orphan snapshot commit.gh-pageshistory is not relied on for audit/debugging and can be rewritten.CCCL Reference Point
CCCL appears to have gone further than periodic manual compaction. Its current docs deployment workflow keeps
gh-pagescompact by construction.In
NVIDIA/cccl, the current docs deploy workflow uses:The current
NVIDIA/ccclgh-pagesbranch has exactly one commit, which is consistent withforce_orphan: trueproducing a fresh orphan deployment commit.Relevant CCCL PRs:
gh-pagesdeployment.keep_files + force_orphan..doctreesand removing exhaustive API listing from table of contents cccl#7696 separately reduced the size of the deployed docs snapshot itself.This suggests a durable model: instead of treating compaction as a rare manual cleanup, make the normal docs deployment path maintain a compact
gh-pagesbranch.CUDA Python Difference
CUDA Python has more
gh-pageswriters than CCCL appears to have in its current setup.Today, CUDA Python writes to
gh-pagesfrom at least:docs/.docs/pr-preview/pr-N/.docs/coverage/.That makes a direct CCCL-style switch less trivial. If multiple workflows independently write to
gh-pages, then any workflow that force-orphans the branch needs to preserve the other published subtrees correctly, and concurrent writes become a real operational concern.The key question is whether CUDA Python can safely adopt a single compacting deployment model, or whether we first need to consolidate the
gh-pageswriters. The highest-confidence version would have one deployment/maintenance path responsible for materializing the complete desired Pages tree, then publishing it as a compact orphan commit. A lower-effort version might keep the current writers but add a periodic compacting maintenance workflow after confirming that the existing deploy actions tolerate the rewritten history.My current preference would be:
gh-pagesinNVIDIA/cuda-pythonto preservehttps://nvidia.github.io/cuda-python/....gh-pagesas the realistic improvement path.keep_files: true + force_orphan: truedeployment model.gh-pageswriters can be made compatible with that model, or whether they should be consolidated first.rwgk commentedon Jun 11, 2026
Ralf in the words of GPT-5.5
@jrhemstad We are looking at ways to reduce the clone-size impact of
gh-pagesinNVIDIA/cuda-pythonwhile preservinghttps://nvidia.github.io/cuda-python/....I noticed that
NVIDIA/ccclnow deploys docs togh-pageswithpeaceiris/actions-gh-pagesusing bothkeep_files: trueandforce_orphan: true, and that the current CCCLgh-pagesbranch has exactly one commit.Did that setup cause any operational issues in CCCL, especially around GitHub Pages serving, concurrent docs deploys, or preserving existing published subdirectories? Any lessons learned before we consider a similar compacting model for CUDA Python?
9 remaining items
jpascucci-nv commentedon Sep 18, 2026
Summary of fix #2914
jpascucci-nv commentedon Sep 21, 2026
Leo suggested we punt on the size issue for now. Link to message.
Cleanup concurrency problems in doc generation (NVIDIA#2914)
jpascucci-nv commentedon Sep 30, 2026
This shouldn't have been closed, the commit message was old. But I'm removing myself from assigned as we're not going to look at the size problem at the moment.
wence- commentedon Oct 2, 2026
One needn't push to a branch at all to publish a site. See https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#creating-a-custom-github-actions-workflow-to-publish-your-site
leofang commentedon Oct 2, 2026
Explained offline. This is required for us to e.g. customize and build our doc preview system.
Remove the Allure test report for PR 3006 (docs/test-report/pr-3006)