diff --git a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs index e5a119c4618..efede8671e0 100644 --- a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs +++ b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/CommandOptions/OptionsGenerator.cs @@ -56,7 +56,16 @@ public static RootCommand GenerateCommandLineOptions(Func }; #endregion - var root = new RootCommand(); + + var Description = @"This tool is used by the Azure SDK team in two primary ways: + + - Run as a http record/playback server. (""start"" / default verb) + - Invoke a CLI Tool to interact with recordings in an external store. (""push"", ""restore"", ""reset"", ""config"")"; + + var root = new RootCommand() + { + Description = Description + }; root.AddGlobalOption(storageLocationOption); root.AddGlobalOption(storagePluginOption); diff --git a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md index eccece25e3a..5be66555b83 100644 --- a/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md +++ b/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md @@ -149,32 +149,70 @@ For safety, the "official target" version that the azure-sdk team uses is presen ## Command line arguments -This is the help information for test-proxy. It uses the nuget package [`CommandLineParser`](https://www.nuget.org/packages/CommandLineParser) to parse arguments. +This is the help information for test-proxy. It uses the nuget package [`System.CommandLine`](https://www.nuget.org/packages/System.CommandLine) to parse arguments. The test-proxy executable fulfills one of two primary purposes: 1. The test-proxy server (the only option up to this point) -2. [`asset-sync`](#asset-sync-retrieve-external-test-recordings) push/restore/reset. +2. [`asset-sync`](#asset-sync-retrieve-external-test-recordings) verbs + - `push` + - `restore` + - `reset` + - `config` This is surfaced by only showing options for the default commands. Each individual command has its own argument set that can be detailed by invoking `test-proxy --help`. ```text -/>test-proxy --help -Azure.Sdk.Tools.TestProxy 1.0.0-dev.20220926.1 -c Microsoft Corporation. All rights reserved. - - start (Default Verb) Start the TestProxy. - - push Push the assets, referenced by assets.json, into git. - - reset Reset the assets, referenced by assets.json, from git to their original files referenced by the tag. Will prompt - if there are pending changes. - - restore Restore the assets, referenced by assets.json, from git. +/>Azure.Sdk.Tools.TestProxy --help +Description: + This tool is used by the Azure SDK team in two primary ways: + + - Run as a http record/playback server. ("start" / default verb) + - Invoke a CLI Tool to interact with recordings in an external store. ("push", "restore", "reset", "config") + +Usage: + Azure.Sdk.Tools.TestProxy [command] [options] + +Options: + -l, --storage-location The path to the target local git repo. If not provided as an argument, Environment + variable TEST_PROXY_FOLDER will be consumed. Lacking both, the current working + directory will be utilized. + -p, --storage-plugin The plugin for the selected storage, default is Git storage is GitStore. (Currently + the only option) [default: GitStore] + --version Show version information + -?, -h, --help Show help and usage information + +Commands: + start Start the TestProxy. + push Push the assets, referenced by assets.json, into git. + restore Restore the assets, referenced by assets.json, from git. + reset Reset the assets, referenced by assets.json, from git to their original files referenced by the tag. Will prompt if + there are pending changes unless indicated by -y/--yes. + config Interact with an assets.json. +``` - help Display more information on a specific command. +For the `config` verb, there are subverbs! - version Display version information. +```text +/>Azure.Sdk.Tools.TestProxy config --help +Description: + Interact with an assets.json. + +Usage: + Azure.Sdk.Tools.TestProxy config [command] [options] + +Options: + -l, --storage-location The path to the target local git repo. If not provided as an argument, Environment + variable TEST_PROXY_FOLDER will be consumed. Lacking both, the current working + directory will be utilized. + -p, --storage-plugin The plugin for the selected storage, default is Git storage is GitStore. (Currently + the only option) [default: GitStore] + -?, -h, --help Show help and usage information + +Commands: + create Enter a prompt and create an assets.json. + show Show the content of a given assets.json. + locate Get the assets repo root for a given assets.json path. ``` ### Storage Location diff --git a/tools/test-proxy/documentation/asset-sync/README.md b/tools/test-proxy/documentation/asset-sync/README.md index 13b12ade834..31aae84e7a8 100644 --- a/tools/test-proxy/documentation/asset-sync/README.md +++ b/tools/test-proxy/documentation/asset-sync/README.md @@ -69,10 +69,12 @@ Each of these CLI Commands takes an `assets.json` argument that provides the _co When using a Windows machine, it is technically possible to invoke tests from WSL against a windows clone. That path would appear under `/mnt/c/path/to/your/repo`. This is _not_ a supported scenario, as the `test-proxy` shells out to git for the push/restore actions. Running a `git push/pull` from _linux_ against a repo that was cloned down using a _windows_ git client can have unexpected results. Better to avoid the situation entirely and use an entirely separate clone for work on WSL. -## test-proxy CLI commands +## test-proxy CLI (asset) commands The test-proxy also offers interactions with the external assets repository as a CLI. Invoking `test-proxy --help` will show the available list of commands. `test-proxy --help` will show the help and options for an individual command. The options for a given command are all `--