Skip to content

Commit c9a2529

Browse files
arturcicarturcic
committed
feat(cli): enhance argument descriptions and add help wrapping
Improve clarity and detail of argument descriptions in the CLI parser. Configure help system to wrap text for better readability in large outputs.
1 parent cc07f23 commit c9a2529

1 file changed

Lines changed: 136 additions & 30 deletions

File tree

‎src/GitVersion.App/ArgumentParser.cs‎

Lines changed: 136 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
using System.CommandLine;
2+
using System.CommandLine.Help;
23
using System.IO.Abstractions;
34
using GitVersion.Extensions;
45
using GitVersion.FileSystemGlobbing;
@@ -301,38 +302,140 @@ private static bool IsBooleanTrue(string value) =>
301302

302303
private static (RootCommand Root, CommandOptions Options) BuildCommand()
303304
{
304-
var path = new Argument<string?>("path") { Description = "The directory containing .git. If not defined current directory is used.", Arity = ArgumentArity.ZeroOrOne };
305-
var version = new Option<bool>("--version") { Description = "Displays the version of GitVersion" };
306-
var diagnose = new Option<bool>("--diagnose", "-d") { Description = "Runs GitVersion with additional diagnostic information" };
307-
var logFile = new Option<string?>("--log-file", "-l") { Description = "Path to logfile; specify 'console' to emit to stdout" };
308-
var output = new Option<OutputType[]>("--output", "-o") { Description = "Determines the output to the console. Can be 'json', 'file', 'buildserver' or 'dotenv'", AllowMultipleArgumentsPerToken = true, Arity = ArgumentArity.ZeroOrMore };
309-
var outputFile = new Option<string?>("--output-file") { Description = "Path to output file. Used in combination with --output 'file'" };
310-
var showVariable = new Option<string?>("--show-variable", "-v") { Description = "Output just a particular variable" };
311-
var format = new Option<string?>("--format", "-f") { Description = "Output a format containing version variables" };
312-
var config = new Option<string?>("--config", "-c") { Description = "Path to config file (defaults to GitVersion.yml)" };
313-
var showConfig = new Option<bool>("--show-config") { Description = "Outputs the effective GitVersion config in yaml format" };
314-
var overrideConfig = new Option<string[]>("--override-config") { Description = "Overrides GitVersion config values inline (key=value pairs)", AllowMultipleArgumentsPerToken = false, Arity = ArgumentArity.ZeroOrMore };
315-
var targetPath = new Option<string?>("--target-path") { Description = "Same as 'path', but not positional" };
316-
var noFetch = new Option<bool>("--no-fetch") { Description = "Disables 'git fetch' during version calculation" };
317-
var noCache = new Option<bool>("--no-cache") { Description = "Bypasses the cache, result will not be written to the cache" };
318-
var noNormalize = new Option<bool>("--no-normalize") { Description = "Disables normalize step on a build server" };
319-
var allowShallow = new Option<bool>("--allow-shallow") { Description = "Allows GitVersion to run on a shallow clone" };
320-
var verbosity = new Option<string?>("--verbosity") { Description = "Specifies the amount of information to be displayed (Quiet, Minimal, Normal, Verbose, Diagnostic)" };
321-
var updateAssemblyInfo = new Option<string[]?>("--update-assembly-info") { Description = "Will recursively search for all 'AssemblyInfo.cs' files and update them", AllowMultipleArgumentsPerToken = true, Arity = ArgumentArity.ZeroOrMore };
322-
var updateProjectFiles = new Option<string[]?>("--update-project-files") { Description = "Will recursively search for all project files and update them", AllowMultipleArgumentsPerToken = true, Arity = ArgumentArity.ZeroOrMore };
323-
var ensureAssemblyInfo = new Option<bool>("--ensure-assembly-info") { Description = "If the assembly info file specified with --update-assembly-info is not found, it will be created" };
324-
var updateWixVersionFile = new Option<bool>("--update-wix-version-file") { Description = "All the GitVersion variables are written to 'GitVersion_WixVersion.wxi'" };
325-
var url = new Option<string?>("--url") { Description = "Url to remote git repository" };
326-
var branch = new Option<string?>("--branch", "-b") { Description = "Name of the branch to use on the remote repository" };
327-
var username = new Option<string?>("--username", "-u") { Description = "Username in case authentication is required" };
328-
var password = new Option<string?>("--password", "-p") { Description = "Password in case authentication is required" };
329-
var commit = new Option<string?>("--commit") { Description = "The commit id to check" };
330-
var dynamicRepoLocation = new Option<string?>("--dynamic-repo-location") { Description = "Override default dynamic repository clone location" };
305+
var path = new Argument<string?>("path")
306+
{
307+
Description = "The directory containing .git. If not defined current directory is used. (Must be first argument)",
308+
Arity = ArgumentArity.ZeroOrOne
309+
};
310+
var diagnose = new Option<bool>("--diagnose", "-d")
311+
{
312+
Description = """
313+
Runs GitVersion with additional diagnostic information.
314+
Also needs the '--log-file' argument to specify a logfile or stdout (requires git.exe to be installed)
315+
"""
316+
};
317+
var logFile = new Option<string?>("--log-file", "-l")
318+
{
319+
Description = "Path to logfile; specify 'console' to emit to stdout"
320+
};
321+
var output = new Option<OutputType[]>("--output", "-o")
322+
{
323+
Description = "Determines the output to the console. Can be either 'json', 'file', 'buildserver' or 'dotenv', will default to 'json'",
324+
AllowMultipleArgumentsPerToken = true,
325+
Arity = ArgumentArity.ZeroOrMore
326+
};
327+
var outputFile = new Option<string?>("--output-file")
328+
{
329+
Description = "Path to output file. It is used in combination with --output 'file'"
330+
};
331+
var showVariable = new Option<string?>("--show-variable", "-v")
332+
{
333+
Description = """
334+
Used in conjunction with --output json, will output just a particular variable.
335+
E.g. --output json --show-variable SemVer - will output `1.2.3+beta.4`
336+
"""
337+
};
338+
var format = new Option<string?>("--format", "-f")
339+
{
340+
Description = """
341+
Used in conjunction with --output json, will output a format containing version variables.
342+
E.g. --output json --format {SemVer} - will output `1.2.3+beta.4`
343+
--output json --format {Major}.{Minor} - will output `1.2`
344+
"""
345+
};
346+
var config = new Option<string?>("--config", "-c")
347+
{
348+
Description = "Path to config file (defaults to GitVersion.yml, GitVersion.yaml, .GitVersion.yml or .GitVersion.yaml)"
349+
};
350+
var showConfig = new Option<bool>("--show-config")
351+
{
352+
Description = "Outputs the effective GitVersion config (defaults + custom from GitVersion.yml) in yaml format"
353+
};
354+
var overrideConfig = new Option<string[]>("--override-config")
355+
{
356+
Description = "Overrides GitVersion config values inline (key=value pairs e.g. --override-config tag-prefix=Foo)",
357+
AllowMultipleArgumentsPerToken = false,
358+
Arity = ArgumentArity.ZeroOrMore
359+
};
360+
var targetPath = new Option<string?>("--target-path")
361+
{
362+
Description = "Same as 'path', but not positional"
363+
};
364+
var noFetch = new Option<bool>("--no-fetch")
365+
{
366+
Description = "Disables 'git fetch' during version calculation. Might cause GitVersion to not calculate your version as expected"
367+
};
368+
var noCache = new Option<bool>("--no-cache")
369+
{
370+
Description = "Bypasses the cache, result will not be written to the cache"
371+
};
372+
var noNormalize = new Option<bool>("--no-normalize")
373+
{
374+
Description = "Disables normalize step on a build server"
375+
};
376+
var allowShallow = new Option<bool>("--allow-shallow")
377+
{
378+
Description = "Allows GitVersion to run on a shallow clone (not recommended)"
379+
};
380+
var verbosity = new Option<string?>("--verbosity")
381+
{
382+
Description = "Specifies the amount of information to be displayed (Quiet, Minimal, Normal, Verbose, Diagnostic). Default is Normal"
383+
};
384+
var updateAssemblyInfo = new Option<string[]?>("--update-assembly-info")
385+
{
386+
Description = "Will recursively search for all 'AssemblyInfo.cs' files in the git repo and update them",
387+
AllowMultipleArgumentsPerToken = true,
388+
Arity = ArgumentArity.ZeroOrMore
389+
};
390+
var updateProjectFiles = new Option<string[]?>("--update-project-files")
391+
{
392+
Description = """
393+
Will recursively search for all project files (.csproj/.vbproj/.fsproj/.sqlproj)
394+
in the git repo and update them (only compatible with Sdk projects)
395+
""",
396+
AllowMultipleArgumentsPerToken = true,
397+
Arity = ArgumentArity.ZeroOrMore
398+
};
399+
var ensureAssemblyInfo = new Option<bool>("--ensure-assembly-info")
400+
{
401+
Description = """
402+
If the assembly info file specified with --update-assembly-info is not found,
403+
it will be created with AssemblyFileVersion, AssemblyVersion and AssemblyInformationalVersion.
404+
Supports C#, F#, VB
405+
"""
406+
};
407+
var updateWixVersionFile = new Option<bool>("--update-wix-version-file")
408+
{
409+
Description = "All the GitVersion variables are written to 'GitVersion_WixVersion.wxi'"
410+
};
411+
var url = new Option<string?>("--url")
412+
{
413+
Description = "Url to remote git repository"
414+
};
415+
var branch = new Option<string?>("--branch", "-b")
416+
{
417+
Description = "Name of the branch to use on the remote repository, must be used in combination with --url"
418+
};
419+
var username = new Option<string?>("--username", "-u")
420+
{
421+
Description = "Username in case authentication is required"
422+
};
423+
var password = new Option<string?>("--password", "-p")
424+
{
425+
Description = "Password in case authentication is required"
426+
};
427+
var commit = new Option<string?>("--commit")
428+
{
429+
Description = "The commit id to check. If not specified, the latest available commit on the specified branch will be used"
430+
};
431+
var dynamicRepoLocation = new Option<string?>("--dynamic-repo-location")
432+
{
433+
Description = "By default dynamic repositories will be cloned to %tmp%. Use this option to override"
434+
};
331435

332436
var rootCommand = new RootCommand("Use convention to derive a SemVer product version from a GitFlow or GitHub based repository.")
333437
{
334438
path,
335-
version,
336439
diagnose,
337440
logFile,
338441
output,
@@ -360,8 +463,12 @@ private static (RootCommand Root, CommandOptions Options) BuildCommand()
360463
dynamicRepoLocation
361464
};
362465

466+
// Configure the built-in help system to wrap at 260 characters to avoid too small help messages
467+
var helpOption = rootCommand.Options.SingleOfType<HelpOption>();
468+
helpOption.Action = new HelpAction { MaxWidth = 260 };
469+
363470
return (rootCommand, new CommandOptions(
364-
Path: path, Version: version, Diagnose: diagnose, LogFile: logFile,
471+
Path: path, Diagnose: diagnose, LogFile: logFile,
365472
Output: output, OutputFile: outputFile, ShowVariable: showVariable, Format: format,
366473
Config: config, ShowConfig: showConfig, OverrideConfig: overrideConfig, TargetPath: targetPath,
367474
NoFetch: noFetch, NoCache: noCache, NoNormalize: noNormalize, AllowShallow: allowShallow,
@@ -485,7 +592,6 @@ private static void ParseOverrideConfig(Arguments arguments, IReadOnlyCollection
485592

486593
private sealed record CommandOptions(
487594
Argument<string?> Path,
488-
Option<bool> Version,
489595
Option<bool> Diagnose,
490596
Option<string?> LogFile,
491597
Option<OutputType[]> Output,

0 commit comments

Comments
 (0)