Skip to content

Commit 09f61db

Browse files
arturcicarturcic
committed
docs(migration): Add v6 to v7 migration guide for CLI arguments
1 parent e97abbf commit 09f61db

9 files changed

Lines changed: 102 additions & 11 deletions

File tree

‎.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: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ The command-line interface has been migrated from Windows-style (`/switch` and s
66

77
**Old-style arguments are no longer accepted by default.** Update any scripts, CI pipelines, or tooling accordingly.
88

9-
As a temporary migration aid, set the environment variable `USE_V6_ARGUMENT_PARSER=true` to restore the legacy `/switch` and `-switch` argument handling. This escape hatch will be removed in a future release.
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.
1010

1111
#### Full argument mapping
1212

‎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 supported short aliases where available (`-o`, `-v`, `-f`, `-c`, `-l`, `-d`, `-b`, `-u`, `-p`).
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/usage/cli/arguments.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,11 @@ Description: The supported arguments of the GitVersion Command Line Interface
55
---
66

77
:::{.alert .alert-info}
8-
**Note:** GitVersion now uses POSIX-style `--long-name` arguments. Short aliases
8+
**Note:** GitVersion uses POSIX-style `--long-name` arguments from version 7 and up. Short aliases
99
(e.g. `-l`, `-o`, `-b`) are also supported. The legacy `/switch` and `-switch`
10-
syntax is still available when `USE_V6_ARGUMENT_PARSER=true` is set.
10+
syntax is still available when `GITVERSION_USE_V6_ARGUMENT_PARSER=true` is set.
11+
12+
See [Migration v6 to v7](/docs/migration/v6-to-v7) for upgrade guidance and the full argument mapping.
1113
:::
1214

1315
## Help

‎src/.run/cli (help - old).run.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
<option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/GitVersion.App/bin/Debug/net10.0" />
66
<option name="PASS_PARENT_ENVS" value="1" />
77
<envs>
8-
<env name="USE_V6_ARGUMENT_PARSER" value="true" />
8+
<env name="GITVERSION_USE_V6_ARGUMENT_PARSER" value="true" />
99
</envs>
1010
<option name="ENV_FILE_PATHS" value="" />
1111
<option name="REDIRECT_INPUT_PATH" value="" />
@@ -23,4 +23,4 @@
2323
<option name="Build" />
2424
</method>
2525
</configuration>
26-
</component>
26+
</component>

‎src/.run/cli (old).run.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
<option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/GitVersion.App/bin/Debug/net10.0" />
66
<option name="PASS_PARENT_ENVS" value="1" />
77
<envs>
8-
<env name="USE_V6_ARGUMENT_PARSER" value="true" />
8+
<env name="GITVERSION_USE_V6_ARGUMENT_PARSER" value="true" />
99
</envs>
1010
<option name="ENV_FILE_PATHS" value="" />
1111
<option name="REDIRECT_INPUT_PATH" value="" />
@@ -23,4 +23,4 @@
2323
<option name="Build" />
2424
</method>
2525
</configuration>
26-
</component>
26+
</component>

‎src/.run/cli (version - old).run.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
<option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/GitVersion.App/bin/Debug/net10.0" />
66
<option name="PASS_PARENT_ENVS" value="1" />
77
<envs>
8-
<env name="USE_V6_ARGUMENT_PARSER" value="true" />
8+
<env name="GITVERSION_USE_V6_ARGUMENT_PARSER" value="true" />
99
</envs>
1010
<option name="ENV_FILE_PATHS" value="" />
1111
<option name="REDIRECT_INPUT_PATH" value="" />
@@ -23,4 +23,4 @@
2323
<option name="Build" />
2424
</method>
2525
</configuration>
26-
</component>
26+
</component>

‎src/GitVersion.App/CliHost.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ private static void RegisterGitVersionModules(IServiceCollection services, strin
3535

3636
services.AddModule(new GitVersionLibGit2SharpModule());
3737

38-
var envValue = SysEnv.GetEnvironmentVariable("USE_V6_ARGUMENT_PARSER");
38+
var envValue = SysEnv.GetEnvironmentVariable("GITVERSION_USE_V6_ARGUMENT_PARSER");
3939
var useLegacyParser = string.Equals(envValue, "true", StringComparison.OrdinalIgnoreCase);
4040
services.AddModule(new GitVersionAppModule(args, useLegacyParser));
4141
}

0 commit comments

Comments
 (0)