Skip to content

Commit 2f22270

Browse files
arturcicarturcic
committed
Merge pull request #4840 from arturcic/feature/posix-argument-parser
Adopt POSIX-style CLI arguments
2 parents 3a7f721 + cd1cf40 commit 2f22270

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

50 files changed

+2434
-663
lines changed

‎.markdownlint.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
{
22
"MD026": false,
3-
"MD041": false
3+
"MD041": false,
4+
"MD013": false
45
}

‎BREAKING_CHANGES.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,47 @@
11
## Unreleased
22

3+
### CLI Arguments — POSIX-style Syntax
4+
5+
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).
6+
7+
**Old-style arguments are no longer accepted by default.** Update any scripts, CI pipelines, or tooling accordingly.
8+
9+
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.
10+
11+
#### Full argument mapping
12+
13+
| Old argument | New argument | Short alias | Env var alternative |
14+
| ----------------------------- | -------------------------------- | ------------------------------ | ---------------------------- |
15+
| `/targetpath <path>` | `--target-path <path>` | _(positional `path` argument)_ | |
16+
| `/output <type>` | `--output <type>` | `-o` | |
17+
| `/outputfile <path>` | `--output-file <path>` | | |
18+
| `/showvariable <var>` | `--show-variable <var>` | `-v` | |
19+
| `/format <format>` | `--format <format>` | `-f` | |
20+
| `/config <path>` | `--config <path>` | `-c` | |
21+
| `/showconfig` | `--show-config` | | |
22+
| `/overrideconfig <k=v>` | `--override-config <k=v>` | | |
23+
| `/nocache` | `--no-cache` | | |
24+
| `/nofetch` | `--no-fetch` | | |
25+
| `/nonormalize` | `--no-normalize` | | |
26+
| `/allowshallow` | `--allow-shallow` | | |
27+
| `/verbosity <level>` | `--verbosity <level>` | | |
28+
| `/l <path>` | `--log-file <path>` | `-l` | |
29+
| `/diag` | `--diagnose` | `-d` | |
30+
| `/updateassemblyinfo [files]` | `--update-assembly-info [files]` | | |
31+
| `/updateprojectfiles [files]` | `--update-project-files [files]` | | |
32+
| `/ensureassemblyinfo` | `--ensure-assembly-info` | | |
33+
| `/updatewixversionfile` | `--update-wix-version-file` | | |
34+
| `/url <url>` | `--url <url>` | | |
35+
| `/b <branch>` | `--branch <branch>` | `-b` | |
36+
| `/u <username>` | `--username <username>` | `-u` | `GITVERSION_REMOTE_USERNAME` |
37+
| `/p <password>` | `--password <password>` | `-p` | `GITVERSION_REMOTE_PASSWORD` |
38+
| `/c <commit>` | `--commit <commit>` | _(no short alias)_ | |
39+
| `/dynamicRepoLocation <path>` | `--dynamic-repo-location <path>` | | |
40+
41+
> **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>`.
42+
43+
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.
44+
345
### Logging System Replacement
446

547
* 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‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ private static void PackPrepareNative(BuildContext context)
3939
{
4040
context.Information("Validating native lib:");
4141
var nativeExe = outputPath.CombineWithFilePath(context.IsOnWindows ? "gitversion.exe" : "gitversion");
42-
context.ValidateOutput(nativeExe.FullPath, "/showvariable FullSemver", context.Version?.GitVersion?.FullSemVer);
42+
context.ValidateOutput(nativeExe.FullPath, "--show-variable FullSemver", context.Version?.GitVersion?.FullSemVer);
4343
}
4444
}
4545
}

‎build/build/Tasks/ValidateVersion.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,6 @@ public override void Run(BuildContext context)
1111
{
1212
ArgumentNullException.ThrowIfNull(context.Version);
1313
var gitVersionTool = context.GetGitVersionToolLocation();
14-
context.ValidateOutput("dotnet", $"\"{gitVersionTool}\" -version", context.Version.GitVersion.InformationalVersion);
14+
context.ValidateOutput("dotnet", $"\"{gitVersionTool}\" --version", context.Version.GitVersion.InformationalVersion);
1515
}
1616
}

‎build/common/Addins/GitVersion/GitVersionRunner.cs‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -64,19 +64,19 @@ private ProcessArgumentBuilder GetArguments(GitVersionSettings settings)
6464

6565
if (settings.OutputTypes.Contains(GitVersionOutput.Json))
6666
{
67-
builder.Append("-output");
67+
builder.Append("--output");
6868
builder.Append("json");
6969
}
7070

7171
if (settings.OutputTypes.Contains(GitVersionOutput.BuildServer))
7272
{
73-
builder.Append("-output");
73+
builder.Append("--output");
7474
builder.Append("buildserver");
7575
}
7676

7777
if (!string.IsNullOrWhiteSpace(settings.ShowVariable))
7878
{
79-
builder.Append("-showvariable");
79+
builder.Append("--show-variable");
8080
builder.Append(settings.ShowVariable);
8181
}
8282

@@ -91,7 +91,7 @@ private ProcessArgumentBuilder GetArguments(GitVersionSettings settings)
9191

9292
if (settings.UpdateAssemblyInfo)
9393
{
94-
builder.Append("-updateassemblyinfo");
94+
builder.Append("--update-assembly-info");
9595

9696
if (settings.UpdateAssemblyInfoFilePath != null)
9797
{
@@ -101,12 +101,12 @@ private ProcessArgumentBuilder GetArguments(GitVersionSettings settings)
101101

102102
if (settings.RepositoryPath != null)
103103
{
104-
builder.Append("-targetpath");
104+
builder.Append("--target-path");
105105
builder.AppendQuoted(settings.RepositoryPath.FullPath);
106106
}
107107
else if (!string.IsNullOrWhiteSpace(settings.Url))
108108
{
109-
builder.Append("-url");
109+
builder.Append("--url");
110110
builder.AppendQuoted(settings.Url);
111111

112112
if (!string.IsNullOrWhiteSpace(settings.Branch))
@@ -122,13 +122,13 @@ private ProcessArgumentBuilder GetArguments(GitVersionSettings settings)
122122

123123
if (!string.IsNullOrWhiteSpace(settings.Commit))
124124
{
125-
builder.Append("-c");
125+
builder.Append("--commit");
126126
builder.AppendQuoted(settings.Commit);
127127
}
128128

129129
if (settings.DynamicRepositoryPath != null)
130130
{
131-
builder.Append("-dynamicRepoLocation");
131+
builder.Append("--dynamic-repo-location");
132132
builder.AppendQuoted(settings.DynamicRepositoryPath.FullPath);
133133
}
134134
}
@@ -141,14 +141,14 @@ private ProcessArgumentBuilder GetArguments(GitVersionSettings settings)
141141

142142
if (settings.NoFetch)
143143
{
144-
builder.Append("-nofetch");
144+
builder.Append("--no-fetch");
145145
}
146146

147147
var verbosity = settings.Verbosity ?? this._log.Verbosity;
148148

149149
if (verbosity != Verbosity.Normal)
150150
{
151-
builder.Append("-verbosity");
151+
builder.Append("--verbosity");
152152
builder.Append(verbosity.ToString());
153153
}
154154

‎build/common/Utilities/DockerContextExtensions.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -156,7 +156,7 @@ public void DockerTestImage(DockerImage dockerImage)
156156
var tags = context.GetDockerTags(dockerImage, dockerImage.Architecture);
157157
foreach (var tag in tags)
158158
{
159-
context.DockerTestRun(tag, dockerImage.Architecture, "/repo", ["/showvariable", "FullSemver", "/nocache"]);
159+
context.DockerTestRun(tag, dockerImage.Architecture, "/repo", ["--show-variable", "FullSemver", "--no-cache"]);
160160
}
161161
}
162162

‎docs/input/docs/learn/dynamic-repositories.md‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -31,15 +31,17 @@ will assume there is already a ".git" folder present, and it will use it.
3131
To tell GitVersion.exe to obtain the repository on the fly, you need to call
3232
`GitVersion.exe` with the following arguments:
3333

34-
* `/url [the url of your git repo]`
35-
* `/u [authentication username]`
36-
* `/p [authentication password]`
37-
* `/b [branch name]`
38-
* `/c [commit id]`
34+
* `--url [the url of your git repo]`
35+
* `--username [authentication username]` (short alias: `-u`)
36+
* `--password [authentication password]` (short alias: `-p`)
37+
* `--branch [branch name]` (short alias: `-b`)
38+
* `--commit [commit id]`
3939

40-
Please note that these arguments are described when calling `GitVersion.exe /?`.
40+
Long-form arguments are recommended for scripts and documentation.
4141

42-
Also, be aware that if you don't specify the `/b` argument (branch name) then
42+
Please note that these arguments are described when calling `GitVersion.exe --help`.
43+
44+
Also, be aware that if you don't specify the `--branch` argument (branch name) then
4345
GitVersion will currently fallback to targeting whatever the default branch name
4446
happens to be for the repo. This could lead to incorrect results, so for that
4547
reason it's recommended to always explicitly specify the branch name.

‎docs/input/docs/migration/index.cshtml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
Title: Migration
3+
Description: Technical reference documentation.
4+
Order: 100
5+
---
6+
<p>@Html.Raw(Model.String(DocsKeys.Description))</p>
7+
8+
@Html.Partial("_ChildPages")

‎docs/input/docs/migration/v6-to-v7.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
Order: 10
3+
Title: Migration v6 to v7
4+
Description: Migration guidance for upgrading from GitVersion v6 to GitVersion v7.
5+
---
6+
7+
This document summarizes the relevant breaking changes when migrating from GitVersion v6 to v7.
8+
9+
## CLI Arguments - POSIX-style syntax
10+
11+
GitVersion now uses POSIX-style command-line arguments powered by System.CommandLine.
12+
13+
:::{.alert .alert-warning}
14+
**Breaking change:** Legacy Windows-style (`/switch`) and legacy single-dash long-form (`-switch`) arguments are no longer accepted by default.
15+
16+
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.
17+
:::
18+
19+
### What you need to change
20+
21+
1. Replace old argument names with POSIX-style `--long-name` arguments.
22+
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.
23+
3. Update scripts that used `-c <commit>` to `--commit <commit>`.
24+
4. Optionally use `GITVERSION_REMOTE_USERNAME` and `GITVERSION_REMOTE_PASSWORD` instead of passing credentials on the command line.
25+
26+
### Full argument mapping
27+
28+
| Old argument | New argument | Short alias | Env var alternative |
29+
| ----------------------------- | -------------------------------- | ------------------------------ | ---------------------------- |
30+
| `/targetpath <path>` | `--target-path <path>` | _(positional `path` argument)_ | |
31+
| `/output <type>` | `--output <type>` | `-o` | |
32+
| `/outputfile <path>` | `--output-file <path>` | | |
33+
| `/showvariable <var>` | `--show-variable <var>` | `-v` | |
34+
| `/format <format>` | `--format <format>` | `-f` | |
35+
| `/config <path>` | `--config <path>` | `-c` | |
36+
| `/showconfig` | `--show-config` | | |
37+
| `/overrideconfig <k=v>` | `--override-config <k=v>` | | |
38+
| `/nocache` | `--no-cache` | | |
39+
| `/nofetch` | `--no-fetch` | | |
40+
| `/nonormalize` | `--no-normalize` | | |
41+
| `/allowshallow` | `--allow-shallow` | | |
42+
| `/verbosity <level>` | `--verbosity <level>` | | |
43+
| `/l <path>` | `--log-file <path>` | `-l` | |
44+
| `/diag` | `--diagnose` | `-d` | |
45+
| `/updateassemblyinfo [files]` | `--update-assembly-info [files]` | | |
46+
| `/updateprojectfiles [files]` | `--update-project-files [files]` | | |
47+
| `/ensureassemblyinfo` | `--ensure-assembly-info` | | |
48+
| `/updatewixversionfile` | `--update-wix-version-file` | | |
49+
| `/url <url>` | `--url <url>` | | |
50+
| `/b <branch>` | `--branch <branch>` | `-b` | |
51+
| `/u <username>` | `--username <username>` | `-u` | `GITVERSION_REMOTE_USERNAME` |
52+
| `/p <password>` | `--password <password>` | `-p` | `GITVERSION_REMOTE_PASSWORD` |
53+
| `/c <commit>` | `--commit <commit>` | _(no short alias)_ | |
54+
| `/dynamicRepoLocation <path>` | `--dynamic-repo-location <path>` | | |
55+
56+
:::{.alert .alert-danger}
57+
**Important:** `-c` now maps to `--config`.
58+
59+
If you previously used `-c <commit-id>`, you must replace it with `--commit <commit-id>`.
60+
:::
61+
62+
### Example updates
63+
64+
```bash
65+
# Before
66+
gitversion /output json /showvariable SemVer /config GitVersion.yml
67+
68+
# After
69+
gitversion --output json --show-variable SemVer --config GitVersion.yml
70+
```
71+
72+
```bash
73+
# Before
74+
gitversion /url https://github.com/org/repo.git /b main /u user /p pass /c a1b2c3
75+
76+
# After
77+
gitversion --url https://github.com/org/repo.git --branch main --username user --password pass --commit a1b2c3
78+
```
79+
80+
For current command details and examples, see [CLI Arguments](/docs/usage/cli/arguments).

‎docs/input/docs/reference/build-servers/bitbucket-pipelines.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ pipelines:
2828
script:
2929
- export PATH="$PATH:/root/.dotnet/tools"
3030
- dotnet tool install --global GitVersion.Tool
31-
- dotnet-gitversion /output buildserver
31+
- dotnet-gitversion --output buildserver
3232
- source gitversion.properties
3333
- echo Building with semver $GITVERSION_FULLSEMVER
3434
- dotnet build
@@ -41,7 +41,7 @@ You must set the `clone:depth` setting as shown above; without it, BitBucket Pip
4141
cause GitVersion to display an error message.
4242
:::
4343

44-
When the action `dotnet-gitversion /output buildserver` is executed, it will detect that it is running in BitBucket Pipelines by the presence of
44+
When the action `dotnet-gitversion --output buildserver` is executed, it will detect that it is running in BitBucket Pipelines by the presence of
4545
the `BITBUCKET_WORKSPACE` environment variable, which is set by the BitBucket Pipelines engine. It will generate a text file named `gitversion.properties`
4646
which contains all the output of the GitVersion tool, exported as individual environment variables prefixed with `GITVERSION_`.
4747
These environment variables can then be imported back into the build step using the `source gitversion.properties` action.
@@ -62,7 +62,7 @@ pipelines:
6262
script:
6363
- export PATH="$PATH:/root/.dotnet/tools"
6464
- dotnet tool install --global GitVersion.Tool
65-
- dotnet-gitversion /output buildserver
65+
- dotnet-gitversion --output buildserver
6666
artifacts:
6767
- gitversion.properties
6868
- step:

0 commit comments

Comments
 (0)