Merge pull request #2317 from buildkite/pdp-1505-adjust-the-buildkite-agent-help-text-to-work-with-the-new

Author: triarius

clicommand/acknowledgements.go

@@ -10,15 +10,17 @@ import (
 )
 
 const acknowledgementsHelpDescription = `Usage:
-  buildkite-agent acknowledgements
+
+    buildkite-agent acknowledgements
 
 Description:
-   Prints the licenses and notices of open source software incorporated into
-   this software.
+
+Prints the licenses and notices of open source software incorporated into
+this software.
 
 Example:
 
-	$ buildkite-agent acknowledgements`
+    $ buildkite-agent acknowledgements`
 
 //go:embed *.md.gz
 var files embed.FS

clicommand/agent_start.go

@@ -39,20 +39,20 @@ import (
 
 const startDescription = `Usage:
 
-   buildkite-agent start [options...]
+    buildkite-agent start [options...]
 
 Description:
 
-   When a job is ready to run it will call the "bootstrap-script"
-   and pass it all the environment variables required for the job to run.
-   This script is responsible for checking out the code, and running the
-   actual build script defined in the pipeline.
+When a job is ready to run it will call the "bootstrap-script"
+and pass it all the environment variables required for the job to run.
+This script is responsible for checking out the code, and running the
+actual build script defined in the pipeline.
 
-   The agent will run any jobs within a PTY (pseudo terminal) if available.
+The agent will run any jobs within a PTY (pseudo terminal) if available.
 
 Example:
 
-   $ buildkite-agent start --token xxx`
+    $ buildkite-agent start --token xxx`
 
 var verificationFailureBehaviors = []string{agent.VerificationBehaviourBlock, agent.VerificationBehaviourWarn}
 

clicommand/annotate.go

@@ -21,37 +21,37 @@ const (
 
 const annotateHelpDescription = `Usage:
 
-   buildkite-agent annotate [body] [options...]
+    buildkite-agent annotate [body] [options...]
 
 Description:
 
-   Build annotations allow you to customize the Buildkite build interface to
-   show information that may surface from your builds. Some examples include:
+Build annotations allow you to customize the Buildkite build interface to
+show information that may surface from your builds. Some examples include:
 
-   - Links to artifacts generated by your jobs
-   - Test result summaries
-   - Graphs that include analysis about your codebase
-   - Helpful information for team members about what happened during a build
+- Links to artifacts generated by your jobs
+- Test result summaries
+- Graphs that include analysis about your codebase
+- Helpful information for team members about what happened during a build
 
-   Annotations are written in CommonMark-compliant Markdown, with "GitHub
-   Flavored Markdown" extensions.
+Annotations are written in CommonMark-compliant Markdown, with "GitHub
+Flavored Markdown" extensions.
 
-   The annotation body can be supplied as a command line argument, or by piping
-   content into the command. The maximum size of each annotation body is 1MiB.
+The annotation body can be supplied as a command line argument, or by piping
+content into the command. The maximum size of each annotation body is 1MiB.
 
-   You can update an existing annotation's body by running the annotate command
-   again and provide the same context as the one you want to update. Or if you
-   leave context blank, it will use the default context.
+You can update an existing annotation's body by running the annotate command
+again and provide the same context as the one you want to update. Or if you
+leave context blank, it will use the default context.
 
-   You can also update only the style of an existing annotation by omitting the
-   body entirely and providing a new style value.
+You can also update only the style of an existing annotation by omitting the
+body entirely and providing a new style value.
 
 Example:
 
-   $ buildkite-agent annotate "All tests passed! :rocket:"
-   $ cat annotation.md | buildkite-agent annotate --style "warning"
-   $ buildkite-agent annotate --style "success" --context "junit"
-   $ ./script/dynamic_annotation_generator | buildkite-agent annotate --style "success"`
+    $ buildkite-agent annotate "All tests passed! :rocket:"
+    $ cat annotation.md | buildkite-agent annotate --style "warning"
+    $ buildkite-agent annotate --style "success" --context "junit"
+    $ ./script/dynamic_annotation_generator | buildkite-agent annotate --style "success"`
 
 type AnnotateConfig struct {
 	Body    string `cli:"arg:0" label:"annotation body"`

clicommand/annotation_remove.go

@@ -11,19 +11,19 @@ import (
 
 const annotationRemoveHelpDescription = `Usage:
 
-   buildkite-agent annotation remove [arguments...]
+    buildkite-agent annotation remove [arguments...]
 
 Description:
 
-   Remove an existing annotation which was previously published using the
-   buildkite-agent annotate command.
+Remove an existing annotation which was previously published using the
+buildkite-agent annotate command.
 
-   If you leave context blank, it will use the default context.
+If you leave context blank, it will use the default context.
 
 Example:
 
-   $ buildkite-agent annotation remove
-   $ buildkite-agent annotation remove --context "remove-me"`
+    $ buildkite-agent annotation remove
+    $ buildkite-agent annotation remove --context "remove-me"`
 
 type AnnotationRemoveConfig struct {
 	Context string `cli:"context" validate:"required"`

clicommand/artifact_download.go

@@ -10,40 +10,40 @@ import (
 
 const downloadHelpDescription = `Usage:
 
-   buildkite-agent artifact download [options] <query> <destination>
+    buildkite-agent artifact download [options] <query> <destination>
 
 Description:
 
-   Downloads artifacts matching <query> from Buildkite to <destination>
-   directory on the local machine.
+Downloads artifacts matching <query> from Buildkite to <destination>
+directory on the local machine.
 
-   Note: You need to ensure that your search query is surrounded by quotes if
-   using a wild card as the built-in shell path globbing will expand the wild
-   card and break the query.
+Note: You need to ensure that your search query is surrounded by quotes if
+using a wild card as the built-in shell path globbing will expand the wild
+card and break the query.
 
-   If the last path component of <destination> matches the first path component
-   of your <query>, the last component of <destination> is dropped from the
-   final path. For example, a query of 'app/logs/*' with a destination of
-   'foo/app' will write any matched artifact files to 'foo/app/logs/', relative
-   to the current working directory.
+If the last path component of <destination> matches the first path component
+of your <query>, the last component of <destination> is dropped from the
+final path. For example, a query of 'app/logs/*' with a destination of
+'foo/app' will write any matched artifact files to 'foo/app/logs/', relative
+to the current working directory.
 
-   You can also change working directory to the intended destination and use a
-   <destination> of '.' to always create a directory hierarchy matching the
-   artifact paths.
+You can also change working directory to the intended destination and use a
+<destination> of '.' to always create a directory hierarchy matching the
+artifact paths.
 
 Example:
 
-   $ buildkite-agent artifact download "pkg/*.tar.gz" . --build xxx
+    $ buildkite-agent artifact download "pkg/*.tar.gz" . --build xxx
 
-   This will search across all the artifacts for the build with files that match that part.
-   The first argument is the search query, and the second argument is the download destination.
+This will search across all the artifacts for the build with files that match that part.
+The first argument is the search query, and the second argument is the download destination.
 
-   If you're trying to download a specific file, and there are multiple artifacts from different
-   jobs, you can target the particular job you want to download the artifact from:
+If you're trying to download a specific file, and there are multiple artifacts from different
+jobs, you can target the particular job you want to download the artifact from:
 
-   $ buildkite-agent artifact download "pkg/*.tar.gz" . --step "tests" --build xxx
+    $ buildkite-agent artifact download "pkg/*.tar.gz" . --step "tests" --build xxx
 
-   You can also use the step's jobs id (provided by the environment variable $BUILDKITE_JOB_ID)`
+You can also use the step's jobs id (provided by the environment variable $BUILDKITE_JOB_ID)`
 
 type ArtifactDownloadConfig struct {
 	Query              string `cli:"arg:0" label:"artifact search query" validate:"required"`

clicommand/artifact_search.go

@@ -14,35 +14,57 @@ import (
 
 const searchHelpDescription = `Usage:
 
-   buildkite-agent artifact search [options] <query>
+    buildkite-agent artifact search [options] <query>
 
 Description:
 
-	 Searches for build artifacts specified by <query> on Buildkite
+Searches for build artifacts specified by <query> on Buildkite
 
-   Note: You need to ensure that your search query is surrounded by quotes if
-   using a wild card as the built-in shell path globbing will provide files,
-   which will break the search.
+Note: You need to ensure that your search query is surrounded by quotes if
+using a wild card as the built-in shell path globbing will provide files,
+which will break the search.
 
 Example:
 
-   $ buildkite-agent artifact search "pkg/*.tar.gz" --build xxx
+    $ buildkite-agent artifact search "pkg/*.tar.gz" --build xxx
 
-   This will search across all uploaded artifacts in a build for files that match that query.
-   The first argument is the search query.
+This will search across all uploaded artifacts in a build for files that match that query.
+The first argument is the search query.
 
-   If you're trying to find a specific file, and there are multiple artifacts from different
-   jobs, you can target the particular job you want to search the artifacts from using --step:
+If you're trying to find a specific file, and there are multiple artifacts from different
+jobs, you can target the particular job you want to search the artifacts from using --step:
 
-   $ buildkite-agent artifact search "pkg/*.tar.gz" --step "tests" --build xxx
+    $ buildkite-agent artifact search "pkg/*.tar.gz" --step "tests" --build xxx
 
-   You can also use the step's job id (provided by the environment variable $BUILDKITE_JOB_ID)
+You can also use the step's job id (provided by the environment variable $BUILDKITE_JOB_ID)
 
-   Output formatting can be altered with the -format flag as follows:
+Output formatting can be altered with the -format flag as follows:
 
-   $ buildkite-agent artifact search "*" -format "%p\n"
+    $ buildkite-agent artifact search "*" -format "%p\n"
 
-   The above will return a list of filenames separated by newline.`
+The above will return a list of filenames separated by newline.`
+
+const artifactSearchHelpTemplate = `{{.Description}}
+
+Options:
+
+{{range .VisibleFlags}}  {{.}}
+{{end}}
+Format specifiers:
+
+  %i    UUID of the artifact
+
+  %p    Artifact path
+
+  %c    Artifact creation time (an ISO 8601 / RFC-3339 formatted UTC timestamp)
+
+  %j    UUID of the job that uploaded the artifact, helpful for subsequent artifact downloads
+
+  %s    File size of the artifact in bytes
+
+  %S    SHA1 checksum of the artifact
+
+  %u    Download URL for the artifact, though consider using 'buildkite-agent artifact download' instead`
 
 type ArtifactSearchConfig struct {
 	Query              string `cli:"arg:0" label:"artifact search query" validate:"required"`
@@ -67,32 +89,10 @@ type ArtifactSearchConfig struct {
 }
 
 var ArtifactSearchCommand = cli.Command{
-	Name:        "search",
-	Usage:       "Searches artifacts in Buildkite",
-	Description: searchHelpDescription,
-	CustomHelpTemplate: `{{.Description}}
-
-Options:
-
-   {{range .VisibleFlags}}{{.}}
-   {{end}}
-
-Format specifiers:
-
-	%i		UUID of the artifact
-
-	%p		Artifact path
-
-	%c		Artifact creation time (an ISO 8601 / RFC-3339 formatted UTC timestamp)
-
-	%j		UUID of the job that uploaded the artifact, helpful for subsequent artifact downloads
-
-	%s		File size of the artifact in bytes
-
-	%S		SHA1 checksum of the artifact
-
-	%u		Download URL for the artifact, though consider using 'buildkite-agent artifact download' instead
-`,
+	Name:               "search",
+	Usage:              "Searches artifacts in Buildkite",
+	Description:        searchHelpDescription,
+	CustomHelpTemplate: artifactSearchHelpTemplate,
 	Flags: []cli.Flag{
 		cli.StringFlag{
 			Name:  "step",

clicommand/artifact_shasum.go

@@ -14,40 +14,40 @@ import (
 
 const shasumHelpDescription = `Usage:
 
-   buildkite-agent artifact shasum [options...]
+    buildkite-agent artifact shasum [options...]
 
 Description:
 
-   Prints the SHA-1 or SHA-256 hash for the single artifact specified by a
-   search query.
+Prints the SHA-1 or SHA-256 hash for the single artifact specified by a
+search query.
 
-   The hash is fetched from Buildkite's API, having been generated client-side
-   by the agent during artifact upload.
+The hash is fetched from Buildkite's API, having been generated client-side
+by the agent during artifact upload.
 
-   A search query that does not match exactly one artifact results in an error.
+A search query that does not match exactly one artifact results in an error.
 
-   Note: You need to ensure that your search query is surrounded by quotes if
-   using a wild card as the built-in shell path globbing will provide files,
-   which will break the download.
+Note: You need to ensure that your search query is surrounded by quotes if
+using a wild card as the built-in shell path globbing will provide files,
+which will break the download.
 
 Example:
 
-   $ buildkite-agent artifact shasum "pkg/release.tar.gz" --build xxx
+    $ buildkite-agent artifact shasum "pkg/release.tar.gz" --build xxx
 
-   This will search for all files in the build with path "pkg/release.tar.gz",
-   and if exactly one match is found, the SHA-1 hash generated during upload
-   is printed.
+This will search for all files in the build with path "pkg/release.tar.gz",
+and if exactly one match is found, the SHA-1 hash generated during upload
+is printed.
 
-   If you would like to target artifacts from a specific build step, you can do
-   so by using the --step argument.
+If you would like to target artifacts from a specific build step, you can do
+so by using the --step argument.
 
-   $ buildkite-agent artifact shasum "pkg/release.tar.gz" --step "release" --build xxx
+    $ buildkite-agent artifact shasum "pkg/release.tar.gz" --step "release" --build xxx
 
-   You can also use the step's job ID (provided by the environment variable $BUILDKITE_JOB_ID)
+You can also use the step's job ID (provided by the environment variable $BUILDKITE_JOB_ID)
 
-   The --sha256 argument requests SHA-256 instead of SHA-1; this is only
-   available for artifacts uploaded since SHA-256 support was added to the
-   agent.`
+The ′--sha256′ argument requests SHA-256 instead of SHA-1; this is only
+available for artifacts uploaded since SHA-256 support was added to the
+agent.`
 
 type ArtifactShasumConfig struct {
 	Query              string `cli:"arg:0" label:"artifact search query" validate:"required"`