Skip to content

Commit

Permalink
Merge pull request #2317 from buildkite/pdp-1505-adjust-the-buildkite…
Browse files Browse the repository at this point in the history
…-agent-help-text-to-work-with-the-new
  • Loading branch information
triarius authored Aug 23, 2023
2 parents 8f07ffa + 014526f commit ace27c4
Show file tree
Hide file tree
Showing 28 changed files with 392 additions and 379 deletions.
10 changes: 6 additions & 4 deletions clicommand/acknowledgements.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 7 additions & 7 deletions clicommand/agent_start.go
Original file line number Diff line number Diff line change
Expand Up @@ -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}

Expand Down
40 changes: 20 additions & 20 deletions clicommand/annotate.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"`
Expand Down
12 changes: 6 additions & 6 deletions clicommand/annotation_remove.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"`
Expand Down
42 changes: 21 additions & 21 deletions clicommand/artifact_download.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"`
Expand Down
82 changes: 41 additions & 41 deletions clicommand/artifact_search.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"`
Expand All @@ -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",
Expand Down
40 changes: 20 additions & 20 deletions clicommand/artifact_shasum.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"`
Expand Down
Loading

0 comments on commit ace27c4

Please sign in to comment.