docs(scm): document singleBranch/depth performance option - #3514
Merged
olblak merged 3 commits intoAug 6, 2026
Merged
Conversation
Adds a new 'Performance on large repositories' subsection to each scm plugin doc (github, gitlab, gitea, bitbucket, stash, azuredevops, git) explaining the new singleBranch option (paired with depth) that lets Updatecli skip fetching every branch, tag, and ref on the remote, along with a runnable example for each plugin. Related to updatecli/updatecli#9590. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Member
|
I slightly modified the pullrequest as part of it was already documented when working on #3597 |
olblak
enabled auto-merge (squash)
August 6, 2026 11:36
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
updatecli/updatecli#9590introduces a new opt-indepth+singleBranchcombination for git-based scm plugins (github,gitlab,gitea,bitbucket,stash,azuredevops,git) that lets Updatecli skip fetching every branch, tag, and ref on the remote during checkout. On repositories with hundreds of branches/tags and hundreds of thousands of commits, this reduced checkout time from ~19 minutes to ~43 seconds.The parameter reference table on each scm doc page (
{{< resourceparameters "scms" "..." >}}) is auto-generated from the JSON schema incontent/en/schema/latest/policy/manifest/config.json, which is refreshed automatically by thejsonschemapipeline (updatecli/updatecli.d/jsonschema.yaml) once a new Updatecli release ships with the field. That part requires no manual change here.However, none of the scm doc pages had prose/examples explaining why and how to use this option, so users are unlikely to discover it.
Solution
Added a new "Performance on large repositories" subsection to each of the 7 affected scm doc pages:
content/en/docs/plugins/scm/github.adoccontent/en/docs/plugins/scm/gitlab.adoccontent/en/docs/plugins/scm/gitea.adoccontent/en/docs/plugins/scm/bitbucket.adoccontent/en/docs/plugins/scm/stash.adoccontent/en/docs/plugins/scm/azuredevops.adoccontent/en/docs/plugins/scm/git.adocEach subsection explains:
depth: 1+singleBranch: truescopes the checkout to just the configured branch.NOTE:) about reduced visibility into other branches/tags when enabled (e.g. duplicate-PR detection).A corresponding runnable example yaml file was added for each plugin under
assets/code_example/docs/plugins/..., following the same include pattern already used by the existing "Default"/"CommitMessage" examples on each page.Related