docs(cli): Recommend long-form arguments for scripts and documentation

Author: arturcic

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

@@ -32,11 +32,13 @@ 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]`
-* `--username [authentication username]` (or `-u`)
-* `--password [authentication password]` (or `-p`)
-* `--branch [branch name]` (or `-b`)
+* `--username [authentication username]` (short alias: `-u`)
+* `--password [authentication password]` (short alias: `-p`)
+* `--branch [branch name]` (short alias: `-b`)
 * `--commit [commit id]`
 
+Long-form arguments are recommended for scripts and documentation.
+
 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

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

@@ -19,7 +19,7 @@ As a temporary migration aid, set `GITVERSION_USE_V6_ARGUMENT_PARSER=true` to re
 ### What you need to change
 
 1. Replace old argument names with POSIX-style `--long-name` arguments.
-2. Prefer supported short aliases where available (`-o`, `-v`, `-f`, `-c`, `-l`, `-d`, `-b`, `-u`, `-p`).
+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.
 

docs/input/docs/usage/cli/arguments.md

@@ -5,7 +5,8 @@ Description: The supported arguments of the GitVersion Command Line Interface
 ---
 
 :::{.alert .alert-info}
-**Note:** GitVersion uses POSIX-style `--long-name` arguments from version 7 and up. Short aliases
+**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.
 

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.
 :::