Source controller fails to clone when specifying just the revision (and default branch `main` at origin)

[squaremo]

If I create a GitRepository with a spec like this:

spec:
  url: https://github.com/squaremo/flux2-example
  ref:
    commit: 92f0a9e59583732a052178427e376b77ae9e248b

then the source controller fails to clone the repo. Naively, I would expect it to do the equivalent of

git clone --no-checkout https://github.com/squaremo/flux2-example
cd flux2-example; git checkout 92f0a9e59583732a052178427e376b77ae9e248b

Unfortunately, the .branch field has a default of master, and the checkout code checks out the branch first, then the commit (whether or not it's on the branch, so far as I can tell). This seems like a needless step; but it also means you can't specify just a commit, you have to name a branch that exists at the origin, otherwise it'll fail.

[jonathan-innis]

@squaremo interested in picking this one up

[jonathan-innis]

This can be achieved in a fairly straight-forward way. A question about UX:

• The return from the branch step typically returns the branch; however, there's a roundabout way to achieve this with commit as we essentially have to iterate over the branches to get the branch that contains the commit. If the branch name isn't strictly needed we can avoid this

[stefanprodan]

The ref.commit field is for pinning a branch, I would not break the <branch>/<commit> revision format as users depend on it to confirm syncs are working via flux commands, events and notifications. If we remove the branch/tag from the revision string, then we will not be able to expose vars like GIT_BRANCH and GIT_TAG that users are asking for.

[squaremo]

The ref.commit field is for pinning a branch

How do I target a commit without knowing or caring which branch it's on?

Why would I want to do this -- I'm treating GitRepository as a compilation target, i.e., it is constructed by another controller. It's not the end of the world if that controller has to supply a branch, it just complicates using sourcev1 as an API, since that has to be traced through the layers above which don't otherwise need it.

as users depend on it to confirm syncs are working via flux commands, events and notifications

Are people parsing that field? It seems like a mistake to encourage that, since it's brittle.

we will not be able to expose vars like GIT_BRANCH and GIT_TAG that users are asking for

Presumably if you ask for a branch, then GIT_TAG is not set, and if you ask for a tag, GIT_BRANCH is not set. This is like those situations, except you haven't asked for either of a branch or tag.

[stefanprodan]

@squaremo my point is that if both the branch and the commit are specified, we should set the revision as <branch>/<commit>, if the commit doesn't exists in the specified branch we should error out. I'm ok with setting the revision to <commit> only if the branch is not present in the definition.

[squaremo]

my point is that if both the branch and the commit are specified, we should set the revision as <branch>/<commit>

OK yes I see, that makes sense.

if the commit doesn't exists in the specified branch we should error out

This also makes sense -- does it do this now though? I suspect not, since it clones with the branch then does a checkout of the commit.

[hiddeco]

does it do this now though? I suspect not, since it clones with the branch then does a checkout of the commit.

It does, just ran into this while working on kustomize-controller tests:

  ref:
    branch: main
    commit: 16e375850ade4e5c77cc5ad37d0b643ff9aca44c

results in: git commit '16e375850ade4e5c77cc5ad37d0b643ff9aca44c' not found: object not found

While

  ref:
    branch: age-encryption
    commit: 16e375850ade4e5c77cc5ad37d0b643ff9aca44c

gives back: Fetched revision: age-encryption/16e375850ade4e5c77cc5ad37d0b643ff9aca44c

[squaremo]

It does [...]

I stand corrected :-)

[simongottschlag]

What we are talking about is using a detached head, maybe we could specify this using a boolean (detachedHead: true, defaults to false) and when using it we skip the branch checkout?

The ref could maybe be in the format detachedHead/checksum?

[squaremo]

What we are talking about is using a detached head, maybe we could specify this using a boolean (detachedHead: true, defaults to false) and when using it we skip the branch checkout?

Whether or not you check out the branch first, once you checkout a commit it's a detached head.

[simongottschlag]

As per Slack with @squaremo (https://cloud-native.slack.com/archives/C01A402P0R2/p1617451966151300) a boolean is redundant.