Adopt POSIX-style CLI arguments

.markdownlint.json

@@ -1,4 +1,5 @@
 {
     "MD026": false,
-    "MD041": false
+    "MD041": false,
+    "MD013": false
 }

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 <path>`          | `--target-path <path>`           | _(positional `path` argument)_ |                              |
+| `/output <type>`              | `--output <type>`                | `-o`                           |                              |
+| `/outputfile <path>`          | `--output-file <path>`           |                                |                              |
+| `/showvariable <var>`         | `--show-variable <var>`          | `-v`                           |                              |
+| `/format <format>`            | `--format <format>`              | `-f`                           |                              |
+| `/config <path>`              | `--config <path>`                | `-c`                           |                              |
+| `/showconfig`                 | `--show-config`                  |                                |                              |
+| `/overrideconfig <k=v>`       | `--override-config <k=v>`        |                                |                              |
+| `/nocache`                    | `--no-cache`                     |                                |                              |
+| `/nofetch`                    | `--no-fetch`                     |                                |                              |
+| `/nonormalize`                | `--no-normalize`                 |                                |                              |
+| `/allowshallow`               | `--allow-shallow`                |                                |                              |
+| `/verbosity <level>`          | `--verbosity <level>`            |                                |                              |
+| `/l <path>`                   | `--log-file <path>`              | `-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>`                  | `--url <url>`                    |                                |                              |
+| `/b <branch>`                 | `--branch <branch>`              | `-b`                           |                              |
+| `/u <username>`               | `--username <username>`          | `-u`                           | `GITVERSION_REMOTE_USERNAME` |
+| `/p <password>`               | `--password <password>`          | `-p`                           | `GITVERSION_REMOTE_PASSWORD` |
+| `/c <commit>`                 | `--commit <commit>`              | _(no short alias)_             |                              |
+| `/dynamicRepoLocation <path>` | `--dynamic-repo-location <path>` |                                |                              |
+
+> **Critical**: `-c` previously referred to the commit id. It is now aliased to `--config` (config file path). Any usage of `-c <commit-id>` must be changed to `--commit <commit-id>`.
+
+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.

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);
             }
         }
     }

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);
     }
 }

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());
         }
 

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"]);
             }
         }
 

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.

docs/input/docs/migration/index.cshtml

@@ -0,0 +1,8 @@
+---
+Title: Migration
+Description: Technical reference documentation.
+Order: 100
+---
+<p>@Html.Raw(Model.String(DocsKeys.Description))</p>
+
+@Html.Partial("_ChildPages")

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 <commit>` to `--commit <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 <path>`          | `--target-path <path>`           | _(positional `path` argument)_ |                              |
+| `/output <type>`              | `--output <type>`                | `-o`                           |                              |
+| `/outputfile <path>`          | `--output-file <path>`           |                                |                              |
+| `/showvariable <var>`         | `--show-variable <var>`          | `-v`                           |                              |
+| `/format <format>`            | `--format <format>`              | `-f`                           |                              |
+| `/config <path>`              | `--config <path>`                | `-c`                           |                              |
+| `/showconfig`                 | `--show-config`                  |                                |                              |
+| `/overrideconfig <k=v>`       | `--override-config <k=v>`        |                                |                              |
+| `/nocache`                    | `--no-cache`                     |                                |                              |
+| `/nofetch`                    | `--no-fetch`                     |                                |                              |
+| `/nonormalize`                | `--no-normalize`                 |                                |                              |
+| `/allowshallow`               | `--allow-shallow`                |                                |                              |
+| `/verbosity <level>`          | `--verbosity <level>`            |                                |                              |
+| `/l <path>`                   | `--log-file <path>`              | `-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>`                  | `--url <url>`                    |                                |                              |
+| `/b <branch>`                 | `--branch <branch>`              | `-b`                           |                              |
+| `/u <username>`               | `--username <username>`          | `-u`                           | `GITVERSION_REMOTE_USERNAME` |
+| `/p <password>`               | `--password <password>`          | `-p`                           | `GITVERSION_REMOTE_PASSWORD` |
+| `/c <commit>`                 | `--commit <commit>`              | _(no short alias)_             |                              |
+| `/dynamicRepoLocation <path>` | `--dynamic-repo-location <path>` |                                |                              |
+
+:::{.alert .alert-danger}
+**Important:** `-c` now maps to `--config`.
+
+If you previously used `-c <commit-id>`, you must replace it with `--commit <commit-id>`.
+:::
+
+### 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).

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:

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

docs/input/docs/reference/build-servers/index.cshtml

@@ -29,11 +29,11 @@ RedirectFrom:
 
 <p>
     When the <code>gitVersion</code> executable is run with the
-    <code>/output buildserver</code> flag instead of outputting JSON, it will
+    <code>--output buildserver</code> flag instead of outputting JSON, it will
     export its <a href="/docs/reference/variables">version variables</a> to the
     current build server as build-server native variables. For instance if you
     are running in TeamCity after you run
-    <code>gitversion /output buildserver</code> you will have the
+    <code>gitversion --output buildserver</code> you will have the
     <code>%system.GitVersion.SemVer%</code> variable available for you to use
     in the rest of the build configuration.
 </p>

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: