diff --git a/.markdownlint.json b/.markdownlint.json index 08d535e1cb..c5dcebf8d6 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -1,4 +1,5 @@ { "MD026": false, - "MD041": false + "MD041": false, + "MD013": false } diff --git a/BREAKING_CHANGES.md b/BREAKING_CHANGES.md index c6da444ae8..b5696d29fa 100644 --- a/BREAKING_CHANGES.md +++ b/BREAKING_CHANGES.md @@ -1,5 +1,47 @@ ## Unreleased +### CLI Arguments — POSIX-style Syntax + +The command-line interface has been migrated from Windows-style (`/switch` and single-dash `-switch`) arguments to POSIX-style `--long-name` arguments using [System.CommandLine](https://github.com/dotnet/command-line-api). + +**Old-style arguments are no longer accepted by default.** Update any scripts, CI pipelines, or tooling accordingly. + +As a temporary migration aid, set the environment variable `GITVERSION_USE_V6_ARGUMENT_PARSER=true` to restore the legacy `/switch` and `-switch` argument handling. This escape hatch will be removed in a future release. + +#### Full argument mapping + +| Old argument | New argument | Short alias | Env var alternative | +| ----------------------------- | -------------------------------- | ------------------------------ | ---------------------------- | +| `/targetpath ` | `--target-path ` | _(positional `path` argument)_ | | +| `/output ` | `--output ` | `-o` | | +| `/outputfile ` | `--output-file ` | | | +| `/showvariable ` | `--show-variable ` | `-v` | | +| `/format ` | `--format ` | `-f` | | +| `/config ` | `--config ` | `-c` | | +| `/showconfig` | `--show-config` | | | +| `/overrideconfig ` | `--override-config ` | | | +| `/nocache` | `--no-cache` | | | +| `/nofetch` | `--no-fetch` | | | +| `/nonormalize` | `--no-normalize` | | | +| `/allowshallow` | `--allow-shallow` | | | +| `/verbosity ` | `--verbosity ` | | | +| `/l ` | `--log-file ` | `-l` | | +| `/diag` | `--diagnose` | `-d` | | +| `/updateassemblyinfo [files]` | `--update-assembly-info [files]` | | | +| `/updateprojectfiles [files]` | `--update-project-files [files]` | | | +| `/ensureassemblyinfo` | `--ensure-assembly-info` | | | +| `/updatewixversionfile` | `--update-wix-version-file` | | | +| `/url ` | `--url ` | | | +| `/b ` | `--branch ` | `-b` | | +| `/u ` | `--username ` | `-u` | `GITVERSION_REMOTE_USERNAME` | +| `/p ` | `--password ` | `-p` | `GITVERSION_REMOTE_PASSWORD` | +| `/c ` | `--commit ` | _(no short alias)_ | | +| `/dynamicRepoLocation ` | `--dynamic-repo-location ` | | | + +> **Critical**: `-c` previously referred to the commit id. It is now aliased to `--config` (config file path). Any usage of `-c ` must be changed to `--commit `. + +The `GITVERSION_REMOTE_USERNAME` and `GITVERSION_REMOTE_PASSWORD` environment variables can be used as alternatives to `--username` and `--password`. Environment variables take lower precedence than explicit CLI arguments. + ### Logging System Replacement * The custom `ILog` logging abstraction has been replaced with the industry-standard `Microsoft.Extensions.Logging` (M.E.L.) infrastructure using Serilog as the underlying provider. diff --git a/build/build/Tasks/Package/PackagePrepare.cs b/build/build/Tasks/Package/PackagePrepare.cs index 0f32b29f08..430c4fcb3e 100644 --- a/build/build/Tasks/Package/PackagePrepare.cs +++ b/build/build/Tasks/Package/PackagePrepare.cs @@ -39,7 +39,7 @@ private static void PackPrepareNative(BuildContext context) { context.Information("Validating native lib:"); var nativeExe = outputPath.CombineWithFilePath(context.IsOnWindows ? "gitversion.exe" : "gitversion"); - context.ValidateOutput(nativeExe.FullPath, "/showvariable FullSemver", context.Version?.GitVersion?.FullSemVer); + context.ValidateOutput(nativeExe.FullPath, "--show-variable FullSemver", context.Version?.GitVersion?.FullSemVer); } } } diff --git a/build/build/Tasks/ValidateVersion.cs b/build/build/Tasks/ValidateVersion.cs index e88866ffca..5e79d567a1 100644 --- a/build/build/Tasks/ValidateVersion.cs +++ b/build/build/Tasks/ValidateVersion.cs @@ -11,6 +11,6 @@ public override void Run(BuildContext context) { ArgumentNullException.ThrowIfNull(context.Version); var gitVersionTool = context.GetGitVersionToolLocation(); - context.ValidateOutput("dotnet", $"\"{gitVersionTool}\" -version", context.Version.GitVersion.InformationalVersion); + context.ValidateOutput("dotnet", $"\"{gitVersionTool}\" --version", context.Version.GitVersion.InformationalVersion); } } diff --git a/build/common/Addins/GitVersion/GitVersionRunner.cs b/build/common/Addins/GitVersion/GitVersionRunner.cs index 7da7defc4d..d8731abb7c 100644 --- a/build/common/Addins/GitVersion/GitVersionRunner.cs +++ b/build/common/Addins/GitVersion/GitVersionRunner.cs @@ -64,19 +64,19 @@ private ProcessArgumentBuilder GetArguments(GitVersionSettings settings) if (settings.OutputTypes.Contains(GitVersionOutput.Json)) { - builder.Append("-output"); + builder.Append("--output"); builder.Append("json"); } if (settings.OutputTypes.Contains(GitVersionOutput.BuildServer)) { - builder.Append("-output"); + builder.Append("--output"); builder.Append("buildserver"); } if (!string.IsNullOrWhiteSpace(settings.ShowVariable)) { - builder.Append("-showvariable"); + builder.Append("--show-variable"); builder.Append(settings.ShowVariable); } @@ -91,7 +91,7 @@ private ProcessArgumentBuilder GetArguments(GitVersionSettings settings) if (settings.UpdateAssemblyInfo) { - builder.Append("-updateassemblyinfo"); + builder.Append("--update-assembly-info"); if (settings.UpdateAssemblyInfoFilePath != null) { @@ -101,12 +101,12 @@ private ProcessArgumentBuilder GetArguments(GitVersionSettings settings) if (settings.RepositoryPath != null) { - builder.Append("-targetpath"); + builder.Append("--target-path"); builder.AppendQuoted(settings.RepositoryPath.FullPath); } else if (!string.IsNullOrWhiteSpace(settings.Url)) { - builder.Append("-url"); + builder.Append("--url"); builder.AppendQuoted(settings.Url); if (!string.IsNullOrWhiteSpace(settings.Branch)) @@ -122,13 +122,13 @@ private ProcessArgumentBuilder GetArguments(GitVersionSettings settings) if (!string.IsNullOrWhiteSpace(settings.Commit)) { - builder.Append("-c"); + builder.Append("--commit"); builder.AppendQuoted(settings.Commit); } if (settings.DynamicRepositoryPath != null) { - builder.Append("-dynamicRepoLocation"); + builder.Append("--dynamic-repo-location"); builder.AppendQuoted(settings.DynamicRepositoryPath.FullPath); } } @@ -141,14 +141,14 @@ private ProcessArgumentBuilder GetArguments(GitVersionSettings settings) if (settings.NoFetch) { - builder.Append("-nofetch"); + builder.Append("--no-fetch"); } var verbosity = settings.Verbosity ?? this._log.Verbosity; if (verbosity != Verbosity.Normal) { - builder.Append("-verbosity"); + builder.Append("--verbosity"); builder.Append(verbosity.ToString()); } diff --git a/build/common/Utilities/DockerContextExtensions.cs b/build/common/Utilities/DockerContextExtensions.cs index eb8dd85a9d..4ffcd7ce33 100644 --- a/build/common/Utilities/DockerContextExtensions.cs +++ b/build/common/Utilities/DockerContextExtensions.cs @@ -156,7 +156,7 @@ public void DockerTestImage(DockerImage dockerImage) var tags = context.GetDockerTags(dockerImage, dockerImage.Architecture); foreach (var tag in tags) { - context.DockerTestRun(tag, dockerImage.Architecture, "/repo", ["/showvariable", "FullSemver", "/nocache"]); + context.DockerTestRun(tag, dockerImage.Architecture, "/repo", ["--show-variable", "FullSemver", "--no-cache"]); } } diff --git a/docs/input/docs/learn/dynamic-repositories.md b/docs/input/docs/learn/dynamic-repositories.md index 848ac16391..481c490986 100644 --- a/docs/input/docs/learn/dynamic-repositories.md +++ b/docs/input/docs/learn/dynamic-repositories.md @@ -31,15 +31,17 @@ will assume there is already a ".git" folder present, and it will use it. To tell GitVersion.exe to obtain the repository on the fly, you need to call `GitVersion.exe` with the following arguments: -* `/url [the url of your git repo]` -* `/u [authentication username]` -* `/p [authentication password]` -* `/b [branch name]` -* `/c [commit id]` +* `--url [the url of your git repo]` +* `--username [authentication username]` (short alias: `-u`) +* `--password [authentication password]` (short alias: `-p`) +* `--branch [branch name]` (short alias: `-b`) +* `--commit [commit id]` -Please note that these arguments are described when calling `GitVersion.exe /?`. +Long-form arguments are recommended for scripts and documentation. -Also, be aware that if you don't specify the `/b` argument (branch name) then +Please note that these arguments are described when calling `GitVersion.exe --help`. + +Also, be aware that if you don't specify the `--branch` argument (branch name) then GitVersion will currently fallback to targeting whatever the default branch name happens to be for the repo. This could lead to incorrect results, so for that reason it's recommended to always explicitly specify the branch name. diff --git a/docs/input/docs/migration/index.cshtml b/docs/input/docs/migration/index.cshtml new file mode 100644 index 0000000000..29caab1ada --- /dev/null +++ b/docs/input/docs/migration/index.cshtml @@ -0,0 +1,8 @@ +--- +Title: Migration +Description: Technical reference documentation. +Order: 100 +--- +

@Html.Raw(Model.String(DocsKeys.Description))

+ +@Html.Partial("_ChildPages") diff --git a/docs/input/docs/migration/v6-to-v7.md b/docs/input/docs/migration/v6-to-v7.md new file mode 100644 index 0000000000..d9cb1dab09 --- /dev/null +++ b/docs/input/docs/migration/v6-to-v7.md @@ -0,0 +1,80 @@ +--- +Order: 10 +Title: Migration v6 to v7 +Description: Migration guidance for upgrading from GitVersion v6 to GitVersion v7. +--- + +This document summarizes the relevant breaking changes when migrating from GitVersion v6 to v7. + +## CLI Arguments - POSIX-style syntax + +GitVersion now uses POSIX-style command-line arguments powered by System.CommandLine. + +:::{.alert .alert-warning} +**Breaking change:** Legacy Windows-style (`/switch`) and legacy single-dash long-form (`-switch`) arguments are no longer accepted by default. + +As a temporary migration aid, set `GITVERSION_USE_V6_ARGUMENT_PARSER=true` to restore legacy argument handling. This compatibility mode is temporary and will be removed in a future release. +::: + +### What you need to change + +1. Replace old argument names with POSIX-style `--long-name` arguments. +2. Prefer `--long-name` arguments for readability and maintainability. Supported short aliases (`-o`, `-v`, `-f`, `-c`, `-l`, `-d`, `-b`, `-u`, `-p`) remain available for interactive use. +3. Update scripts that used `-c ` to `--commit `. +4. Optionally use `GITVERSION_REMOTE_USERNAME` and `GITVERSION_REMOTE_PASSWORD` instead of passing credentials on the command line. + +### Full argument mapping + +| Old argument | New argument | Short alias | Env var alternative | +| ----------------------------- | -------------------------------- | ------------------------------ | ---------------------------- | +| `/targetpath ` | `--target-path ` | _(positional `path` argument)_ | | +| `/output ` | `--output ` | `-o` | | +| `/outputfile ` | `--output-file ` | | | +| `/showvariable ` | `--show-variable ` | `-v` | | +| `/format ` | `--format ` | `-f` | | +| `/config ` | `--config ` | `-c` | | +| `/showconfig` | `--show-config` | | | +| `/overrideconfig ` | `--override-config ` | | | +| `/nocache` | `--no-cache` | | | +| `/nofetch` | `--no-fetch` | | | +| `/nonormalize` | `--no-normalize` | | | +| `/allowshallow` | `--allow-shallow` | | | +| `/verbosity ` | `--verbosity ` | | | +| `/l ` | `--log-file ` | `-l` | | +| `/diag` | `--diagnose` | `-d` | | +| `/updateassemblyinfo [files]` | `--update-assembly-info [files]` | | | +| `/updateprojectfiles [files]` | `--update-project-files [files]` | | | +| `/ensureassemblyinfo` | `--ensure-assembly-info` | | | +| `/updatewixversionfile` | `--update-wix-version-file` | | | +| `/url ` | `--url ` | | | +| `/b ` | `--branch ` | `-b` | | +| `/u ` | `--username ` | `-u` | `GITVERSION_REMOTE_USERNAME` | +| `/p ` | `--password ` | `-p` | `GITVERSION_REMOTE_PASSWORD` | +| `/c ` | `--commit ` | _(no short alias)_ | | +| `/dynamicRepoLocation ` | `--dynamic-repo-location ` | | | + +:::{.alert .alert-danger} +**Important:** `-c` now maps to `--config`. + +If you previously used `-c `, you must replace it with `--commit `. +::: + +### Example updates + +```bash +# Before +gitversion /output json /showvariable SemVer /config GitVersion.yml + +# After +gitversion --output json --show-variable SemVer --config GitVersion.yml +``` + +```bash +# Before +gitversion /url https://github.com/org/repo.git /b main /u user /p pass /c a1b2c3 + +# After +gitversion --url https://github.com/org/repo.git --branch main --username user --password pass --commit a1b2c3 +``` + +For current command details and examples, see [CLI Arguments](/docs/usage/cli/arguments). diff --git a/docs/input/docs/reference/build-servers/bitbucket-pipelines.md b/docs/input/docs/reference/build-servers/bitbucket-pipelines.md index f2e91f83db..268b94d0a3 100644 --- a/docs/input/docs/reference/build-servers/bitbucket-pipelines.md +++ b/docs/input/docs/reference/build-servers/bitbucket-pipelines.md @@ -28,7 +28,7 @@ pipelines: script: - export PATH="$PATH:/root/.dotnet/tools" - dotnet tool install --global GitVersion.Tool - - dotnet-gitversion /output buildserver + - dotnet-gitversion --output buildserver - source gitversion.properties - echo Building with semver $GITVERSION_FULLSEMVER - dotnet build @@ -41,7 +41,7 @@ You must set the `clone:depth` setting as shown above; without it, BitBucket Pip cause GitVersion to display an error message. ::: -When the action `dotnet-gitversion /output buildserver` is executed, it will detect that it is running in BitBucket Pipelines by the presence of +When the action `dotnet-gitversion --output buildserver` is executed, it will detect that it is running in BitBucket Pipelines by the presence of the `BITBUCKET_WORKSPACE` environment variable, which is set by the BitBucket Pipelines engine. It will generate a text file named `gitversion.properties` which contains all the output of the GitVersion tool, exported as individual environment variables prefixed with `GITVERSION_`. These environment variables can then be imported back into the build step using the `source gitversion.properties` action. @@ -62,7 +62,7 @@ pipelines: script: - export PATH="$PATH:/root/.dotnet/tools" - dotnet tool install --global GitVersion.Tool - - dotnet-gitversion /output buildserver + - dotnet-gitversion --output buildserver artifacts: - gitversion.properties - step: diff --git a/docs/input/docs/reference/build-servers/continua.md b/docs/input/docs/reference/build-servers/continua.md index e2af69c06e..fc3c29253d 100644 --- a/docs/input/docs/reference/build-servers/continua.md +++ b/docs/input/docs/reference/build-servers/continua.md @@ -48,7 +48,7 @@ follow the steps below: * Executable path: $Agent.GitVersion.Path$ * Working directory: %RepositoryPath% * In the `Arguments` tab, set the following values: - * Arguments: /url %RepositoryUrl% /b %RepositoryBranchName% /c %RepositoryCommitId% /output buildserver + * Arguments: --url %RepositoryUrl% --branch %RepositoryBranchName% --commit %RepositoryCommitId% --output buildserver * In the `Options` tab, set the following values: * Wait for completion: checked * Log output: checked diff --git a/docs/input/docs/reference/build-servers/index.cshtml b/docs/input/docs/reference/build-servers/index.cshtml index 9688a560d8..dec0653f25 100644 --- a/docs/input/docs/reference/build-servers/index.cshtml +++ b/docs/input/docs/reference/build-servers/index.cshtml @@ -29,11 +29,11 @@ RedirectFrom:

When the gitVersion executable is run with the - /output buildserver flag instead of outputting JSON, it will + --output buildserver flag instead of outputting JSON, it will export its version variables to the current build server as build-server native variables. For instance if you are running in TeamCity after you run - gitversion /output buildserver you will have the + gitversion --output buildserver you will have the %system.GitVersion.SemVer% variable available for you to use in the rest of the build configuration.

diff --git a/docs/input/docs/reference/build-servers/jenkins.md b/docs/input/docs/reference/build-servers/jenkins.md index 93eb9cb6ab..73923f45f2 100644 --- a/docs/input/docs/reference/build-servers/jenkins.md +++ b/docs/input/docs/reference/build-servers/jenkins.md @@ -31,7 +31,7 @@ To inject the GitVersion variables as environment variables for a build job using [EnvInject][env-inject], do the following: 1. Add an **Execute Windows batch command** build step with _Command_: - `gitversion /output buildserver` + `gitversion --output buildserver` 2. Add an **Inject environment variables** build step and use value 'gitversion.properties' for the _Properties File Path_ parameter @@ -58,7 +58,7 @@ In a pipeline stage: 1. Run GitVersion with the flag for _buildserver_ output (this only works when run from Jenkins, specifically when the `JENKINS_URL` environment variable is defined): ```groovy -sh 'gitversion /output buildserver'` +sh 'gitversion --output buildserver'` ``` 2. Add a script block to read the properties file, assign environment variables as needed: diff --git a/docs/input/docs/reference/build-servers/myget.md b/docs/input/docs/reference/build-servers/myget.md index 895862c2a9..c948bbdee2 100644 --- a/docs/input/docs/reference/build-servers/myget.md +++ b/docs/input/docs/reference/build-servers/myget.md @@ -15,7 +15,7 @@ to leverage GitVersion + GitFlow to produce Semantically Versioned packages. automatically picks up any of the following file names as pre-build script: * `pre-build.(bat|cmd|ps1)` * `pre-myget.(bat|cmd|ps1)` -* Run `GitVersion /output buildserver`: this will cause MyGet Build Services to +* Run `GitVersion --output buildserver`: this will cause MyGet Build Services to set the current `%PackageVersion%` value to the NuGet-compatible SemVer generated by GitVersion and apply this [MyGet Environment Variable](https://docs.myget.org/docs/reference/build-services#Available_Environment_Variables) wherever it is used during the build process. @@ -28,7 +28,7 @@ If you require the `AssemblyInfo.cs` files in your project to be patched with the information from GitVersion, you will have to run it manually, for example using the command: -`call %GitVersion% /updateassemblyinfo true`. +`call %GitVersion% --update-assembly-info true`. ::: Also check [docs.myget.org](https://docs.myget.org/docs/reference/build-services#GitVersion_and_Semantic_Versioning) diff --git a/docs/input/docs/reference/build-servers/octopus-deploy.md b/docs/input/docs/reference/build-servers/octopus-deploy.md index e7d50ff3e0..f7054ae549 100644 --- a/docs/input/docs/reference/build-servers/octopus-deploy.md +++ b/docs/input/docs/reference/build-servers/octopus-deploy.md @@ -106,7 +106,7 @@ if ($pendingChanges -ne $null) & git merge origin/main --ff-only # Determine version to release -$output = & $gitversion /output json +$output = & $gitversion --output json $versionInfoJson = $output -join "`n" $versionInfo = $versionInfoJson | ConvertFrom-Json @@ -146,7 +146,7 @@ $gitversion = "tools\GitVersion\GitVersion.exe" $octo = "tools\Octo\Octo.exe" $nuget = "tools\NuGet\NuGet.exe" # Calculate version -$output = & $gitversion /output json /l GitVersion.log /updateAssemblyInfo /nofetch +$output = & $gitversion --output json --log-file GitVersion.log --update-assembly-info --no-fetch if ($LASTEXITCODE -ne 0) { Write-Verbose "$output" throw "GitVersion Exit Code: $LASTEXITCODE" diff --git a/docs/input/docs/reference/build-servers/teamcity.md b/docs/input/docs/reference/build-servers/teamcity.md index 60f84f5129..f710b06ec1 100644 --- a/docs/input/docs/reference/build-servers/teamcity.md +++ b/docs/input/docs/reference/build-servers/teamcity.md @@ -12,7 +12,7 @@ In [TeamCity][teamcity] you can create a build step as follows: * **Runner type:** Command Line * **Run:** Executable with parameters * **Command executable:** `GitVersion.exe` -* **Command parameters:** `/output buildserver /updateassemblyinfo true` +* **Command parameters:** `--output buildserver --update-assembly-info true` Then in your build parameters simply [add a placeholder](#nuget-in-teamcity) of the GitVersion variables you would like to use. diff --git a/docs/input/docs/reference/configuration.md b/docs/input/docs/reference/configuration.md index 2a1350176f..3bcb4c4faf 100644 --- a/docs/input/docs/reference/configuration.md +++ b/docs/input/docs/reference/configuration.md @@ -19,7 +19,7 @@ The `develop` branch is set to `ContinuousDeployment` mode by default as we have found that is generally what is needed when using GitFlow. To see the effective configuration (defaults and overrides), you can run -`gitversion /showConfig`. +`gitversion --show-config`. ## Global configuration diff --git a/docs/input/docs/reference/mdsource/configuration.source.md b/docs/input/docs/reference/mdsource/configuration.source.md index 8c745a16d3..1a3afa1a00 100644 --- a/docs/input/docs/reference/mdsource/configuration.source.md +++ b/docs/input/docs/reference/mdsource/configuration.source.md @@ -19,7 +19,7 @@ The `develop` branch is set to `ContinuousDeployment` mode by default as we have found that is generally what is needed when using GitFlow. To see the effective configuration (defaults and overrides), you can run -`gitversion /showConfig`. +`gitversion --show-config`. ## Global configuration diff --git a/docs/input/docs/usage/cli/arguments.md b/docs/input/docs/usage/cli/arguments.md index d873130986..8198325495 100644 --- a/docs/input/docs/usage/cli/arguments.md +++ b/docs/input/docs/usage/cli/arguments.md @@ -5,14 +5,17 @@ Description: The supported arguments of the GitVersion Command Line Interface --- :::{.alert .alert-info} -**Hint:** While documentation and help use `/` as command prefix the hyphen `-` -is supported as well and is a better alternative for usage on \*nix systems. -Example: `-output json` vs. `/output json` +**Note:** GitVersion uses POSIX-style `--long-name` arguments from version 7 and up. Long-form +arguments are recommended for readability in scripts and documentation. Short aliases +(e.g. `-l`, `-o`, `-b`) are also supported. The legacy `/switch` and `-switch` +syntax is still available when `GITVERSION_USE_V6_ARGUMENT_PARSER=true` is set. + +See [Migration v6 to v7](/docs/migration/v6-to-v7) for upgrade guidance and the full argument mapping. ::: ## Help -Below is the output from `gitversion /help` as a best effort to provide +Below is the output from `gitversion --help` as a best effort to provide documentation for which arguments GitVersion supports and their meaning. ```bash @@ -23,56 +26,59 @@ GitVersion [path] path The directory containing .git. If not defined current directory is used. (Must be first argument) - /version Displays the version of GitVersion - /diag Runs GitVersion with additional diagnostic information; - also needs the '/l' argument to specify a logfile or stdout - (requires git.exe to be installed) - /h or /? Shows Help - - /targetpath Same as 'path', but not positional - /output Determines the output to the console. Can be either 'json', + --version Displays the version of GitVersion + --diagnose, -d Runs GitVersion with additional diagnostic information; + also needs the '--log-file' argument to specify a logfile + or stdout (requires git.exe to be installed) + --help, -h Shows Help + + --target-path Same as 'path', but not positional + --output, -o Determines the output to the console. Can be either 'json', 'file', 'buildserver' or 'dotenv', will default to 'json'. - /outputfile Path to output file. It is used in combination with /output - 'file'. - /showvariable Used in conjunction with /output json, will output just a - particular variable. E.g. /output json /showvariable SemVer + --output-file Path to output file. It is used in combination with + --output 'file'. + --show-variable, -v + Used in conjunction with --output json, will output just a + particular variable. + E.g. --output json --show-variable SemVer - will output `1.2.3+beta.4` - /format Used in conjunction with /output json, will output a format + --format, -f Used in conjunction with --output json, will output a format containing version variables. Supports C# format strings - see [Format Strings](/docs/reference/custom-formatting) for details. - E.g. /output json /format {SemVer} - will output `1.2.3+beta.4` - /output json /format {Major}.{Minor} - will output `1.2` - /l Path to logfile; specify 'console' to emit to stdout. - /config Path to config file (defaults to GitVersion.yml, GitVersion.yaml, .GitVersion.yml or .GitVersion.yaml) - /showconfig Outputs the effective GitVersion config (defaults + custom + E.g. --output json --format {SemVer} - will output `1.2.3+beta.4` + --output json --format {Major}.{Minor} - will output `1.2` + --log-file, -l Path to logfile; specify 'console' to emit to stdout. + --config, -c Path to config file (defaults to GitVersion.yml, GitVersion.yaml, .GitVersion.yml or .GitVersion.yaml) + --show-config Outputs the effective GitVersion config (defaults + custom from GitVersion.yml, GitVersion.yaml, .GitVersion.yml or .GitVersion.yaml) in yaml format - /overrideconfig Overrides GitVersion config values inline (semicolon- - separated key value pairs e.g. /overrideconfig + --override-config + Overrides GitVersion config values inline (semicolon- + separated key value pairs e.g. --override-config tag-prefix=Foo) Currently supported config overrides: tag-prefix - /nocache Bypasses the cache, result will not be written to the cache. - /nonormalize Disables normalize step on a build server. - /allowshallow Allows GitVersion to run on a shallow clone. + --no-cache Bypasses the cache, result will not be written to the cache. + --no-normalize Disables normalize step on a build server. + --allow-shallow Allows GitVersion to run on a shallow clone. This is not recommended, but can be used if you are sure that the shallow clone contains all the information needed to calculate the version. - /verbosity Specifies the amount of information to be displayed. + --verbosity Specifies the amount of information to be displayed. (Quiet, Minimal, Normal, Verbose, Diagnostic) Default is Normal # AssemblyInfo updating - /updateassemblyinfo + --update-assembly-info Will recursively search for all 'AssemblyInfo.cs' files in the git repo and update them - /updateprojectfiles + --update-project-files Will recursively search for all project files (.csproj/.vbproj/.fsproj/.sqlproj) files in the git repo and update them Note: This is only compatible with the newer Sdk projects - /ensureassemblyinfo + --ensure-assembly-info If the assembly info file specified with - /updateassemblyinfo is not + --update-assembly-info is not found, it will be created with these attributes: AssemblyFileVersion, AssemblyVersion and AssemblyInformationalVersion. @@ -80,33 +86,33 @@ GitVersion [path] # Create or update Wix version file - /updatewixversionfile + --update-wix-version-file All the GitVersion variables are written to 'GitVersion_WixVersion.wxi'. The variables can then be referenced in other WiX project files for versioning. # Remote repository args - /url Url to remote git repository. - /b Name of the branch to use on the remote repository, must be - used in combination with /url. - /u Username in case authentication is required. - /p Password in case authentication is required. - /c The commit id to check. If not specified, the latest + --url Url to remote git repository. + --branch, -b Name of the branch to use on the remote repository, must be + used in combination with --url. + --username, -u Username in case authentication is required. + --password, -p Password in case authentication is required. + --commit The commit id to check. If not specified, the latest available commit on the specified branch will be used. - /dynamicRepoLocation + --dynamic-repo-location By default dynamic repositories will be cloned to %tmp%. Use this switch to override - /nofetch Disables 'git fetch' during version calculation. Might cause + --no-fetch Disables 'git fetch' during version calculation. Might cause GitVersion to not calculate your version as expected. ``` ## Override config -`/overrideconfig [key=value]` will override appropriate `key` from 'GitVersion.yml', 'GitVersion.yaml', '.GitVersion.yml' or '.GitVersion.yaml'. +`--override-config key=value` will override appropriate `key` from 'GitVersion.yml', 'GitVersion.yaml', '.GitVersion.yml' or '.GitVersion.yaml'. -To specify multiple options add multiple `/overrideconfig [key=value]` entries: -`/overrideconfig key1=value1 /overrideconfig key2=value2`. +To specify multiple options add multiple `--override-config key=value` entries: +`--override-config key1=value1 --override-config key2=value2`. To have **space characters** as a part of `value`, `value` has be enclosed with double quotes - `key="My value"`. @@ -139,28 +145,28 @@ Using `override-config` on the command line will not change the contents of the ### Example: How to override configuration option 'tag-prefix' to use prefix 'custom' -`GitVersion.exe /output json /overrideconfig tag-prefix=custom` +`GitVersion.exe --output json --override-config tag-prefix=custom` ### Example: How to override configuration option 'assembly-versioning-format' -`GitVersion.exe /output json /overrideconfig assembly-versioning-format="{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER ?? 0}"` +`GitVersion.exe --output json --override-config assembly-versioning-format="{Major}.{Minor}.{Patch}.{env:BUILD_NUMBER ?? 0}"` Will pickup up environment variable `BUILD_NUMBER` or fallback to zero for assembly revision number. ### Example: How to override configuration option 'assembly-versioning-scheme' -`GitVersion.exe /output json /overrideconfig assembly-versioning-scheme=MajorMinor` +`GitVersion.exe --output json --override-config assembly-versioning-scheme=MajorMinor` Will use only major and minor version numbers for assembly version. Assembly build and revision numbers will be 0 (e.g. `1.2.0.0`) ### Example: How to override multiple configuration options -`GitVersion.exe /output json /overrideconfig tag-prefix=custom /overrideconfig assembly-versioning-scheme=MajorMinor` +`GitVersion.exe --output json --override-config tag-prefix=custom --override-config assembly-versioning-scheme=MajorMinor` ### Example: How to override configuration option 'update-build-number' -`GitVersion.exe /output json /overrideconfig update-build-number=true` +`GitVersion.exe --output json --override-config update-build-number=true` ### Example: How to override configuration option 'next-version' -`GitVersion.exe /output json /overrideconfig next-version=6` +`GitVersion.exe --output json --override-config next-version=6` diff --git a/docs/input/docs/usage/cli/assembly-patch.md b/docs/input/docs/usage/cli/assembly-patch.md index 94509e65c8..f8ec0ee58c 100644 --- a/docs/input/docs/usage/cli/assembly-patch.md +++ b/docs/input/docs/usage/cli/assembly-patch.md @@ -6,7 +6,7 @@ Description: | assemblies --- -`GitVersion.exe /updateassemblyinfo` will recursively search for all +`GitVersion.exe --update-assembly-info` will recursively search for all `AssemblyInfo.cs` or `AssemblyInfo.vb` files in the git repo and update them. It will update the following assembly attributes: @@ -20,13 +20,13 @@ Note that contrary to when using the [MSBuild Task][msbuild-task] the attributes must already exist in the `AssemblyInfo.cs` or `AssemblyInfo.vb` files prior to calling GitVersion. -By adding `/updateassemblyinfo ` the name of AssemblyInfo file to +By adding `--update-assembly-info ` the name of AssemblyInfo file to update can be set. This switch can accept multiple files with the path to the file specified relative to the working directory. GitVersion can generate an assembly info source file for you if it does not -already exist. Use the `/ensureassemblyinfo` switch alongside -`/updateassemblyinfo `, if the filename specified does not exist it +already exist. Use the `--ensure-assembly-info` switch alongside +`--update-assembly-info `, if the filename specified does not exist it will be generated based on a known template that adds: * `AssemblyVersion` will be set to the `AssemblySemVer` variable. @@ -38,45 +38,45 @@ will be generated based on a known template that adds: This can be done for \*.cs, \*.vb and \*.fs files. When requesting that GitVersion generate an assembly info file you are limited -to only specifying a single `` within the `/updateassemblyinfo` +to only specifying a single `` within the `--update-assembly-info` switch, this is to prevent the creation of multiple assembly info files with the same assembly version attributes. If this occurs your build will fail. ## Example: When AssemblyInfo.cs does not exist -`GitVersion.exe /updateassemblyinfo AssemblyInfo.cs /ensureassemblyinfo` +`GitVersion.exe --update-assembly-info AssemblyInfo.cs --ensure-assembly-info` A file is generated that contains version attributes (`AssemblyVersion`, `AssemblyFileVersion`, `AssemblyInformationalVersion`) ## Example: When AssemblyInfo.cs already exists -`GitVersion.exe /updateassemblyinfo AssemblyInfo.cs /ensureassemblyinfo` +`GitVersion.exe --update-assembly-info AssemblyInfo.cs --ensure-assembly-info` All known attributes (`AssemblyVersion`, `AssemblyFileVersion`, `AssemblyInformationalVersion`) will be updated ## Example: When AssemblyInfo.cs and AssemblyVersionInfo.cs do not exist -`GitVersion.exe /updateassemblyinfo AssemblyInfo.cs AssemblyVersionInfo.cs /ensureassemblyinfo` +`GitVersion.exe --update-assembly-info AssemblyInfo.cs AssemblyVersionInfo.cs --ensure-assembly-info` Will result in command line argument error ## Example: When AssemblyInfo.cs and AssemblyVersionInfo.cs already exist -`GitVersion.exe /updateassemblyinfo AssemblyInfo.cs AssemblyVersionInfo.cs` +`GitVersion.exe --update-assembly-info AssemblyInfo.cs AssemblyVersionInfo.cs` Will iterate through each file and update known attributes (`AssemblyVersion`, `AssemblyFileVersion`, `AssemblyInformationalVersion`). ## Example: How to override configuration option 'tag-prefix' to use prefix 'custom' -`GitVersion.exe /output json /overrideconfig tag-prefix=custom` +`GitVersion.exe --output json --override-config tag-prefix=custom` ## Writing version metadata in WiX format To support integration with WiX projects, use `GitVersion.exe -/updatewixversionfile`. All the [variables][variables] are written to +--update-wix-version-file`. All the [variables][variables] are written to `GitVersion_WixVersion.wxi` under the current working directory and can be referenced in the WiX project files. diff --git a/docs/input/docs/usage/cli/installation.md b/docs/input/docs/usage/cli/installation.md index 96340743e9..f9409e0b61 100644 --- a/docs/input/docs/usage/cli/installation.md +++ b/docs/input/docs/usage/cli/installation.md @@ -101,9 +101,8 @@ enter the following into a terminal: brew install gitversion ``` -Switches are available with `gitversion -h`. Even though the documentation -uses a slash `/` for all switches, you need to use a dash `-` instead, since `/` -is interpreted as a root path on POSIX based operating systems. +Arguments are available with `gitversion --help` (short alias `-h` is also supported). +Long-form arguments are recommended in scripts and documentation. This should work on all operating systems supported by Homebrew (at the time of writing: Linux and macOS). @@ -139,7 +138,7 @@ The important arguments here are: | `/repo` | The directory within the Docker container GitVersion should use as its working directory. Don't change this. | :::{.alert .alert-warning} -**Caveat:** The `/output buildserver` option doesn't work universally with +**Caveat:** The `--output buildserver` option doesn't work universally with Docker since environment variables defined inside the Docker container will not be exposed to the host OS. ::: diff --git a/docs/input/docs/usage/cli/output.md b/docs/input/docs/usage/cli/output.md index e8cdaf051d..c20eecb21b 100644 --- a/docs/input/docs/usage/cli/output.md +++ b/docs/input/docs/usage/cli/output.md @@ -9,7 +9,7 @@ By default GitVersion returns a json object to stdout containing all the great if you want to get your build scripts to parse the json object then use the variables, but there is a simpler way. -`GitVersion.exe /output buildserver` will change the mode of GitVersion to write +`GitVersion.exe --output buildserver` will change the mode of GitVersion to write out the variables to whatever build server it is running in. You can then use those variables in your build scripts or run different tools to create versioned NuGet packages or whatever you would like to do. See [build @@ -17,21 +17,21 @@ servers](/docs/reference/build-servers) for more information about this. You can even store the [variables](/docs/reference/variables) in a Dotenv file and load it to have the variables available in your environment. -For that you have to run `GitVersion.exe /output dotenv` and store the output +For that you have to run `GitVersion.exe --output dotenv` and store the output into e.g. a `gitversion.env` file. These files can also be passed around in CI environments like [GitHub](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#passing-values-between-steps-and-jobs-in-a-workflow) or [GitLab](https://docs.gitlab.com/ee/ci/variables/#pass-an-environment-variable-to-another-job). Below are some examples of using the Dotenv format in the Unix command line: ```bash # Output version variables in Dotenv format -gitversion /output dotenv +gitversion --output dotenv # Show only a subset of the version variables in Dotenv format -gitversion /output dotenv | grep -i "prerelease" +gitversion --output dotenv | grep -i "prerelease" # Show only a subset of the version variables that match the regex in Dotenv format -gitversion /output dotenv | grep -iE "major|sha=|_prerelease" +gitversion --output dotenv | grep -iE "major|sha=|_prerelease" # Write version variables in Dotenv format into a file -gitversion /output dotenv > gitversion.env +gitversion --output dotenv > gitversion.env ``` diff --git a/src/.run/cli (help).run.xml b/src/.run/cli (help - new).run.xml similarity index 86% rename from src/.run/cli (help).run.xml rename to src/.run/cli (help - new).run.xml index a8457356e3..8639188b7d 100644 --- a/src/.run/cli (help).run.xml +++ b/src/.run/cli (help - new).run.xml @@ -1,7 +1,7 @@ - +