add support for checking out to Git refs

Add a new field `.spec.ref.name` which points to a Git reference which
enables checking out to a particular commit pointed to by the specified
reference.

Signed-off-by: Sanskar Jaiswal <jaiswalsanskar078@gmail.com>

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
+	// This can be combined with Branch to shallow clone the branch, in which
-	// combined with Branch to shallow clone the branch, in which the commit is
+	// the commit is expected to exist.
-	// expected to exist.
 	// +optional
 	Commit string `json:"commit,omitempty"`
 }

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'
+                  settings.
-                  GitImplementation.
                 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
+                    description: Branch to check out, defaults to 'master' if no other
-                      other field is defined. \n When GitRepositorySpec.GitImplementation
+                      field is defined.
-                      is set to 'go-git', a shallow clone of the specified branch
-                      is performed."
                     type: string
                   commit:
                     description: "Commit SHA to check out, takes precedence over all
-                      reference fields. \n When GitRepositorySpec.GitImplementation
+                      reference fields. \n This can be combined with Branch to shallow
-                      is set to 'go-git', 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.

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

docs/api/source.md

@@ -436,8 +436,7 @@ bool
 <td>
 <em>(Optional)</em>
 <p>RecurseSubmodules enables the initialization of all submodules within
-the GitRepository as cloned from the URL, using their default settings.
+the GitRepository as cloned from the URL, using their default settings.</p>
-This option is available only when using the &lsquo;go-git&rsquo; GitImplementation.</p>
 </td>
 </tr>
 <tr>
@@ -1671,8 +1670,6 @@ string
 <td>
 <em>(Optional)</em>
 <p>Branch to check out, defaults to &lsquo;master&rsquo; if no other field is defined.</p>
-<p>When GitRepositorySpec.GitImplementation is set to &lsquo;go-git&rsquo;, a shallow
-clone of the specified branch is performed.</p>
 </td>
 </tr>
 <tr>
@@ -1701,6 +1698,20 @@ string
 </tr>
 <tr>
 <td>
+<code>name</code><br>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Name of the reference to check out; takes precedence over Branch, Tag and SemVer.</p>
+<p>It must be a valid Git reference: <a href="https://git-scm.com/docs/git-check-ref-format#_description">https://git-scm.com/docs/git-check-ref-format#_description</a>
+Examples: &ldquo;refs/heads/main&rdquo;, &ldquo;refs/tags/v0.1.0&rdquo;, &ldquo;refs/pull/420/head&rdquo;, &ldquo;refs/merge-requests/1/head&rdquo;</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>commit</code><br>
 <em>
 string
@@ -1709,9 +1720,8 @@ string
 <td>
 <em>(Optional)</em>
 <p>Commit SHA to check out, takes precedence over all reference fields.</p>
-<p>When GitRepositorySpec.GitImplementation is set to &lsquo;go-git&rsquo;, this can be
+<p>This can be combined with Branch to shallow clone the branch, in which
-combined with Branch to shallow clone the branch, in which the commit is
+the commit is expected to exist.</p>
-expected to exist.</p>
 </td>
 </tr>
 </tbody>
@@ -1875,8 +1885,7 @@ bool
 <td>
 <em>(Optional)</em>
 <p>RecurseSubmodules enables the initialization of all submodules within
-the GitRepository as cloned from the URL, using their default settings.
+the GitRepository as cloned from the URL, using their default settings.</p>
-This option is available only when using the &lsquo;go-git&rsquo; GitImplementation.</p>
 </td>
 </tr>
 <tr>

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: <repository-name>
+spec:
+  ref:
+    # Ref name format reference: https://git-scm.com/docs/git-check-ref-format#_description
+    name: <reference-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`: