Skip to content

Commit 02c2073

Browse files
AkihiroSudaAkihiroSuda
committed
Mark experimental flags in --help
Prior to this commit, experimental flags were not distinguishable from regular flags in `--help` Signed-off-by: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>
1 parent 78adfc8 commit 02c2073

File tree

9 files changed

+92
-29
lines changed

9 files changed

+92
-29
lines changed

‎commands/build.go‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ import (
2727
"github.com/docker/buildx/store"
2828
"github.com/docker/buildx/store/storeutil"
2929
"github.com/docker/buildx/util/buildflags"
30+
"github.com/docker/buildx/util/cobrautil"
3031
"github.com/docker/buildx/util/desktop"
3132
"github.com/docker/buildx/util/ioset"
3233
"github.com/docker/buildx/util/metrics"
@@ -537,7 +538,7 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions, debugConfig *debug.D
537538

538539
if isExperimental() {
539540
flags.StringVar(&options.printFunc, "print", "", "Print result of information request (e.g., outline, targets)")
540-
flags.SetAnnotation("print", "experimentalCLI", nil)
541+
cobrautil.MarkFlagsExperimental(flags, "print")
541542
}
542543

543544
flags.BoolVar(&options.exportPush, "push", false, `Shorthand for "--output=type=registry"`)
@@ -566,11 +567,9 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions, debugConfig *debug.D
566567
if isExperimental() {
567568
// TODO: move this to debug command if needed
568569
flags.StringVar(&options.Root, "root", "", "Specify root directory of server to connect")
569-
flags.SetAnnotation("root", "experimentalCLI", nil)
570570
flags.BoolVar(&options.Detach, "detach", false, "Detach buildx server (supported only on linux)")
571-
flags.SetAnnotation("detach", "experimentalCLI", nil)
572571
flags.StringVar(&options.ServerConfig, "server-config", "", "Specify buildx server config file (used only when launching new server)")
573-
flags.SetAnnotation("server-config", "experimentalCLI", nil)
572+
cobrautil.MarkFlagsExperimental(flags, "root", "detach", "server-config")
574573
}
575574

576575
// hidden flags
@@ -593,7 +592,7 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions, debugConfig *debug.D
593592
flags.BoolVar(&ignoreBool, "squash", false, "Squash newly built layers into a single new layer")
594593
flags.MarkHidden("squash")
595594
flags.SetAnnotation("squash", "flag-warn", []string{"experimental flag squash is removed with BuildKit. You should squash inside build using a multi-stage Dockerfile for efficiency."})
596-
flags.SetAnnotation("squash", "experimentalCLI", nil)
595+
cobrautil.MarkFlagsExperimental(flags, "squash")
597596

598597
flags.StringVarP(&ignore, "memory", "m", "", "Memory limit")
599598
flags.MarkHidden("memory")

‎commands/debug/root.go‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ import (
1010
"github.com/docker/buildx/controller/control"
1111
controllerapi "github.com/docker/buildx/controller/pb"
1212
"github.com/docker/buildx/monitor"
13+
"github.com/docker/buildx/util/cobrautil"
1314
"github.com/docker/buildx/util/progress"
1415
"github.com/docker/cli/cli/command"
1516
"github.com/moby/buildkit/util/progress/progressui"
@@ -42,9 +43,6 @@ func RootCmd(dockerCli command.Cli, children ...DebuggableCmd) *cobra.Command {
4243
Use: "debug",
4344
Short: "Start debugger",
4445
Args: cobra.NoArgs,
45-
Annotations: map[string]string{
46-
"experimentalCLI": "",
47-
},
4846
RunE: func(cmd *cobra.Command, args []string) error {
4947
printer, err := progress.NewPrinter(context.TODO(), os.Stderr, progressui.DisplayMode(progressMode))
5048
if err != nil {
@@ -73,21 +71,19 @@ func RootCmd(dockerCli command.Cli, children ...DebuggableCmd) *cobra.Command {
7371
return err
7472
},
7573
}
74+
cobrautil.MarkCommandExperimental(cmd)
7675

7776
flags := cmd.Flags()
7877
flags.StringVar(&options.InvokeFlag, "invoke", "", "Launch a monitor with executing specified command")
79-
flags.SetAnnotation("invoke", "experimentalCLI", nil)
8078
flags.StringVar(&options.OnFlag, "on", "error", "When to launch the monitor ([always, error])")
81-
flags.SetAnnotation("on", "experimentalCLI", nil)
8279

8380
flags.StringVar(&controlOptions.Root, "root", "", "Specify root directory of server to connect for the monitor")
84-
flags.SetAnnotation("root", "experimentalCLI", nil)
8581
flags.BoolVar(&controlOptions.Detach, "detach", runtime.GOOS == "linux", "Detach buildx server for the monitor (supported only on linux)")
86-
flags.SetAnnotation("detach", "experimentalCLI", nil)
8782
flags.StringVar(&controlOptions.ServerConfig, "server-config", "", "Specify buildx server config file for the monitor (used only when launching new server)")
88-
flags.SetAnnotation("server-config", "experimentalCLI", nil)
8983
flags.StringVar(&progressMode, "progress", "auto", `Set type of progress output ("auto", "plain", "tty") for the monitor. Use plain to show container output`)
9084

85+
cobrautil.MarkFlagsExperimental(flags, "invoke", "on", "root", "detach", "server-config")
86+
9187
for _, c := range children {
9288
cmd.AddCommand(c.NewDebugger(&options))
9389
}

‎commands/root.go‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,10 @@ func NewRootCmd(name string, isPlugin bool, dockerCli command.Cli) *cobra.Comman
5959
"using default config store",
6060
))
6161

62+
if !isExperimental() {
63+
cmd.SetHelpTemplate(cmd.HelpTemplate() + "\nExperimental commands and flags are hidden. Set BUILDX_EXPERIMENTAL=1 to show them.\n")
64+
}
65+
6266
addCommands(cmd, dockerCli)
6367
return cmd
6468
}

‎docs/generate.go‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ package main
33
import (
44
"log"
55
"os"
6+
"strings"
67

78
"github.com/docker/buildx/commands"
89
clidocstool "github.com/docker/cli-docs-tool"
@@ -26,6 +27,28 @@ type options struct {
2627
formats []string
2728
}
2829

30+
// fixUpExperimentalCLI trims the " (EXPERIMENTAL)" suffix from the CLI output,
31+
// as docs.docker.com already displays "experimental (CLI)",
32+
//
33+
// https://github.com/docker/buildx/pull/2188#issuecomment-1889487022
34+
func fixUpExperimentalCLI(cmd *cobra.Command) {
35+
const (
36+
annotationExperimentalCLI = "experimentalCLI"
37+
suffixExperimental = " (EXPERIMENTAL)"
38+
)
39+
if _, ok := cmd.Annotations[annotationExperimentalCLI]; ok {
40+
cmd.Short = strings.TrimSuffix(cmd.Short, suffixExperimental)
41+
}
42+
cmd.Flags().VisitAll(func(f *pflag.Flag) {
43+
if _, ok := f.Annotations[annotationExperimentalCLI]; ok {
44+
f.Usage = strings.TrimSuffix(f.Usage, suffixExperimental)
45+
}
46+
})
47+
for _, c := range cmd.Commands() {
48+
fixUpExperimentalCLI(c)
49+
}
50+
}
51+
2952
func gen(opts *options) error {
3053
log.SetFlags(0)
3154

@@ -57,6 +80,8 @@ func gen(opts *options) error {
5780
return err
5881
}
5982
case "yaml":
83+
// fix up is needed only for yaml (used for generating docs.docker.com contents)
84+
fixUpExperimentalCLI(cmd)
6085
if err = c.GenYamlTree(cmd); err != nil {
6186
return err
6287
}

‎docs/reference/buildx.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Extended build capabilities with BuildKit
1414
| [`bake`](buildx_bake.md) | Build from a file |
1515
| [`build`](buildx_build.md) | Start a build |
1616
| [`create`](buildx_create.md) | Create a new builder instance |
17-
| [`debug`](buildx_debug.md) | Start debugger |
17+
| [`debug`](buildx_debug.md) | Start debugger (EXPERIMENTAL) |
1818
| [`du`](buildx_du.md) | Disk usage |
1919
| [`imagetools`](buildx_imagetools.md) | Commands to work on images in registry |
2020
| [`inspect`](buildx_inspect.md) | Inspect current builder instance |

‎docs/reference/buildx_build.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Start a build
2525
| [`--cache-from`](#cache-from) | `stringArray` | | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) |
2626
| [`--cache-to`](#cache-to) | `stringArray` | | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`) |
2727
| [`--cgroup-parent`](https://docs.docker.com/engine/reference/commandline/build/#cgroup-parent) | `string` | | Set the parent cgroup for the `RUN` instructions during build |
28-
| `--detach` | | | Detach buildx server (supported only on linux) |
28+
| `--detach` | | | Detach buildx server (supported only on linux) (EXPERIMENTAL) |
2929
| [`-f`](https://docs.docker.com/engine/reference/commandline/build/#file), [`--file`](https://docs.docker.com/engine/reference/commandline/build/#file) | `string` | | Name of the Dockerfile (default: `PATH/Dockerfile`) |
3030
| `--iidfile` | `string` | | Write the image ID to the file |
3131
| `--label` | `stringArray` | | Set metadata for an image |
@@ -36,16 +36,16 @@ Start a build
3636
| [`--no-cache-filter`](#no-cache-filter) | `stringArray` | | Do not cache specified stages |
3737
| [`-o`](#output), [`--output`](#output) | `stringArray` | | Output destination (format: `type=local,dest=path`) |
3838
| [`--platform`](#platform) | `stringArray` | | Set target platform for build |
39-
| `--print` | `string` | | Print result of information request (e.g., outline, targets) |
39+
| `--print` | `string` | | Print result of information request (e.g., outline, targets) (EXPERIMENTAL) |
4040
| [`--progress`](#progress) | `string` | `auto` | Set type of progress output (`auto`, `plain`, `tty`). Use plain to show container output |
4141
| [`--provenance`](#provenance) | `string` | | Shorthand for `--attest=type=provenance` |
4242
| `--pull` | | | Always attempt to pull all referenced images |
4343
| [`--push`](#push) | | | Shorthand for `--output=type=registry` |
4444
| `-q`, `--quiet` | | | Suppress the build output and print image ID on success |
45-
| `--root` | `string` | | Specify root directory of server to connect |
45+
| `--root` | `string` | | Specify root directory of server to connect (EXPERIMENTAL) |
4646
| [`--sbom`](#sbom) | `string` | | Shorthand for `--attest=type=sbom` |
4747
| [`--secret`](#secret) | `stringArray` | | Secret to expose to the build (format: `id=mysecret[,src=/local/secret]`) |
48-
| `--server-config` | `string` | | Specify buildx server config file (used only when launching new server) |
48+
| `--server-config` | `string` | | Specify buildx server config file (used only when launching new server) (EXPERIMENTAL) |
4949
| [`--shm-size`](#shm-size) | `bytes` | `0` | Size of `/dev/shm` |
5050
| [`--ssh`](#ssh) | `stringArray` | | SSH agent socket or keys to expose to the build (format: `default\|<id>[=<socket>\|<key>[,<key>]]`) |
5151
| [`-t`](https://docs.docker.com/engine/reference/commandline/build/#tag), [`--tag`](https://docs.docker.com/engine/reference/commandline/build/#tag) | `stringArray` | | Name and optionally a tag (format: `name:tag`) |

‎docs/reference/buildx_debug.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# docker buildx debug
22

33
<!---MARKER_GEN_START-->
4-
Start debugger
4+
Start debugger (EXPERIMENTAL)
55

66
### Subcommands
77

@@ -15,12 +15,12 @@ Start debugger
1515
| Name | Type | Default | Description |
1616
|:------------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------|
1717
| `--builder` | `string` | | Override the configured builder instance |
18-
| `--detach` | | | Detach buildx server for the monitor (supported only on linux) |
19-
| `--invoke` | `string` | | Launch a monitor with executing specified command |
20-
| `--on` | `string` | `error` | When to launch the monitor ([always, error]) |
18+
| `--detach` | | | Detach buildx server for the monitor (supported only on linux) (EXPERIMENTAL) |
19+
| `--invoke` | `string` | | Launch a monitor with executing specified command (EXPERIMENTAL) |
20+
| `--on` | `string` | `error` | When to launch the monitor ([always, error]) (EXPERIMENTAL) |
2121
| `--progress` | `string` | `auto` | Set type of progress output (`auto`, `plain`, `tty`) for the monitor. Use plain to show container output |
22-
| `--root` | `string` | | Specify root directory of server to connect for the monitor |
23-
| `--server-config` | `string` | | Specify buildx server config file for the monitor (used only when launching new server) |
22+
| `--root` | `string` | | Specify root directory of server to connect for the monitor (EXPERIMENTAL) |
23+
| `--server-config` | `string` | | Specify buildx server config file for the monitor (used only when launching new server) (EXPERIMENTAL) |
2424

2525

2626
<!---MARKER_GEN_END-->

0 commit comments

Comments
 (0)