diff --git a/api/v1beta2/gitrepository_types.go b/api/v1beta2/gitrepository_types.go index f85191e87..58c57a9a1 100644 --- a/api/v1beta2/gitrepository_types.go +++ b/api/v1beta2/gitrepository_types.go @@ -106,7 +106,6 @@ type GitRepositorySpec struct { // RecurseSubmodules enables the initialization of all submodules within // the GitRepository as cloned from the URL, using their default settings. - // This option is available only when using the 'go-git' GitImplementation. // +optional RecurseSubmodules bool `json:"recurseSubmodules,omitempty"` @@ -156,9 +155,6 @@ func (in *GitRepositoryInclude) GetToPath() string { // GitRepositoryRef specifies the Git reference to resolve and checkout. type GitRepositoryRef struct { // Branch to check out, defaults to 'master' if no other field is defined. - // - // When GitRepositorySpec.GitImplementation is set to 'go-git', a shallow - // clone of the specified branch is performed. // +optional Branch string `json:"branch,omitempty"` @@ -170,11 +166,17 @@ type GitRepositoryRef struct { // +optional SemVer string `json:"semver,omitempty"` + // Name of the reference to check out; takes precedence over Branch, Tag and SemVer. + // + // It must be a valid Git reference: https://git-scm.com/docs/git-check-ref-format#_description + // Examples: "refs/heads/main", "refs/tags/v0.1.0", "refs/pull/420/head", "refs/merge-requests/1/head" + // +optional + Name string `json:"name,omitempty"` + // Commit SHA to check out, takes precedence over all reference fields. // - // When GitRepositorySpec.GitImplementation is set to 'go-git', this can be - // combined with Branch to shallow clone the branch, in which the commit is - // expected to exist. + // This can be combined with Branch to shallow clone the branch, in which + // the commit is expected to exist. // +optional Commit string `json:"commit,omitempty"` } diff --git a/config/crd/bases/source.toolkit.fluxcd.io_gitrepositories.yaml b/config/crd/bases/source.toolkit.fluxcd.io_gitrepositories.yaml index 58dab8f06..5f370659a 100644 --- a/config/crd/bases/source.toolkit.fluxcd.io_gitrepositories.yaml +++ b/config/crd/bases/source.toolkit.fluxcd.io_gitrepositories.yaml @@ -462,25 +462,28 @@ spec: recurseSubmodules: description: RecurseSubmodules enables the initialization of all submodules within the GitRepository as cloned from the URL, using their default - settings. This option is available only when using the 'go-git' - GitImplementation. + settings. type: boolean ref: description: Reference specifies the Git reference to resolve and monitor for changes, defaults to the 'master' branch. properties: branch: - description: "Branch to check out, defaults to 'master' if no - other field is defined. \n When GitRepositorySpec.GitImplementation - is set to 'go-git', a shallow clone of the specified branch - is performed." + description: Branch to check out, defaults to 'master' if no other + field is defined. type: string commit: description: "Commit SHA to check out, takes precedence over all - reference fields. \n When GitRepositorySpec.GitImplementation - is set to 'go-git', this can be combined with Branch to shallow + reference fields. \n This can be combined with Branch to shallow clone the branch, in which the commit is expected to exist." type: string + name: + description: "Name of the reference to check out; takes precedence + over Branch, Tag and SemVer. \n It must be a valid Git reference: + https://git-scm.com/docs/git-check-ref-format#_description Examples: + \"refs/heads/main\", \"refs/tags/v0.1.0\", \"refs/pull/420/head\", + \"refs/merge-requests/1/head\"" + type: string semver: description: SemVer tag expression to check out, takes precedence over Tag. diff --git a/controllers/gitrepository_controller.go b/controllers/gitrepository_controller.go index 9f1d134b2..b93c4ee71 100644 --- a/controllers/gitrepository_controller.go +++ b/controllers/gitrepository_controller.go @@ -787,6 +787,7 @@ func (r *GitRepositoryReconciler) gitCheckout(ctx context.Context, cloneOpts.Commit = ref.Commit cloneOpts.Tag = ref.Tag cloneOpts.SemVer = ref.SemVer + cloneOpts.RefName = ref.Name } // Only if the object has an existing artifact in storage, attempt to diff --git a/docs/api/source.md b/docs/api/source.md index 0725598f9..e5c446075 100644 --- a/docs/api/source.md +++ b/docs/api/source.md @@ -436,8 +436,7 @@ bool (Optional)

RecurseSubmodules enables the initialization of all submodules within -the GitRepository as cloned from the URL, using their default settings. -This option is available only when using the ‘go-git’ GitImplementation.

+the GitRepository as cloned from the URL, using their default settings.

@@ -1671,8 +1670,6 @@ string (Optional)

Branch to check out, defaults to ‘master’ if no other field is defined.

-

When GitRepositorySpec.GitImplementation is set to ‘go-git’, a shallow -clone of the specified branch is performed.

@@ -1701,6 +1698,20 @@ string +name
+ +string + + + +(Optional) +

Name of the reference to check out; takes precedence over Branch, Tag and SemVer.

+

It must be a valid Git reference: https://git-scm.com/docs/git-check-ref-format#_description +Examples: “refs/heads/main”, “refs/tags/v0.1.0”, “refs/pull/420/head”, “refs/merge-requests/1/head”

+ + + + commit
string @@ -1709,9 +1720,8 @@ string (Optional)

Commit SHA to check out, takes precedence over all reference fields.

-

When GitRepositorySpec.GitImplementation is set to ‘go-git’, this can be -combined with Branch to shallow clone the branch, in which the commit is -expected to exist.

+

This can be combined with Branch to shallow clone the branch, in which +the commit is expected to exist.

@@ -1875,8 +1885,7 @@ bool (Optional)

RecurseSubmodules enables the initialization of all submodules within -the GitRepository as cloned from the URL, using their default settings. -This option is available only when using the ‘go-git’ GitImplementation.

+the GitRepository as cloned from the URL, using their default settings.

diff --git a/docs/spec/v1beta2/gitrepositories.md b/docs/spec/v1beta2/gitrepositories.md index 2d82d0d5b..44c7b9777 100644 --- a/docs/spec/v1beta2/gitrepositories.md +++ b/docs/spec/v1beta2/gitrepositories.md @@ -228,7 +228,7 @@ is `60s`. `.spec.ref` is an optional field to specify the Git reference to resolve and watch for changes. References are specified in one or more subfields -(`.branch`, `.tag`, `.semver`, `.commit`), with latter listed fields taking +(`.branch`, `.tag`, `.semver`, `.name`, `.commit`), with latter listed fields taking precedence over earlier ones. If not specified, it defaults to a `master` branch reference. @@ -287,6 +287,30 @@ spec: This field takes precedence over [`.branch`](#branch-example) and [`.tag`](#tag-example). + +#### Name example + +To Git checkout a specfied [reference](https://git-scm.com/book/en/v2/Git-Internals-Git-References), +use `.spec.ref.name`: + +```yaml +--- +apiVersion: source.toolkit.fluxcd.io/v1beta2 +kind: GitRepository +metadata: + name: +spec: + ref: + # Ref name format reference: https://git-scm.com/docs/git-check-ref-format#_description + name: +``` + +Valid examples are: `refs/heads/main`, `refs/tags/v0.1.0`, `refs/pull/420/head`, +`refs/merge-requests/1/head`. + +This field takes precedence over [`.branch`](#branch-example), +[`.tag`](#tag-example), and [`.semver`](#semver-example). + #### Commit example To Git checkout a specified commit, use `.spec.ref.commit`: