[Improvement] Document Git repository requirements

[asbjornu]

Seeing how getting GitVersion to work in different CI servers (Jenkins seems particularly problematic) is a recurring problem, it would be great if we documented GitVersion’s requirements for successfully generating a version number such as:

1. An unshallow clone.
2. An existing local master branch.
3. Possibly an existing local develop branch (for GitFlow).
4. Should be switched to a named, existing branch pointing to the commit being built (i.e. no detached HEAD).
5. Git_Branch as an available environment variable.
6. If using a GitVersion.yml file, that file should be checked out otherwise it won't be found by GitVersion and default config will apply.

Possibly related issues: #1335, #2180, #2118, #2115, #1857, #2233.

[kwaazaar]

Sounds good. And maybe clear examples for the different CI servers.

I'm new to GitVersion, but I see all dev-teams here use different GitVersion.yml files because they're struggling with the options, resulting is messy version numbers and unusable versionnumbers for example for Docker images.

Versioning is important and must be done right. But it should be just a small, one-time set-up task you never have to look at anymore. That's not my experience so far.

(we use Azure DevOps)

[asbjornu]

@kwaazaar, if you use one of the supported Git processes, such as Git flow, the process itself will take care of the versioning and no GitVersion.yml should be required. It's only when you have an undefined or custom process versioning becomes difficult, regardless of whether you use GitVersion or something else as the source of the application's version number.

[dazinator]

I wonder if... shallow fetching can actually be used with certain branches / workflows.

For example, if we use the last tag as the final fallback for a version source, then it might be possible to only fetch back history as far as the last tag? Just a thought.

[asbjornu]

Hm, yeah, that's an interesting thought. git fetch --depth 1 origin tag <tag-name> should suffice for most, I assume. We would have to know the name of the tag to fetch, though.

[dazinator]

@asbjornu I'm not really familiar with shallow cloning. But conceptually I think what we'd need to do (could be mistaken) is fetch all commit history from current HEAD back to the latest tag - so that if current HEAD isn't tagged, we can still walk the commit history to find the previous commit with the tag and use that as the version source, and then each commit after that tag, adds to the commit count that we use to calculate the final version (plus all other logic that we do). I think fetching history further back than that last tag is probably irrelvent?

Is that what git fetch --depth 1 origin tag <tag-name> does - because my interpretation of that was that it was just going to fetch the specified TAG as HEAD, and only include that 1 commit in history - so would be missing all the newer commits since then.. and would only be useful if you were tagging every commit?

I think if we wanted to actually leverage this, we'd need someway of determining what depth should be in this command: git fetch --depth X in order to fetch only as far back as the commit with the last tag.

I'm not sure if there is any clever way to calculate that - however a quick search yielded this:

In order to find the latest Git tag available on your repository, you have to use the “git describe” command with the “–tags” option: https://devconnected.com/how-to-list-git-tags/#List_Remote_Git_Tags

and also this: https://github.com/erasys/git-describe-remote

[dazinator]

Another thought on this requirement

4. A named, existing and checked out branch pointing to the commit being built (i.e. no detached HEAD).

Wondering if we need the entire branch checked out, or if we only need the GitVersion.yml file checkout out (if used). I realise in most cases people will want to be building sources so will most likely want the branch checked out anyway, but I can see in some situations where you are optimising the pipeline you might:

1. Calculate semver variables as fast as possible:
   • Only fetch minimal history needed (i.e shallow clone upto previous tag)
   • Only checkout minimal files necessary (none, or just GitVersion.yml)

On a large repo with lots of files and lots of history those two steps could have decent impact / saving.

From a requirements perspective, I can't think why GitVersion should need any other files checked out?

[asbjornu]

It's not about files, but about Git history. In some calcuation strategies, GitVersion needs the history of the current branch at least up to the commit it was branched out from (typically) develop or master.

[dazinator]

A named, existing and checked out branch

If files aren't needed should "checked out" be a requirement. The only file I can think might be needed is gitversion.yml and that might not be used by everyone so is optional in that sense. If used its possible to do a single file checkout, which might be preferable for jobs that don't build sources, or repo's that contain a lot of files and want to use sparse checkout.

It's possible to set the active branch without checking out files like so:

git symbolic-ref HEAD refs/heads/otherbranch

[asbjornu]

Perhaps "checked out" isn't the right terminology. What I mean is that the branch being built should also be the one Git is switched to.

[dazinator]

@asbjornu - yup that makes more sense - have updated that text

[dazinator]

Would requirement 6) be:

• If using a GitVersion.yml file, that file should be checked out

I am assuming we don't have logic to auto checkout such a file, or find it somehow without checking it out - but I haven't tested.

[asbjornu]

No, we aren't checking out any particular files, the normalization is just to ensure we have history and relevant branches in place. Requirement 6 makes sense, yes.

[dazinator]

Ok cool - added that. Can't think of anything else!

[dazinator]

I lied there was one more thing ;-)

Git_Branch as an available environment variable.

I'm not setting GIT_BRANCH environment variable anywhere and I am using the azure-pipelines task without any problems. Is this a requirement - or is this only required in some circumstances? I remember I used to have to set this for team city builds.

[asbjornu]

I think it's required only in some circumstances, but we haven't documented which. It might be that reuirement 4 and 5 are mutually exclusive.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. After 30 days from now, it will be closed if no further activity occurs. Thank you for your contributions.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. After 30 days from now, it will be closed if no further activity occurs. Thank you for your contributions.

[dazinator]

Nice one @asbjornu !

[arturcic]

🎉 This issue has been resolved in version 5.6.7 🎉
The release is available on:

• GitHub Release
• Chocolatey Package
• .Net Global Tool

Your GitReleaseManager bot 📦🚀