[Feature] New CLI

[asbjornu]

Detailed Description

This issue is our explorations of how the new CLI of GitVersion 6 7 is going to look like.

Design

The new CLI is going to have a command-based style, allowing for more laser-focused and composable execution. We want stdin and stdout to become the default way to both read and write version variables, logging instead to stderr so stdout can be kept as valid JSON throughout.

Since we want to reduce the amount of work being done for each command, GitVersion may have to be executed several times for certain builds, perhaps introducing some latency, but also making it much easier to pinpoint exactly during which step an error occurs so we can fix more easily and users of GitVersion can circumvent and monkey-patch the bugs much more efficiently.

Architecture

The new and more laser-focused command-based CLI allows us to refactor the GitVersion codebase into smaller, more compartementalized parts. This should lead to an almost dependency-free Core with a few optional addon projects that can live their own lives. The API between GitVersion.Core and the addons will be based on the CLI infrastructure we choose. Our current bet is on System.CommandLine.

Addons will be able to add their own commands to GitVersion and besides the Command implementations and arguments they can add to it, they will be able to read the version variables produced by GitVersion as JSON and then perform whatever task they wish. The output from an addon should be JSON written to stdout so different commands can be composed with piping.

Possible Implementation

Below is an example of some of the commands the new CLI may support, with some of their corresponding arguments.

# Write version to stdout
gitversion --version

# Write help to stdout
gitversion --help

# Normalize the repository to its required state:
gitversion normalize 

# Normalize the repository inside `./project/` to its required state:
gitversion normalize --repository ./project/

# Initialize GitVersion.yml
gitversion config init

# Write the effective GitVersion configuration (defaults + custom from GitVersion.yml) in yaml format to stdout
gitversion config show

# Calculate the version number and output to stdout. Only the JSON with the version variables will go to stdout, errors and warnings will be logged to stderr
gitversion calculate

# Calculate the version number and write it gitversion.json
gitversion calculate > gitversion.json

# Calculate the version number and output to stdout. Include logging information depending on the verbosity level in the logging to stderr.
gitversion calculate --verbosity verbose

# Calculate the version number and output to stdout. Include diagnostics info in the logging to stderr (requires `git` executable on PATH).
gitversion [diag] calculate

# Calculate the version number and log to the file `/var/logs/gitversion.log`
gitversion calculate --logfile /var/logs/gitversion.log

# Calculate the version number based on the configuration file `/etc/gitversion.yml`
gitversion calculate --configfile /etc/gitversion.yml

# Calculate the version and override the `tag-prefix` configuration.
gitversion calculate --override-config tag-prefix=foo

# Calculate the version with caching disabled.
gitversion calculate --no-cache

# Read version variables from stdin and write to globbed AssemblyInfo.cs files
cat gitversion.json | gitversion output --type assemblyinfo --path ./**/AssemblyInfo.cs

# Read version variables from stdin and write to globbed .csproj files
cat gitversion.json | gitversion output --type projectfiles --path ./**/*.csproj

# Read version variables from stdin and write to an auto-detected build server. Without an `--in` argument, stdin is the default input.
cat gitversion.json | gitversion output --type buildserver

# Read version variables from stdin and write to Jenkins.
cat gitversion.json | gitversion output --type buildserver --buildserver Jenkins

# Read version variables from stdin and write to globbed .wxi files.
cat gitversion.json | gitversion output --type wix --path ./**/*.wxi

# Read version variables from stdin and output them to environment variables
cat gitversion.json | gitversion output --type environment

# Read version variables from stdin and output only the `FullSemVer` property to stdout.
cat gitversion.json | gitversion output --property FullSemVer 

# Pipe the output of calculate to gitversion output
gitversion calculate | gitversion output --type assemblyinfo --path ./**/AssemblyInfo.cs

#NOTES [diag] can be used only with calculate command

Related Issue

#358, #428, #598, #572.

Motivation and Context

The CLI of GitVersion is a road that has been built as we have walked it, with no planning and no idea of scope or feature set before implementation was started. It has proved difficult to support POSIX file systems due to forward slash / being chosen as the argument separator originally, the argument system doesn't allow for easy documentation generation and perhaps most importantly: Argument parsing is not a core concern of GitVersion, so we're best served to outsource this entire thing to a third-party library.

[dazinator]

For this one, what would overriding multiple config values look like?

gitversion calculate --override-config tag-prefix=foo

[asbjornu]

I think the cleanest is to repeat the argument:

gitversion calculate --override-config tag-prefix=foo --override-config next-version=1.2.3 --override-config mode=Mainline

We might go for colon : instead of equals = to align more with the YAML syntax.

gitversion calculate --override-config tag-prefix:foo --override-config next-version:1.2.3 --override-config mode:Mainline

Not sure.

[arturcic]

@asbjornu I think System.CommandLine supports both : and = https://github.com/dotnet/command-line-api/wiki/Syntax-Concepts-and-Parser#delimiters

[arturcic]

it's up to the user to decide which syntax they prefer. For our docs we'll need to choose one syntax to be consistent

[asbjornu]

Sorry if I wan't entirely clear on where the separator occurs. I meant the separator between the key and the value in the value for the argument --override-config.

Afaict, the separator being discussed is between the argument and its value, i.e. the space between --override-config and tag-prefix:foo. So we could write --override-config:tag-prefix=foo or --override-config=tag-prefix:foo.

But I think tag-prefix:foo and tag-prefix=foo is just seen as one opaque value to System.CommandLine and thus we would have to split the key and value by a chosen delimiter.

[arturcic]

Actually I remember they had a way to parse that too, as the intent is to be able to have something similar to the dotnet build --property:name=value, the way they pass properties to msbuild

[asbjornu]

Neat. Perhaps we should just drop --override-config and go with --tag-prefix=foo anyway? We just need to be sure that none of the configuration properties collide with other arguments. I don't think we have anny collisions now, but if we do, we should take our chance to rename them for v6.