docs(scm): document singleBranch/depth performance option

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

@@ -0,0 +1,21 @@
+---
+name: Test Gitea scm optimized for large repositories
+
+scms:
+  gitea:
+    kind: gitea
+    spec:
+      url: "try.gitea.io"
+      owner: "olblak"
+      repository: "updatecli-mirror"
+      branch: main
+      depth: 1
+      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,22 @@
+---
+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
+      depth: 1
+      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,42 @@
+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
+      depth: 1
+      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,26 @@
+name: "Example with Bitbucket Cloud SCM optimized for large repositories"
+pipelineid: bitbucket/scm
+
+scms:
+  bitbucket:
+    kind: bitbucket
+    spec:
+      owner: "updatecli"
+      repository: "updatecli"
+      branch: main
+      depth: 1
+      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,20 @@
+name: "Example with Git SCM optimized for large repositories"
+
+scms:
+  scenario-target:
+    kind: git
+    spec:
+      url: "git@github.com:updatecli/updatecli.git"
+      branch: "main"
+      depth: 1
+      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,24 @@
+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"
+      depth: 1
+      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,23 @@
+---
+name: Test Bitbucket Server (Stash) scm optimized for large repositories
+
+scms:
+  stash:
+    kind: stash
+    spec:
+      url: "https://bitbucket.exmaple.com"
+      owner: "olblak"
+      repository: "updatecli-mirror"
+      branch: "main"
+      depth: 1
+      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

@@ -70,3 +70,17 @@ It creates the pull request on a temporary working branch, following the Azure D
 # updatecli.yaml
 {{<include "assets/code_example/docs/plugins/scm/azuredevops/updatecli.d/default.yaml">}}
 ----
+
+=== Performance on large repositories
+
+By default, Updatecli fetches every branch, tag, and other ref from the remote repository, which can be slow on repositories with a large number of refs (hundreds of branches/tags, hundreds of thousands of commits).
+
+Setting `depth` to a low value (e.g. `1`) combined with `singleBranch: true` restricts the checkout to the configured `branch` only, skipping the fetch of every other branch, tag, and ref on the remote. This can drastically reduce checkout time on large repositories.
+
+NOTE: Enabling `singleBranch` means Updatecli only has visibility into the configured branch. If your pipeline relies on detecting other branches or tags (for example to avoid opening duplicate pull requests), keep this option disabled.
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/scm/azuredevops/updatecli.d/performance.yaml">}}
+----

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

@@ -54,9 +54,25 @@ Date:   Tue May 4 15:41:44 2021 +0200
 
 == Example
 
+=== Default
+
 [source,yaml]
 ----
 # updatecli.yaml
 {{<include "assets/code_example/docs/plugins/scm/bitbucket/updatecli.d/default.yaml">}}
 ----
 
+=== Performance on large repositories
+
+By default, Updatecli fetches every branch, tag, and other ref from the remote repository, which can be slow on repositories with a large number of refs (hundreds of branches/tags, hundreds of thousands of commits).
+
+Setting `depth` to a low value (e.g. `1`) combined with `singleBranch: true` restricts the checkout to the configured `branch` only, skipping the fetch of every other branch, tag, and ref on the remote. This can drastically reduce checkout time on large repositories.
+
+NOTE: Enabling `singleBranch` means Updatecli only has visibility into the configured branch. If your pipeline relies on detecting other branches or tags (for example to avoid opening duplicate pull requests), keep this option disabled.
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/scm/bitbucket/updatecli.d/performance.yaml">}}
+----
+

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

@@ -94,3 +94,16 @@ At the moment they are two ways to authentication with a git repository, either
 ```
 {{< include "assets/code_example/docs/plugins/scm/git/updatecli.d/default.yaml" >}}
 ```
+
+=== Performance on large repositories
+
+By default, Updatecli fetches every branch, tag, and other ref from the remote repository, which can be slow on repositories with a large number of refs (hundreds of branches/tags, hundreds of thousands of commits).
+
+Setting `depth` to a low value (e.g. `1`) combined with `singleBranch: true` restricts the checkout to the configured `branch` only, skipping the fetch of every other branch, tag, and ref on the remote. This can drastically reduce checkout time on large repositories.
+
+NOTE: Enabling `singleBranch` means Updatecli only has visibility into the configured branch. If your pipeline relies on detecting other branches or tags (for example to avoid opening duplicate pull requests), keep this option disabled.
+
+**updatecli.yaml**
+```
+{{< include "assets/code_example/docs/plugins/scm/git/updatecli.d/performance.yaml" >}}
+```

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

@@ -83,3 +83,17 @@ Updatecli can sign commits using a private GPG key if configured accordingly.
 {{<include "assets/code_example/docs/plugins/gitea/updatecli.yaml">}}
 ----
 
+=== Performance on large repositories
+
+By default, Updatecli fetches every branch, tag, and other ref from the remote repository, which can be slow on repositories with a large number of refs (hundreds of branches/tags, hundreds of thousands of commits).
+
+Setting `depth` to a low value (e.g. `1`) combined with `singleBranch: true` restricts the checkout to the configured `branch` only, skipping the fetch of every other branch, tag, and ref on the remote. This can drastically reduce checkout time on large repositories.
+
+NOTE: Enabling `singleBranch` means Updatecli only has visibility into the configured branch. If your pipeline relies on detecting other branches or tags (for example to avoid opening duplicate pull requests), keep this option disabled.
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/gitea/updatecli-performance.yaml">}}
+----
+

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

@@ -78,3 +78,17 @@ Date:   Tue May 4 15:41:44 2021 +0200
 {{<include "assets/code_example/docs/plugins/scm/github/updatecli.d/commitmessage.yaml">}}
 ----
 
+=== Performance on large repositories
+
+By default, Updatecli fetches every branch, tag, and other ref from the remote repository, which can be slow on repositories with a large number of refs (hundreds of branches/tags, hundreds of thousands of commits).
+
+Setting `depth` to a low value (e.g. `1`) combined with `singleBranch: true` restricts the checkout to the configured `branch` only, skipping the fetch of every other branch, tag, and ref on the remote. This can drastically reduce checkout time on large repositories.
+
+NOTE: Enabling `singleBranch` means Updatecli only has visibility into the configured branch. If your pipeline relies on detecting other branches or tags (for example to avoid opening duplicate pull requests), keep this option disabled.
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/scm/github/updatecli.d/performance.yaml">}}
+----
+

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

@@ -88,3 +88,17 @@ and the merge request updatecli creates will be stuck in the "Your merge request
 {{<include "assets/code_example/docs/plugins/gitlab/updatecli.yaml">}}
 ----
 
+=== Performance on large repositories
+
+By default, Updatecli fetches every branch, tag, and other ref from the remote repository, which can be slow on repositories with a large number of refs (hundreds of branches/tags, hundreds of thousands of commits).
+
+Setting `depth` to a low value (e.g. `1`) combined with `singleBranch: true` restricts the checkout to the configured `branch` only, skipping the fetch of every other branch, tag, and ref on the remote. This can drastically reduce checkout time on large repositories.
+
+NOTE: Enabling `singleBranch` means Updatecli only has visibility into the configured branch. If your pipeline relies on detecting other branches or tags (for example to avoid opening duplicate pull requests), keep this option disabled.
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/gitlab/updatecli-performance.yaml">}}
+----
+

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

@@ -83,3 +83,17 @@ Updatecli can sign commits using a private GPG key if configured accordingly.
 {{<include "assets/code_example/docs/plugins/stash/updatecli.yaml">}}
 ----
 
+=== Performance on large repositories
+
+By default, Updatecli fetches every branch, tag, and other ref from the remote repository, which can be slow on repositories with a large number of refs (hundreds of branches/tags, hundreds of thousands of commits).
+
+Setting `depth` to a low value (e.g. `1`) combined with `singleBranch: true` restricts the checkout to the configured `branch` only, skipping the fetch of every other branch, tag, and ref on the remote. This can drastically reduce checkout time on large repositories.
+
+NOTE: Enabling `singleBranch` means Updatecli only has visibility into the configured branch. If your pipeline relies on detecting other branches or tags (for example to avoid opening duplicate pull requests), keep this option disabled.
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/stash/updatecli-performance.yaml">}}
+----
+