git: support checking out an initial revision which is not modified later

[bugfood]

Use Case

I want to be able to provide a repository working copy to a target host such that:

1. When created, the working copy is set to a specified revision.
2. If a user manually modifies the revision of the working copy on the host, subsequent puppet runs will not alter the revision.

This is conceptually the same as providing the initial contents of a file by:

file { '/path/to/foo':
  ensure => 'file',
  contents => 'bar',
  replace => false,
}

As far as I can tell, vcsrepo supports this only partially.

• If revision is omitted (or set to 'HEAD'), the initial git clone sets the working copy to the upstream repo's default branch; subsequent runs do not modify the working copy's revision. Thus, this only works if the desired initial revision matches the upstream repo's default branch.
• If revision is specified, then the specified revision is set correctly, but subsequent runs insist on changing the repo to that revision. Thus, this does not allow manual modification of the working copy's revision.

Describe the Solution You Would Like

Option 1

Add a new string parameter initial_revision which, when present, overrides revision only at the time of initial creation. The revision parameter may then be omitted or set to 'HEAD' in order to prevent vcsrepo from changing the revision later.

This option has a drawback of allowing a situation which is almost certainly a mistake:

  initial_revision => 'branch-foo',
  revision => 'branch-bar',

...which would cause subsequent puppet runs to alter the revision.

Option 2

Add a new boolean parameter enforce_revision, defaulting to true. This parameter may then be set to false in order to prevent vcsrepo from changing the revision later.

Describe Alternatives You've Considered

I don't know of any alternatives.

Additional Context

Puppet code (test.pp):

vcsrepo { '/tmp/repo':
  ensure => 'present',
  provider => 'git',
  revision => 'main',
  source => 'https://github.com/puppetlabs/puppetlabs-vcsrepo.git',
}

Steps to reproduce:

sudo puppet apply test.pp
sudo git -C /tmp/repo checkout @^
sudo puppet apply test.pp

Observe:

Notice: /Stage[main]/Main/Vcsrepo[/tmp/repo]/revision: revision changed 'b82414b990ed614c6c53445481b947b2dcdfc126' to 'main'
Notice: Applied catalog in 0.67 seconds

Normally, this is desired behavior, but I would like to be able to override that.

Thanks,
Corey