docs(scm): document singleBranch/depth performance option

assets/code_example/docs/plugins/gitea/updatecli-performance.yaml

@@ -0,0 +1,20 @@
+---
+name: Test Gitea scm optimized for large repositories
+
+scms:
+  gitea:
+    kind: gitea
+    spec:
+      url: "try.gitea.io"
+      owner: "olblak"
+      repository: "updatecli-mirror"
+      branch: main
+      singleBranch: true
+
+sources:
+  license:
+    name: Retrieve license file content
+    kind: file
+    scmid: gitea
+    spec:
+      file: LICENSE

assets/code_example/docs/plugins/gitlab/updatecli-performance.yaml

@@ -0,0 +1,21 @@
+---
+name: Show Gitlab scm optimized for large repositories
+
+scms:
+  gitlab:
+    kind: gitlab
+    spec:
+      # By default url is set to gitlab.com
+      # url: gitlab.com
+      owner: "olblak"
+      repository: "updatecli"
+      branch: main
+      singleBranch: true
+
+sources:
+  license:
+    name: Retrieve license file content
+    kind: file
+    scmid: gitlab
+    spec:
+      file: LICENSE

assets/code_example/docs/plugins/scm/azuredevops/updatecli.d/performance.yaml

@@ -0,0 +1,41 @@
+name: Update a file and open an Azure DevOps Pull Request on a large repository
+
+scms:
+  default:
+    kind: azuredevops
+    spec:
+      organization: myorg
+      project: myproject
+      repository: myrepo
+      branch: main
+      singleBranch: true
+      token: '{{ requiredEnv "UPDATECLI_AZURE_DEVOPS_TOKEN" }}'
+      username: '{{ requiredEnv "UPDATECLI_AZURE_DEVOPS_USERNAME" }}'
+      user: updatecli
+      email: updatecli@example.com
+
+sources:
+  golang:
+    name: Get the latest Golang version
+    kind: golang
+    spec:
+      versionfilter:
+        kind: semver
+        pattern: "1.24.x"
+
+targets:
+  golang-version:
+    name: 'deps(golang): Bump Golang version to {{ source "golang" }}'
+    kind: yaml
+    scmid: default
+    spec:
+      file: .github/workflows/*.yaml
+      key: '$.jobs.build.steps[?(@.uses =~ /^actions\/setup-go/)].with.go-version'
+      searchpattern: true
+
+actions:
+  default:
+    kind: azuredevops/pullrequest
+    scmid: default
+    spec:
+      title: 'deps(golang): Bump Golang version'

assets/code_example/docs/plugins/scm/bitbucket/updatecli.d/performance.yaml

@@ -0,0 +1,25 @@
+name: "Example with Bitbucket Cloud SCM optimized for large repositories"
+pipelineid: bitbucket/scm
+
+scms:
+  bitbucket:
+    kind: bitbucket
+    spec:
+      owner: "updatecli"
+      repository: "updatecli"
+      branch: main
+      singleBranch: true
+      # {{ if (env "BITBUCKET_TOKEN") }}
+      token: '{{ env "BITBUCKET_TOKEN" }}'
+      # {{ else if (and (env "BITBUCKET_USER") (env "BITBUCKET_APP_PASSWORD")) }}
+      username: '{{ env "BITBUCKET_USER" }}'
+      password: '{{ env "BITBUCKET_APP_PASSWORD" }}'
+      # {{ end }}
+
+sources:
+  source-1:
+    name: "Source 1"
+    kind: file
+    scmid: bitbucket
+    spec:
+      file: README.md

assets/code_example/docs/plugins/scm/git/updatecli.d/performance.yaml

@@ -0,0 +1,19 @@
+name: "Example with Git SCM optimized for large repositories"
+
+scms:
+  scenario-target:
+    kind: git
+    spec:
+      url: "git@github.com:updatecli/updatecli.git"
+      branch: "main"
+      singleBranch: true
+      user: "git user to push from changes"
+      email: "git user email to push from change"
+
+targets:
+  target-1:
+    name: "Target 1"
+    kind: file
+    scmid: scenario-target
+    spec:
+      file: README.md

assets/code_example/docs/plugins/scm/github/updatecli.d/performance.yaml

@@ -0,0 +1,23 @@
+name: Example of a GitHub SCM configuration optimized for large repositories
+
+scms:
+  default:
+    kind: github
+    spec:
+      user: "git user to push from changes"
+      email: "git user email to push from change"
+      directory: "directory where to clone the git repository"
+      owner: "github owner"
+      repository: "github repository"
+      token: "github token with enough permission on repository"
+      username: "github username used for push git changes. Needed in private repositories"
+      branch: "git branch where to push changes"
+      singleBranch: true
+
+targets:
+  id:
+    kind: yaml
+    scmid: default
+    spec:
+      file: "Yaml file path from the root repository"
+      key: "yaml key to update"

assets/code_example/docs/plugins/stash/updatecli-performance.yaml

@@ -0,0 +1,22 @@
+---
+name: Test Bitbucket Server (Stash) scm optimized for large repositories
+
+scms:
+  stash:
+    kind: stash
+    spec:
+      url: "https://bitbucket.example.com"
+      owner: "olblak"
+      repository: "updatecli-mirror"
+      branch: "main"
+      singleBranch: true
+      username: "user"
+      token: "123456789ABCDEFGHI"
+
+sources:
+  license:
+    name: Retrieve license file content
+    kind: file
+    scmid: stash
+    spec:
+      file: LICENSE

content/en/docs/plugins/scm/azuredevops.adoc

@@ -129,14 +129,27 @@ Left unset, `directory` defaults to `<tmp>/updatecli/azuredevops/<project>/<repo
 `depth`:: Number of commits to fetch. Unset means a full clone. A shallow clone leaves an incomplete history, which can break pushes; `force: true` is often needed alongside.
 `singleBranch`:: Defaults to `false`, meaning every branch, tag, and ref is fetched. `true` fetches only `branch` (much faster on repositories with many refs, at the cost of Updatecli sometimes failing to notice an already published working branch and opening a duplicate pull request).
 
+On a repository with a large number of refs, `singleBranch` is the option that pays off: it skips the fetch that otherwise mirrors every branch, tag, and pull request ref from the remote. It only applies when `branch` is set. See <<_large_repositories,Large repositories>> for a full manifest.
+
 TIP: To run the same manifest against every repository of an organization instead of a single one, use the link:/docs/plugins/scm/azuredevopssearch/[`azuredevopssearch`] scm.
 
 == Example
 
+=== Default
+
 This pipeline updates the Golang version in a single Azure DevOps repository: the change is committed on a working branch, and the `azuredevops/pullrequest` action turns that branch into a pull request against `main`.
 
 [source,yaml]
 ----
 # updatecli.yaml
 {{<include "assets/code_example/docs/plugins/scm/azuredevops/updatecli.d/default.yaml">}}
 ----
+
+[#_large_repositories]
+=== Large repositories
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/scm/azuredevops/updatecli.d/performance.yaml">}}
+----

content/en/docs/plugins/scm/bitbucket.adoc

@@ -141,12 +141,25 @@ Left unset, `directory` defaults to `<tmp>/updatecli/bitbucket/<owner>/<reposito
 `depth`:: Number of commits to fetch. Unset means a full clone. A shallow clone leaves an incomplete history, which can break pushes; `force: true` is often needed alongside.
 `singleBranch`:: Defaults to `false`, meaning every branch, tag, and ref is fetched. `true` fetches only `branch` (much faster on repositories with many refs, at the cost of Updatecli sometimes failing to notice an already published working branch and opening a duplicate pull request).
 
+On a repository with a large number of refs, `singleBranch` is the option that pays off: it skips the fetch that otherwise mirrors every branch, tag, and pull request ref from the remote. It only applies when `branch` is set. See <<_large_repositories,Large repositories>> for a full manifest.
+
 == Example
 
+=== Default
+
 The manifest below picks whichever credential is available in the environment, thanks to the Go template guards around the two blocks.
 
 [source,yaml]
 ----
 # updatecli.yaml
 {{<include "assets/code_example/docs/plugins/scm/bitbucket/updatecli.d/default.yaml">}}
 ----
+
+[#_large_repositories]
+=== Large repositories
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/scm/bitbucket/updatecli.d/performance.yaml">}}
+----

content/en/docs/plugins/scm/git.adoc

@@ -142,16 +142,29 @@ Left unset, `directory` is derived from the URL under your system temporary dire
 `depth`:: Number of commits to fetch. Unset means a full clone. A shallow clone leaves Updatecli with an incomplete history, which can break pushes; `force: true` is often needed alongside.
 `singleBranch`:: Defaults to `false`, meaning every branch, tag, and ref is fetched. Setting it to `true` fetches only `branch`, which is much faster on repositories with many refs, at the cost of Updatecli sometimes failing to notice an already published working branch.
 
+On a repository with a large number of refs, `singleBranch` is the option that pays off: it skips the fetch that otherwise mirrors every branch, tag, and pull request ref from the remote. It only applies when `branch` is set. See <<_large_repositories,Large repositories>> for a full manifest.
+
 === Commit identity
 
 `user` and `email` name the commit author, defaulting to `updatecli-bot` and `updatecli-bot@updatecli.io`.
 
 == Example
 
+=== Default
+
 The manifest below uses three separate scms: one to read a file, one to test a condition, and one over SSH to push a change on a working branch.
 
 [source,yaml]
 ----
 # updatecli.yaml
 {{< include "assets/code_example/docs/plugins/scm/git/updatecli.d/default.yaml" >}}
 ----
+
+[#_large_repositories]
+=== Large repositories
+
+[source,yaml]
+----
+# updatecli.yaml
+{{< include "assets/code_example/docs/plugins/scm/git/updatecli.d/performance.yaml" >}}
+----

content/en/docs/plugins/scm/gitea.adoc

@@ -133,10 +133,23 @@ Left unset, `directory` defaults to `<tmp>/updatecli/gitea/<owner>/<repository>`
 `depth`:: Number of commits to fetch. Unset means a full clone. A shallow clone leaves an incomplete history, which can break pushes; `force: true` is often needed alongside.
 `singleBranch`:: Defaults to `false`, meaning every branch, tag, and ref is fetched. `true` fetches only `branch` (much faster on repositories with many refs, at the cost of Updatecli sometimes failing to notice an already published working branch and opening a duplicate pull request).
 
+On a repository with a large number of refs, `singleBranch` is the option that pays off: it skips the fetch that otherwise mirrors every branch, tag, and pull request ref from the remote. It only applies when `branch` is set. See <<_large_repositories,Large repositories>> for a full manifest.
+
 == Example
 
+=== Default
+
 [source,yaml]
 ----
 # updatecli.yaml
 {{<include "assets/code_example/docs/plugins/gitea/updatecli.yaml">}}
 ----
+
+[#_large_repositories]
+=== Large repositories
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/gitea/updatecli-performance.yaml">}}
+----

content/en/docs/plugins/scm/github.adoc

@@ -146,6 +146,8 @@ Three parameters control how much is fetched, all of them trade-offs on large re
 `depth`:: Number of commits to fetch. Unset means a full clone. A shallow clone gives Updatecli an incomplete history, which can break pushes; setting `force: true` is often necessary alongside it.
 `singleBranch`:: Defaults to `false`, meaning every branch, tag, and ref is fetched. Set it to `true` to fetch only `branch`, which is significantly faster on repositories with many refs. In return, Updatecli may fail to notice an already published working branch in some edge cases, and open a duplicate pull request.
 
+On a repository with a large number of refs, `singleBranch` is the option that pays off: it skips the fetch that otherwise mirrors every branch, tag, and pull request ref from the remote. It only applies when `branch` is set. See <<_large_repositories,Large repositories>> for a full manifest.
+
 === GitHub Enterprise
 
 Point `url` at your instance, for example `github.example.com`. The scheme is optional and defaults to `https://`. Updatecli then talks to the GraphQL API at `<url>/api/graphql` and clones from `<url>/<owner>/<repository>.git`. Left unset, `url` defaults to `github.com`.
@@ -179,3 +181,12 @@ Updatecli checks the remaining GitHub API quota before its GraphQL calls. When t
 # updatecli.yaml
 {{<include "assets/code_example/docs/plugins/scm/github/updatecli.d/githubapp.yaml">}}
 ----
+
+[#_large_repositories]
+=== Large repositories
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/scm/github/updatecli.d/performance.yaml">}}
+----

content/en/docs/plugins/scm/gitlab.adoc

@@ -149,12 +149,25 @@ Left unset, `directory` defaults to `<tmp>/updatecli/gitlab/<owner>/<repository>
 `depth`:: Number of commits to fetch. Unset means a full clone. A shallow clone leaves an incomplete history, which can break pushes; `force: true` is often needed alongside.
 `singleBranch`:: Defaults to `false`, meaning every branch, tag, and ref is fetched. `true` fetches only `branch` (much faster on repositories with many refs, at the cost of Updatecli sometimes failing to notice an already published working branch and opening a duplicate merge request).
 
+On a repository with a large number of refs, `singleBranch` is the option that pays off: it skips the fetch that otherwise mirrors every branch, tag, and merge request ref from the remote. It only applies when `branch` is set. See <<_large_repositories,Large repositories>> for a full manifest.
+
 TIP: To run the same manifest against every project of a group instead of a single repository, use the link:/docs/plugins/scm/gitlabsearch/[`gitlabsearch`] scm.
 
 == Example
 
+=== Default
+
 [source,yaml]
 ----
 # updatecli.yaml
 {{<include "assets/code_example/docs/plugins/gitlab/updatecli.yaml">}}
 ----
+
+[#_large_repositories]
+=== Large repositories
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/gitlab/updatecli-performance.yaml">}}
+----

content/en/docs/plugins/scm/stash.adoc

@@ -139,10 +139,23 @@ Left unset, `directory` defaults to `<tmp>/updatecli/stash/<owner>/<repository>`
 `depth`:: Number of commits to fetch. Unset means a full clone. A shallow clone leaves an incomplete history, which can break pushes; `force: true` is often needed alongside.
 `singleBranch`:: Defaults to `false`, meaning every branch, tag, and ref is fetched. `true` fetches only `branch` (much faster on repositories with many refs, at the cost of Updatecli sometimes failing to notice an already published working branch and opening a duplicate pull request).
 
+On a repository with a large number of refs, `singleBranch` is the option that pays off: it skips the fetch that otherwise mirrors every branch, tag, and pull request ref from the remote. It only applies when `branch` is set. See <<_large_repositories,Large repositories>> for a full manifest.
+
 == Example
 
+=== Default
+
 [source,yaml]
 ----
 # updatecli.yaml
 {{<include "assets/code_example/docs/plugins/stash/updatecli.yaml">}}
 ----
+
+[#_large_repositories]
+=== Large repositories
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/stash/updatecli-performance.yaml">}}
+----