From c700bbcb4baa4b215a67dc587bae70885849bba7 Mon Sep 17 00:00:00 2001 From: Silvin Lubecki Date: Mon, 18 Jan 2021 11:19:37 +0100 Subject: [PATCH 1/8] Add specific "json" value to format flag with inspect commands to output json, as empty flag does. Added tests on that new behavior. Signed-off-by: Silvin Lubecki Signed-off-by: Sebastiaan van Stijn --- cli/command/inspect/inspector.go | 2 +- cli/command/inspect/inspector_test.go | 54 +++++++++++++++++++++++++++ 2 files changed, 55 insertions(+), 1 deletion(-) diff --git a/cli/command/inspect/inspector.go b/cli/command/inspect/inspector.go index aef31e62df..15dbea14ce 100644 --- a/cli/command/inspect/inspector.go +++ b/cli/command/inspect/inspector.go @@ -38,7 +38,7 @@ func NewTemplateInspector(outputStream io.Writer, tmpl *template.Template) Inspe // NewTemplateInspectorFromString creates a new TemplateInspector from a string // which is compiled into a template. func NewTemplateInspectorFromString(out io.Writer, tmplStr string) (Inspector, error) { - if tmplStr == "" { + if tmplStr == "" || tmplStr == "json" { return NewIndentedInspector(out), nil } diff --git a/cli/command/inspect/inspector_test.go b/cli/command/inspect/inspector_test.go index 702df3d8cc..74c49b2f82 100644 --- a/cli/command/inspect/inspector_test.go +++ b/cli/command/inspect/inspector_test.go @@ -257,3 +257,57 @@ func TestTemplateInspectorRawFallbackNumber(t *testing.T) { b.Reset() } } + +func TestNewTemplateInspectorFromString(t *testing.T) { + testCases := []struct { + name string + template string + expected string + }{ + { + name: "empty template outputs json by default", + template: "", + expected: `[ + { + "Name": "test" + } +] +`, + }, + { + name: "json specific value outputs json", + template: "json", + expected: `[ + { + "Name": "test" + } +] +`, + }, + { + name: "template is applied", + template: "{{.Name}}", + expected: "test\n", + }, + } + value := struct { + Name string + }{ + "test", + } + for _, tc := range testCases { + t.Run(tc.name, func(t *testing.T) { + b := new(bytes.Buffer) + i, err := NewTemplateInspectorFromString(b, tc.template) + assert.NilError(t, err) + + err = i.Inspect(value, nil) + assert.NilError(t, err) + + err = i.Flush() + assert.NilError(t, err) + + assert.Equal(t, b.String(), tc.expected) + }) + } +} From 84d47b544e49ca7d268bdad108592d3f1b6a3504 Mon Sep 17 00:00:00 2001 From: Silvin Lubecki Date: Mon, 18 Jan 2021 11:43:29 +0100 Subject: [PATCH 2/8] Add "json" as default value to format flag in all inspect commands. Signed-off-by: Silvin Lubecki Signed-off-by: Sebastiaan van Stijn --- cli/command/config/inspect.go | 3 ++- cli/command/container/inspect.go | 3 ++- cli/command/context/inspect.go | 3 ++- cli/command/image/inspect.go | 3 ++- cli/command/network/inspect.go | 3 ++- cli/command/node/inspect.go | 3 ++- cli/command/plugin/inspect.go | 3 ++- cli/command/secret/inspect.go | 3 ++- cli/command/service/inspect.go | 3 ++- cli/command/system/inspect.go | 3 ++- cli/command/volume/inspect.go | 3 ++- cli/flags/common.go | 5 +++++ docs/reference/commandline/config_inspect.md | 6 +++++- docs/reference/commandline/context_inspect.md | 5 ++++- docs/reference/commandline/network_inspect.md | 6 +++++- docs/reference/commandline/node_inspect.md | 7 +++++-- docs/reference/commandline/plugin_inspect.md | 5 ++++- docs/reference/commandline/secret_inspect.md | 6 +++++- docs/reference/commandline/service_inspect.md | 7 +++++-- docs/reference/commandline/volume_inspect.md | 5 ++++- 20 files changed, 64 insertions(+), 21 deletions(-) diff --git a/cli/command/config/inspect.go b/cli/command/config/inspect.go index cb39ce2799..ddce83fd7a 100644 --- a/cli/command/config/inspect.go +++ b/cli/command/config/inspect.go @@ -8,6 +8,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/spf13/cobra" ) @@ -30,7 +31,7 @@ func newConfigInspectCommand(dockerCli command.Cli) *cobra.Command { }, } - cmd.Flags().StringVarP(&opts.Format, "format", "f", "", "Format the output using the given Go template") + cmd.Flags().StringVarP(&opts.Format, "format", "f", "json", flagsHelper.InspectFormatHelp) cmd.Flags().BoolVar(&opts.Pretty, "pretty", false, "Print the information in a human friendly format") return cmd } diff --git a/cli/command/container/inspect.go b/cli/command/container/inspect.go index 4f50e2a080..168740fae0 100644 --- a/cli/command/container/inspect.go +++ b/cli/command/container/inspect.go @@ -6,6 +6,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/inspect" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/spf13/cobra" ) @@ -30,7 +31,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVarP(&opts.format, "format", "f", "", "Format the output using the given Go template") + flags.StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) flags.BoolVarP(&opts.size, "size", "s", false, "Display total file sizes") return cmd diff --git a/cli/command/context/inspect.go b/cli/command/context/inspect.go index 2145845a7a..246436c1ca 100644 --- a/cli/command/context/inspect.go +++ b/cli/command/context/inspect.go @@ -6,6 +6,7 @@ import ( "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/inspect" "github.com/docker/cli/cli/context/store" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/spf13/cobra" ) @@ -34,7 +35,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVarP(&opts.format, "format", "f", "", "Format the output using the given Go template") + flags.StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) return cmd } diff --git a/cli/command/image/inspect.go b/cli/command/image/inspect.go index 2044fcafdf..e08b5fc3d9 100644 --- a/cli/command/image/inspect.go +++ b/cli/command/image/inspect.go @@ -6,6 +6,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/inspect" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/spf13/cobra" ) @@ -29,7 +30,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVarP(&opts.format, "format", "f", "", "Format the output using the given Go template") + flags.StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) return cmd } diff --git a/cli/command/network/inspect.go b/cli/command/network/inspect.go index 3d7543d9eb..890ac77506 100644 --- a/cli/command/network/inspect.go +++ b/cli/command/network/inspect.go @@ -6,6 +6,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/inspect" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/docker/docker/api/types" "github.com/spf13/cobra" ) @@ -29,7 +30,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { }, } - cmd.Flags().StringVarP(&opts.format, "format", "f", "", "Format the output using the given Go template") + cmd.Flags().StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", false, "Verbose output for diagnostics") return cmd diff --git a/cli/command/node/inspect.go b/cli/command/node/inspect.go index 9c68f43b79..51f7c50e1d 100644 --- a/cli/command/node/inspect.go +++ b/cli/command/node/inspect.go @@ -8,6 +8,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/spf13/cobra" ) @@ -31,7 +32,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVarP(&opts.format, "format", "f", "", "Format the output using the given Go template") + flags.StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) flags.BoolVar(&opts.pretty, "pretty", false, "Print the information in a human friendly format") return cmd } diff --git a/cli/command/plugin/inspect.go b/cli/command/plugin/inspect.go index 9ce49eb908..baf166fccf 100644 --- a/cli/command/plugin/inspect.go +++ b/cli/command/plugin/inspect.go @@ -6,6 +6,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/inspect" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/spf13/cobra" ) @@ -28,7 +29,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVarP(&opts.format, "format", "f", "", "Format the output using the given Go template") + flags.StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) return cmd } diff --git a/cli/command/secret/inspect.go b/cli/command/secret/inspect.go index f7866de1bf..05962b9a8b 100644 --- a/cli/command/secret/inspect.go +++ b/cli/command/secret/inspect.go @@ -8,6 +8,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/spf13/cobra" ) @@ -29,7 +30,7 @@ func newSecretInspectCommand(dockerCli command.Cli) *cobra.Command { }, } - cmd.Flags().StringVarP(&opts.format, "format", "f", "", "Format the output using the given Go template") + cmd.Flags().StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) cmd.Flags().BoolVar(&opts.pretty, "pretty", false, "Print the information in a human friendly format") return cmd } diff --git a/cli/command/service/inspect.go b/cli/command/service/inspect.go index 38709963a1..a06149ec01 100644 --- a/cli/command/service/inspect.go +++ b/cli/command/service/inspect.go @@ -7,6 +7,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/docker/docker/api/types" apiclient "github.com/docker/docker/client" "github.com/pkg/errors" @@ -37,7 +38,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVarP(&opts.format, "format", "f", "", "Format the output using the given Go template") + flags.StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) flags.BoolVar(&opts.pretty, "pretty", false, "Print the information in a human friendly format") return cmd } diff --git a/cli/command/system/inspect.go b/cli/command/system/inspect.go index b49b4b33d3..56199aecde 100644 --- a/cli/command/system/inspect.go +++ b/cli/command/system/inspect.go @@ -8,6 +8,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/inspect" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/docker/docker/api/types" apiclient "github.com/docker/docker/client" "github.com/pkg/errors" @@ -36,7 +37,7 @@ func NewInspectCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVarP(&opts.format, "format", "f", "", "Format the output using the given Go template") + flags.StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) flags.StringVar(&opts.inspectType, "type", "", "Return JSON for specified type") flags.BoolVarP(&opts.size, "size", "s", false, "Display total file sizes if the type is container") diff --git a/cli/command/volume/inspect.go b/cli/command/volume/inspect.go index 52cfb0f0a9..3d3887635e 100644 --- a/cli/command/volume/inspect.go +++ b/cli/command/volume/inspect.go @@ -6,6 +6,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/inspect" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/spf13/cobra" ) @@ -27,7 +28,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { }, } - cmd.Flags().StringVarP(&opts.format, "format", "f", "", "Format the output using the given Go template") + cmd.Flags().StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) return cmd } diff --git a/cli/flags/common.go b/cli/flags/common.go index cf2ccb59a8..f692af75f7 100644 --- a/cli/flags/common.go +++ b/cli/flags/common.go @@ -21,6 +21,11 @@ const ( DefaultCertFile = "cert.pem" // FlagTLSVerify is the flag name for the TLS verification option FlagTLSVerify = "tlsverify" + // InspectFormatHelp describes the --format flag behavior for inspect commands + InspectFormatHelp = `Format output using a custom template: +'json': Print in JSON format +'TEMPLATE': Print output using the given Go template. +Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates` ) var ( diff --git a/docs/reference/commandline/config_inspect.md b/docs/reference/commandline/config_inspect.md index a2cf767ec5..1d8022bbbf 100644 --- a/docs/reference/commandline/config_inspect.md +++ b/docs/reference/commandline/config_inspect.md @@ -12,7 +12,11 @@ Usage: docker config inspect [OPTIONS] CONFIG [CONFIG...] Display detailed information on one or more configs Options: - -f, --format string Format the output using the given Go template + -f, --format string Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") + --pretty Print the information in a human friendly format --help Print usage ``` diff --git a/docs/reference/commandline/context_inspect.md b/docs/reference/commandline/context_inspect.md index 0b86829a9b..6d038b428f 100644 --- a/docs/reference/commandline/context_inspect.md +++ b/docs/reference/commandline/context_inspect.md @@ -12,7 +12,10 @@ Usage: docker context inspect [OPTIONS] [CONTEXT] [CONTEXT...] Display detailed information on one or more contexts Options: - -f, --format string Format the output using the given Go template + -f, --format string Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") ``` ## Description diff --git a/docs/reference/commandline/network_inspect.md b/docs/reference/commandline/network_inspect.md index 365ad13430..2c0150253a 100644 --- a/docs/reference/commandline/network_inspect.md +++ b/docs/reference/commandline/network_inspect.md @@ -12,7 +12,11 @@ Usage: docker network inspect [OPTIONS] NETWORK [NETWORK...] Display detailed information on one or more networks Options: - -f, --format string Format the output using the given Go template + -f, --format string Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") + -v, --verbose Verbose output for diagnostics --help Print usage ``` diff --git a/docs/reference/commandline/node_inspect.md b/docs/reference/commandline/node_inspect.md index 7f479046a4..0ac4289909 100644 --- a/docs/reference/commandline/node_inspect.md +++ b/docs/reference/commandline/node_inspect.md @@ -12,9 +12,12 @@ Usage: docker node inspect [OPTIONS] self|NODE [NODE...] Display detailed information on one or more nodes Options: - -f, --format string Format the output using the given Go template - --help Print usage + -f, --format string Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") --pretty Print the information in a human friendly format + --help Print usage ``` ## Description diff --git a/docs/reference/commandline/plugin_inspect.md b/docs/reference/commandline/plugin_inspect.md index 30caa13a36..2369dc1d1d 100644 --- a/docs/reference/commandline/plugin_inspect.md +++ b/docs/reference/commandline/plugin_inspect.md @@ -12,7 +12,10 @@ Usage: docker plugin inspect [OPTIONS] PLUGIN [PLUGIN...] Display detailed information on one or more plugins Options: - -f, --format string Format the output using the given Go template + -f, --format string Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") --help Print usage ``` diff --git a/docs/reference/commandline/secret_inspect.md b/docs/reference/commandline/secret_inspect.md index 41c4724e4e..ba5cc91211 100644 --- a/docs/reference/commandline/secret_inspect.md +++ b/docs/reference/commandline/secret_inspect.md @@ -12,7 +12,11 @@ Usage: docker secret inspect [OPTIONS] SECRET [SECRET...] Display detailed information on one or more secrets Options: - -f, --format string Format the output using the given Go template + -f, --format string Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") + --pretty Print the information in a human friendly format --help Print usage ``` diff --git a/docs/reference/commandline/service_inspect.md b/docs/reference/commandline/service_inspect.md index 1c204ee0f3..f284b7e94b 100644 --- a/docs/reference/commandline/service_inspect.md +++ b/docs/reference/commandline/service_inspect.md @@ -12,9 +12,12 @@ Usage: docker service inspect [OPTIONS] SERVICE [SERVICE...] Display detailed information on one or more services Options: - -f, --format string Format the output using the given Go template - --help Print usage + -f, --format string Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") --pretty Print the information in a human friendly format + --help Print usage ``` ## Description diff --git a/docs/reference/commandline/volume_inspect.md b/docs/reference/commandline/volume_inspect.md index 5204310ac7..9c2e3b75b1 100644 --- a/docs/reference/commandline/volume_inspect.md +++ b/docs/reference/commandline/volume_inspect.md @@ -12,7 +12,10 @@ Usage: docker volume inspect [OPTIONS] VOLUME [VOLUME...] Display detailed information on one or more volumes Options: - -f, --format string Format the output using the given Go template + -f, --format string Format output using a custom template: + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") --help Print usage ``` From eb27a94c3febc8118b447856a7758be937a480c0 Mon Sep 17 00:00:00 2001 From: Silvin Lubecki Date: Mon, 18 Jan 2021 17:09:21 +0100 Subject: [PATCH 3/8] Added "json" as specific value for --format flag in list commands, as an alias to `{{json .}}` Signed-off-by: Silvin Lubecki Signed-off-by: Sebastiaan van Stijn --- cli/command/formatter/formatter.go | 13 ++++- cli/command/formatter/formatter_test.go | 68 +++++++++++++++++++++++++ 2 files changed, 79 insertions(+), 2 deletions(-) create mode 100644 cli/command/formatter/formatter_test.go diff --git a/cli/command/formatter/formatter.go b/cli/command/formatter/formatter.go index 10ada78f93..ab0ebdfdfd 100644 --- a/cli/command/formatter/formatter.go +++ b/cli/command/formatter/formatter.go @@ -16,8 +16,10 @@ const ( TableFormatKey = "table" RawFormatKey = "raw" PrettyFormatKey = "pretty" + JSONFormatKey = "json" DefaultQuietFormat = "{{.ID}}" + jsonFormat = "{{json .}}" ) // Format is the format string rendered using the Context @@ -28,6 +30,11 @@ func (f Format) IsTable() bool { return strings.HasPrefix(string(f), TableFormatKey) } +// IsJSON returns true if the format is the json format +func (f Format) IsJSON() bool { + return string(f) == JSONFormatKey +} + // Contains returns true if the format contains the substring func (f Format) Contains(sub string) bool { return strings.Contains(string(f), sub) @@ -50,10 +57,12 @@ type Context struct { func (c *Context) preFormat() { c.finalFormat = string(c.Format) - // TODO: handle this in the Format type - if c.Format.IsTable() { + switch { + case c.Format.IsTable(): c.finalFormat = c.finalFormat[len(TableFormatKey):] + case c.Format.IsJSON(): + c.finalFormat = jsonFormat } c.finalFormat = strings.Trim(c.finalFormat, " ") diff --git a/cli/command/formatter/formatter_test.go b/cli/command/formatter/formatter_test.go new file mode 100644 index 0000000000..0f7ca93442 --- /dev/null +++ b/cli/command/formatter/formatter_test.go @@ -0,0 +1,68 @@ +package formatter + +import ( + "bytes" + "testing" + + "gotest.tools/v3/assert" +) + +func TestFormat(t *testing.T) { + f := Format("json") + assert.Assert(t, f.IsJSON()) + assert.Assert(t, !f.IsTable()) + + f = Format("table") + assert.Assert(t, !f.IsJSON()) + assert.Assert(t, f.IsTable()) + + f = Format("other") + assert.Assert(t, !f.IsJSON()) + assert.Assert(t, !f.IsTable()) +} + +type fakeSubContext struct { + Name string +} + +func (f fakeSubContext) FullHeader() interface{} { + return map[string]string{"Name": "NAME"} +} + +func TestContext(t *testing.T) { + testCases := []struct { + name string + format string + expected string + }{ + { + name: "json format", + format: JSONFormatKey, + expected: `{"Name":"test"} +`, + }, + { + name: "table format", + format: `table {{.Name}}`, + expected: `NAME +test +`, + }, + } + for _, tc := range testCases { + t.Run(tc.name, func(t *testing.T) { + buf := bytes.NewBuffer(nil) + ctx := Context{ + Format: Format(tc.format), + Output: buf, + } + subContext := fakeSubContext{Name: "test"} + subFormat := func(f func(sub SubContext) error) error { + return f(subContext) + } + err := ctx.Write(&subContext, subFormat) + assert.NilError(t, err) + assert.Equal(t, buf.String(), tc.expected) + }) + } +} From a4a734df448d91885b87858e4c14bb2b313f554a Mon Sep 17 00:00:00 2001 From: Silvin Lubecki Date: Wed, 10 Mar 2021 00:45:56 +0100 Subject: [PATCH 4/8] Update list commands with better format flag description including all the directives and a link to the documentation. Signed-off-by: Silvin Lubecki Signed-off-by: Sebastiaan van Stijn --- cli/command/config/ls.go | 3 ++- cli/command/container/list.go | 4 ++-- cli/command/container/stats.go | 3 ++- cli/command/context/list.go | 3 ++- cli/command/image/history.go | 3 ++- cli/command/image/list.go | 3 ++- cli/command/network/list.go | 3 ++- cli/command/node/list.go | 3 ++- cli/command/plugin/list.go | 3 ++- cli/command/secret/ls.go | 3 ++- cli/command/service/list.go | 3 ++- cli/command/stack/list.go | 3 ++- cli/command/stack/ps.go | 3 ++- cli/command/stack/services.go | 3 ++- cli/command/system/df.go | 3 ++- cli/command/volume/list.go | 3 ++- cli/flags/common.go | 7 +++++++ 17 files changed, 39 insertions(+), 17 deletions(-) diff --git a/cli/command/config/ls.go b/cli/command/config/ls.go index 57bb13320b..af463adbc6 100644 --- a/cli/command/config/ls.go +++ b/cli/command/config/ls.go @@ -7,6 +7,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/docker/cli/opts" "github.com/docker/docker/api/types" "github.com/fvbommel/sortorder" @@ -35,7 +36,7 @@ func newConfigListCommand(dockerCli command.Cli) *cobra.Command { flags := cmd.Flags() flags.BoolVarP(&listOpts.Quiet, "quiet", "q", false, "Only display IDs") - flags.StringVarP(&listOpts.Format, "format", "", "", "Pretty-print configs using a Go template") + flags.StringVarP(&listOpts.Format, "format", "", "", flagsHelper.FormatHelp) flags.VarP(&listOpts.Filter, "filter", "f", "Filter output based on conditions provided") return cmd diff --git a/cli/command/container/list.go b/cli/command/container/list.go index b9146506c6..99b5c7ef27 100644 --- a/cli/command/container/list.go +++ b/cli/command/container/list.go @@ -7,6 +7,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/docker/cli/opts" "github.com/docker/cli/templates" "github.com/docker/docker/api/types" @@ -46,7 +47,7 @@ func NewPsCommand(dockerCli command.Cli) *cobra.Command { flags.BoolVar(&options.noTrunc, "no-trunc", false, "Don't truncate output") flags.BoolVarP(&options.nLatest, "latest", "l", false, "Show the latest created container (includes all states)") flags.IntVarP(&options.last, "last", "n", -1, "Show n last created containers (includes all states)") - flags.StringVarP(&options.format, "format", "", "", "Pretty-print containers using a Go template") + flags.StringVarP(&options.format, "format", "", "", flagsHelper.FormatHelp) flags.VarP(&options.filter, "filter", "f", "Filter output based on conditions provided") return cmd @@ -80,7 +81,6 @@ func buildContainerListOptions(opts *psOptions) (*types.ContainerListOptions, er // Only requesting container size information when needed is an optimization, // because calculating the size is a costly operation. tmpl, err := templates.NewParse("", opts.format) - if err != nil { return nil, errors.Wrap(err, "failed to parse template") } diff --git a/cli/command/container/stats.go b/cli/command/container/stats.go index c6a193cf12..287fe02f7c 100644 --- a/cli/command/container/stats.go +++ b/cli/command/container/stats.go @@ -11,6 +11,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/docker/docker/api/types" "github.com/docker/docker/api/types/events" "github.com/docker/docker/api/types/filters" @@ -44,7 +45,7 @@ func NewStatsCommand(dockerCli command.Cli) *cobra.Command { flags.BoolVarP(&opts.all, "all", "a", false, "Show all containers (default shows just running)") flags.BoolVar(&opts.noStream, "no-stream", false, "Disable streaming stats and only pull the first result") flags.BoolVar(&opts.noTrunc, "no-trunc", false, "Do not truncate output") - flags.StringVar(&opts.format, "format", "", "Pretty-print images using a Go template") + flags.StringVar(&opts.format, "format", "", flagsHelper.FormatHelp) return cmd } diff --git a/cli/command/context/list.go b/cli/command/context/list.go index 3bffcd4d0f..8e8a71950f 100644 --- a/cli/command/context/list.go +++ b/cli/command/context/list.go @@ -9,6 +9,7 @@ import ( "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" "github.com/docker/cli/cli/context/docker" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/fvbommel/sortorder" "github.com/spf13/cobra" ) @@ -31,7 +32,7 @@ func newListCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVar(&opts.format, "format", "", "Pretty-print contexts using a Go template") + flags.StringVar(&opts.format, "format", "", flagsHelper.FormatHelp) flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Only show context names") return cmd } diff --git a/cli/command/image/history.go b/cli/command/image/history.go index d1bff9de20..fd98ee1399 100644 --- a/cli/command/image/history.go +++ b/cli/command/image/history.go @@ -6,6 +6,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/spf13/cobra" ) @@ -37,7 +38,7 @@ func NewHistoryCommand(dockerCli command.Cli) *cobra.Command { flags.BoolVarP(&opts.human, "human", "H", true, "Print sizes and dates in human readable format") flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Only show image IDs") flags.BoolVar(&opts.noTrunc, "no-trunc", false, "Don't truncate output") - flags.StringVar(&opts.format, "format", "", "Pretty-print images using a Go template") + flags.StringVar(&opts.format, "format", "", flagsHelper.FormatHelp) return cmd } diff --git a/cli/command/image/list.go b/cli/command/image/list.go index f60129d17a..7f1a8df3a7 100644 --- a/cli/command/image/list.go +++ b/cli/command/image/list.go @@ -6,6 +6,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/docker/cli/opts" "github.com/docker/docker/api/types" "github.com/spf13/cobra" @@ -44,7 +45,7 @@ func NewImagesCommand(dockerCli command.Cli) *cobra.Command { flags.BoolVarP(&options.all, "all", "a", false, "Show all images (default hides intermediate images)") flags.BoolVar(&options.noTrunc, "no-trunc", false, "Don't truncate output") flags.BoolVar(&options.showDigests, "digests", false, "Show digests") - flags.StringVar(&options.format, "format", "", "Pretty-print images using a Go template") + flags.StringVar(&options.format, "format", "", flagsHelper.FormatHelp) flags.VarP(&options.filter, "filter", "f", "Filter output based on conditions provided") return cmd diff --git a/cli/command/network/list.go b/cli/command/network/list.go index e72703b212..fa6abcb3e8 100644 --- a/cli/command/network/list.go +++ b/cli/command/network/list.go @@ -7,6 +7,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/docker/cli/opts" "github.com/docker/docker/api/types" "github.com/fvbommel/sortorder" @@ -36,7 +37,7 @@ func newListCommand(dockerCli command.Cli) *cobra.Command { flags := cmd.Flags() flags.BoolVarP(&options.quiet, "quiet", "q", false, "Only display network IDs") flags.BoolVar(&options.noTrunc, "no-trunc", false, "Do not truncate the output") - flags.StringVar(&options.format, "format", "", "Pretty-print networks using a Go template") + flags.StringVar(&options.format, "format", "", flagsHelper.FormatHelp) flags.VarP(&options.filter, "filter", "f", "Provide filter values (e.g. 'driver=bridge')") return cmd diff --git a/cli/command/node/list.go b/cli/command/node/list.go index d67f54a042..6fee9a9b11 100644 --- a/cli/command/node/list.go +++ b/cli/command/node/list.go @@ -7,6 +7,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/docker/cli/opts" "github.com/docker/docker/api/types" "github.com/fvbommel/sortorder" @@ -33,7 +34,7 @@ func newListCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() flags.BoolVarP(&options.quiet, "quiet", "q", false, "Only display IDs") - flags.StringVar(&options.format, "format", "", "Pretty-print nodes using a Go template") + flags.StringVar(&options.format, "format", "", flagsHelper.FormatHelp) flags.VarP(&options.filter, "filter", "f", "Filter output based on conditions provided") return cmd diff --git a/cli/command/plugin/list.go b/cli/command/plugin/list.go index c05eefae79..0a37fb6538 100644 --- a/cli/command/plugin/list.go +++ b/cli/command/plugin/list.go @@ -7,6 +7,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/docker/cli/opts" "github.com/fvbommel/sortorder" "github.com/spf13/cobra" @@ -36,7 +37,7 @@ func newListCommand(dockerCli command.Cli) *cobra.Command { flags.BoolVarP(&options.quiet, "quiet", "q", false, "Only display plugin IDs") flags.BoolVar(&options.noTrunc, "no-trunc", false, "Don't truncate output") - flags.StringVar(&options.format, "format", "", "Pretty-print plugins using a Go template") + flags.StringVar(&options.format, "format", "", flagsHelper.FormatHelp) flags.VarP(&options.filter, "filter", "f", "Provide filter values (e.g. 'enabled=true')") return cmd diff --git a/cli/command/secret/ls.go b/cli/command/secret/ls.go index 5d1d54150a..c1f11f88d4 100644 --- a/cli/command/secret/ls.go +++ b/cli/command/secret/ls.go @@ -7,6 +7,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/docker/cli/opts" "github.com/docker/docker/api/types" "github.com/fvbommel/sortorder" @@ -34,7 +35,7 @@ func newSecretListCommand(dockerCli command.Cli) *cobra.Command { flags := cmd.Flags() flags.BoolVarP(&options.quiet, "quiet", "q", false, "Only display IDs") - flags.StringVarP(&options.format, "format", "", "", "Pretty-print secrets using a Go template") + flags.StringVarP(&options.format, "format", "", "", flagsHelper.FormatHelp) flags.VarP(&options.filter, "filter", "f", "Filter output based on conditions provided") return cmd diff --git a/cli/command/service/list.go b/cli/command/service/list.go index 56cb3a23ba..842205a579 100644 --- a/cli/command/service/list.go +++ b/cli/command/service/list.go @@ -6,6 +6,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/docker/cli/opts" "github.com/docker/docker/api/types" "github.com/docker/docker/api/types/filters" @@ -35,7 +36,7 @@ func newListCommand(dockerCli command.Cli) *cobra.Command { flags := cmd.Flags() flags.BoolVarP(&options.quiet, "quiet", "q", false, "Only display IDs") - flags.StringVar(&options.format, "format", "", "Pretty-print services using a Go template") + flags.StringVar(&options.format, "format", "", flagsHelper.FormatHelp) flags.VarP(&options.filter, "filter", "f", "Filter output based on conditions provided") return cmd diff --git a/cli/command/stack/list.go b/cli/command/stack/list.go index 17f2e7947b..866961b2e5 100644 --- a/cli/command/stack/list.go +++ b/cli/command/stack/list.go @@ -8,6 +8,7 @@ import ( "github.com/docker/cli/cli/command/stack/formatter" "github.com/docker/cli/cli/command/stack/options" "github.com/docker/cli/cli/command/stack/swarm" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/fvbommel/sortorder" "github.com/spf13/cobra" ) @@ -26,7 +27,7 @@ func newListCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVar(&opts.Format, "format", "", "Pretty-print stacks using a Go template") + flags.StringVar(&opts.Format, "format", "", flagsHelper.FormatHelp) return cmd } diff --git a/cli/command/stack/ps.go b/cli/command/stack/ps.go index 3dd8f82cc6..cbe992cfa5 100644 --- a/cli/command/stack/ps.go +++ b/cli/command/stack/ps.go @@ -5,6 +5,7 @@ import ( "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/stack/options" "github.com/docker/cli/cli/command/stack/swarm" + flagsHelper "github.com/docker/cli/cli/flags" cliopts "github.com/docker/cli/opts" "github.com/spf13/cobra" "github.com/spf13/pflag" @@ -30,7 +31,7 @@ func newPsCommand(dockerCli command.Cli) *cobra.Command { flags.BoolVar(&opts.NoResolve, "no-resolve", false, "Do not map IDs to Names") flags.VarP(&opts.Filter, "filter", "f", "Filter output based on conditions provided") flags.BoolVarP(&opts.Quiet, "quiet", "q", false, "Only display task IDs") - flags.StringVar(&opts.Format, "format", "", "Pretty-print tasks using a Go template") + flags.StringVar(&opts.Format, "format", "", flagsHelper.FormatHelp) return cmd } diff --git a/cli/command/stack/services.go b/cli/command/stack/services.go index c955af2785..456a1fad04 100644 --- a/cli/command/stack/services.go +++ b/cli/command/stack/services.go @@ -10,6 +10,7 @@ import ( "github.com/docker/cli/cli/command/stack/formatter" "github.com/docker/cli/cli/command/stack/options" "github.com/docker/cli/cli/command/stack/swarm" + flagsHelper "github.com/docker/cli/cli/flags" cliopts "github.com/docker/cli/opts" swarmtypes "github.com/docker/docker/api/types/swarm" "github.com/fvbommel/sortorder" @@ -34,7 +35,7 @@ func newServicesCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() flags.BoolVarP(&opts.Quiet, "quiet", "q", false, "Only display IDs") - flags.StringVar(&opts.Format, "format", "", "Pretty-print services using a Go template") + flags.StringVar(&opts.Format, "format", "", flagsHelper.FormatHelp) flags.VarP(&opts.Filter, "filter", "f", "Filter output based on conditions provided") return cmd } diff --git a/cli/command/system/df.go b/cli/command/system/df.go index ba91c9d1be..bb1bf2cf43 100644 --- a/cli/command/system/df.go +++ b/cli/command/system/df.go @@ -6,6 +6,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/docker/docker/api/types" "github.com/spf13/cobra" ) @@ -32,7 +33,7 @@ func newDiskUsageCommand(dockerCli command.Cli) *cobra.Command { flags := cmd.Flags() flags.BoolVarP(&opts.verbose, "verbose", "v", false, "Show detailed information on space usage") - flags.StringVar(&opts.format, "format", "", "Pretty-print images using a Go template") + flags.StringVar(&opts.format, "format", "", flagsHelper.FormatHelp) return cmd } diff --git a/cli/command/volume/list.go b/cli/command/volume/list.go index 4793e72d51..7b5a27ac8e 100644 --- a/cli/command/volume/list.go +++ b/cli/command/volume/list.go @@ -7,6 +7,7 @@ import ( "github.com/docker/cli/cli" "github.com/docker/cli/cli/command" "github.com/docker/cli/cli/command/formatter" + flagsHelper "github.com/docker/cli/cli/flags" "github.com/docker/cli/opts" "github.com/fvbommel/sortorder" "github.com/spf13/cobra" @@ -33,7 +34,7 @@ func newListCommand(dockerCli command.Cli) *cobra.Command { flags := cmd.Flags() flags.BoolVarP(&options.quiet, "quiet", "q", false, "Only display volume names") - flags.StringVar(&options.format, "format", "", "Pretty-print volumes using a Go template") + flags.StringVar(&options.format, "format", "", flagsHelper.FormatHelp) flags.VarP(&options.filter, "filter", "f", "Provide filter values (e.g. 'dangling=true')") return cmd diff --git a/cli/flags/common.go b/cli/flags/common.go index f692af75f7..a770333a49 100644 --- a/cli/flags/common.go +++ b/cli/flags/common.go @@ -21,6 +21,13 @@ const ( DefaultCertFile = "cert.pem" // FlagTLSVerify is the flag name for the TLS verification option FlagTLSVerify = "tlsverify" + // FormatHelp describes the --format flag behavior for list commands + FormatHelp = `Format output using a custom template: +'table': Print output in table format with column headers (default) +'table TEMPLATE': Print output in table format using the given Go template +'json': Print in JSON format +'TEMPLATE': Print output using the given Go template. +Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates` // InspectFormatHelp describes the --format flag behavior for inspect commands InspectFormatHelp = `Format output using a custom template: 'json': Print in JSON format From 0611be0f099e65fddf7d1c7a319afa873c89ba7e Mon Sep 17 00:00:00 2001 From: Silvin Lubecki Date: Wed, 10 Mar 2021 00:49:13 +0100 Subject: [PATCH 5/8] Update man pages Signed-off-by: Silvin Lubecki --- man/src/container/ls.md | 5 +++++ man/src/container/stats.md | 7 ++++++- man/src/image/ls.md | 16 ++++++++++++---- man/src/plugin/ls.md | 7 ++++++- 4 files changed, 29 insertions(+), 6 deletions(-) diff --git a/man/src/container/ls.md b/man/src/container/ls.md index 93a87efcab..2bbef0c16e 100644 --- a/man/src/container/ls.md +++ b/man/src/container/ls.md @@ -115,3 +115,8 @@ Valid placeholders for the Go template are listed below: $ docker ps --filter expose=8000-8080/tcp CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 9833437217a5 busybox "top" 21 seconds ago Up 19 seconds 8080/tcp dreamy_mccarthy + +## Display containers in JSON format: + + $ docker ps --format json + {"Command":"\"/docker-entrypoint.…\"","CreatedAt":"2021-03-10 00:15:05 +0100 CET","ID":"a762a2b37a1d","Image":"nginx","Labels":"maintainer=NGINX Docker Maintainers \u003cdocker-maint@nginx.com\u003e","LocalVolumes":"0","Mounts":"","Names":"boring_keldysh","Networks":"bridge","Ports":"80/tcp","RunningFor":"4 seconds ago","Size":"0B","State":"running","Status":"Up 3 seconds"} diff --git a/man/src/container/stats.md b/man/src/container/stats.md index 2de672ee2e..f824417ff2 100644 --- a/man/src/container/stats.md +++ b/man/src/container/stats.md @@ -2,7 +2,7 @@ Display a live stream of one or more containers' resource usage statistics # Format - Pretty-print containers statistics using a Go template. + Format the output using the given Go template. Valid placeholders: .Container - Container name or ID. .Name - Container name. @@ -41,3 +41,8 @@ Running `docker container stats` with customized format on all (Running and Stop 5a8b07ec4cc52823f3cbfdb964018623c1ba307bce2c057ccdbde5f4f6990833 big_heisenberg 0.00% 0B / 0B `drunk_visvesvaraya` and `big_heisenberg` are stopped containers in the above example. + +Running `docker container stats` in JSON format. + + $ docker container stats --format json + {"BlockIO":"43.9MB / 0B","CPUPerc":"0.00%","Container":"14c505d03da8","ID":"14c505d03da8","MemPerc":"0.21%","MemUsage":"4.242MiB / 1.944GiB","Name":"registry","NetIO":"4.17kB / 0B","PIDs":"13"} \ No newline at end of file diff --git a/man/src/image/ls.md b/man/src/image/ls.md index 7e32749911..cf15937e06 100644 --- a/man/src/image/ls.md +++ b/man/src/image/ls.md @@ -25,7 +25,7 @@ Filters the output based on these conditions: ## Format - Pretty-print images using a Go template. + Format the output using the given Go template. Valid placeholders: .ID - Image ID .Repository - Image repository @@ -78,12 +78,13 @@ still find it in the third-party dockviz tool: https://github.com/justone/dockvi When using the --format option, the image command will either output the data exactly as the template declares or, when using the `table` directive, will include column headers as well. You can use special characters like `\t` for -inserting tab spacing between columns. +inserting tab spacing between columns. The `json` directive outputs objects +in JSON format. The following example uses a template without headers and outputs the ID and Repository entries separated by a colon for all images: - docker images --format "{{.ID}}: {{.Repository}}" + docker image ls --format "{{.ID}}: {{.Repository}}" 77af4d6b9913: b6fa739cedf5: committ 78a85c484bad: ipbabble @@ -96,7 +97,7 @@ Repository entries separated by a colon for all images: To list all images with their repository and tag in a table format you can use: - docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" + docker image ls --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}" IMAGE ID REPOSITORY TAG 77af4d6b9913 b6fa739cedf5 committ latest @@ -110,6 +111,13 @@ To list all images with their repository and tag in a table format you can use: Valid template placeholders are listed above. +To list all images in JSON format you can use: + + docker image ls --format json + {"Containers":"N/A","CreatedAt":"2021-01-18 11:29:06 +0100 CET","CreatedSince":"24 hours ago","Digest":"\u003cnone\u003e","ID":"fbcf509fa16f","Repository":"docker","SharedSize":"N/A","Size":"235MB","Tag":"stable-dind","UniqueSize":"N/A","VirtualSize":"235.5MB"} + {"Containers":"N/A","CreatedAt":"2021-01-18 11:24:48 +0100 CET","CreatedSince":"24 hours ago","Digest":"\u003cnone\u003e","ID":"08656a69ab2b","Repository":"docker-cli-e2e","SharedSize":"N/A","Size":"1.21GB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"1.207GB"} + {"Containers":"N/A","CreatedAt":"2021-01-18 10:43:44 +0100 CET","CreatedSince":"24 hours ago","Digest":"\u003cnone\u003e","ID":"abca5c07c1ba","Repository":"docker-cli-dev","SharedSize":"N/A","Size":"608MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"607.8MB"} + ## Listing only the shortened image IDs Listing just the shortened image IDs. This can be useful for some automated diff --git a/man/src/plugin/ls.md b/man/src/plugin/ls.md index f9f3945244..23b0659b5b 100644 --- a/man/src/plugin/ls.md +++ b/man/src/plugin/ls.md @@ -10,7 +10,7 @@ Filter output based on these conditions: ## Format - Pretty-print plugins using a Go template. + Format the output using the given Go template. Valid placeholders: .ID - Plugin ID. .Name - Plugin Name. @@ -30,6 +30,11 @@ Filter output based on these conditions: $ docker plugin ls --format "{{.ID}}: {{.Name}}" 869080b57404: tiborvass/sample-volume-plugin:latest +## Display plugins in JSON format + + $ docker plugin ls --format json + {"Description":"A sample volume plugin for Docker","Enabled":true,"ID":"2788a2da7e12","Name":"tiborvass/sample-volume-plugin:latest","PluginReference":"docker.io/tiborvass/sample-volume-plugin:latest"} + ## Display enabled plugins $ docker plugin ls --filter enabled=true From b4af799686dca6e0a48707321d2a98dfd375a2f2 Mon Sep 17 00:00:00 2001 From: Silvin Lubecki Date: Wed, 10 Mar 2021 00:49:33 +0100 Subject: [PATCH 6/8] Update reference documentation Signed-off-by: Silvin Lubecki Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/context_ls.md | 10 +++++++--- docs/reference/commandline/images.md | 15 ++++++++++++++- docs/reference/commandline/info.md | 2 +- docs/reference/commandline/network_ls.md | 16 +++++++++++++++- docs/reference/commandline/node_ls.md | 12 +++++++++++- docs/reference/commandline/plugin_ls.md | 13 ++++++++++++- docs/reference/commandline/ps.md | 13 ++++++++++++- docs/reference/commandline/secret_ls.md | 14 +++++++++++++- docs/reference/commandline/service_ls.md | 13 ++++++++++++- docs/reference/commandline/stack_ls.md | 13 ++++++++++++- docs/reference/commandline/stack_ps.md | 15 ++++++++++++++- docs/reference/commandline/stack_services.md | 15 ++++++++++++++- docs/reference/commandline/system_df.md | 16 +++++++++++++++- docs/reference/commandline/volume_ls.md | 13 ++++++++++++- 14 files changed, 164 insertions(+), 16 deletions(-) diff --git a/docs/reference/commandline/context_ls.md b/docs/reference/commandline/context_ls.md index d691b46c7f..aec714b5d4 100644 --- a/docs/reference/commandline/context_ls.md +++ b/docs/reference/commandline/context_ls.md @@ -15,8 +15,12 @@ Aliases: ls, list Options: - --format string Pretty-print contexts using a Go template - (default "table") + --format string Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates -q, --quiet Only show context names ``` @@ -32,4 +36,4 @@ NAME DESCRIPTION DOCKER ENDPOINT default * Current DOCKER_HOST based configuration unix:///var/run/docker.sock swarm production tcp:///prod.corp.example.com:2376 staging tcp:///stage.corp.example.com:2376 -``` +``` \ No newline at end of file diff --git a/docs/reference/commandline/images.md b/docs/reference/commandline/images.md index 5577de44be..6c5882c939 100644 --- a/docs/reference/commandline/images.md +++ b/docs/reference/commandline/images.md @@ -20,7 +20,12 @@ Options: - before=([:tag]||) - since=([:tag]||) - reference=(pattern of an image reference) - --format string Pretty-print images using a Go template + --format string Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --help Print usage --no-trunc Don't truncate output -q, --quiet Only show image IDs @@ -341,3 +346,11 @@ b6fa739cedf5 committ latest 746b819f315e postgres 9.3.5 746b819f315e postgres latest ``` + +To list all images in JSON format, use the `json` directive: + +```console +$ docker images --format json +{"Containers":"N/A","CreatedAt":"2021-03-04 03:24:42 +0100 CET","CreatedSince":"5 days ago","Digest":"\u003cnone\u003e","ID":"4dd97cefde62","Repository":"ubuntu","SharedSize":"N/A","Size":"72.9MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"72.9MB"} +{"Containers":"N/A","CreatedAt":"2021-02-17 22:19:54 +0100 CET","CreatedSince":"2 weeks ago","Digest":"\u003cnone\u003e","ID":"28f6e2705743","Repository":"alpine","SharedSize":"N/A","Size":"5.61MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"5.613MB"} +``` \ No newline at end of file diff --git a/docs/reference/commandline/info.md b/docs/reference/commandline/info.md index 0071edd862..316e301ab6 100644 --- a/docs/reference/commandline/info.md +++ b/docs/reference/commandline/info.md @@ -12,7 +12,7 @@ Usage: docker info [OPTIONS] Display system-wide information Options: - -f, --format string Format the output using the given Go template + -f, --format string Format the output using the given Go template (default "json") --help Print usage ``` diff --git a/docs/reference/commandline/network_ls.md b/docs/reference/commandline/network_ls.md index 8b938b33be..98b43d2909 100644 --- a/docs/reference/commandline/network_ls.md +++ b/docs/reference/commandline/network_ls.md @@ -16,7 +16,12 @@ Aliases: Options: -f, --filter filter Provide filter values (e.g. 'driver=bridge') - --format string Pretty-print networks using a Go template + --format string Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --help Print usage --no-trunc Do not truncate the output -q, --quiet Only display network IDs @@ -230,6 +235,15 @@ d1584f8dc718: host 391df270dc66: null ``` +To list all networks in JSON format, use the `json` directive: + +```console +$ docker network ls --format json +{"CreatedAt":"2021-03-09 21:41:29.798999529 +0000 UTC","Driver":"bridge","ID":"f33ba176dd8e","IPv6":"false","Internal":"false","Labels":"","Name":"bridge","Scope":"local"} +{"CreatedAt":"2021-03-09 21:41:29.772806592 +0000 UTC","Driver":"host","ID":"caf47bb3ac70","IPv6":"false","Internal":"false","Labels":"","Name":"host","Scope":"local"} +{"CreatedAt":"2021-03-09 21:41:29.752212603 +0000 UTC","Driver":"null","ID":"9d096c122066","IPv6":"false","Internal":"false","Labels":"","Name":"none","Scope":"local"} +``` + ## Related commands * [network disconnect ](network_disconnect.md) diff --git a/docs/reference/commandline/node_ls.md b/docs/reference/commandline/node_ls.md index 11e3296972..ecc7aa0afc 100644 --- a/docs/reference/commandline/node_ls.md +++ b/docs/reference/commandline/node_ls.md @@ -16,7 +16,12 @@ Aliases: Options: -f, --filter filter Filter output based on conditions provided - --format string Pretty-print nodes using a Go template + --format string Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --help Print usage -q, --quiet Only display IDs ``` @@ -203,6 +208,11 @@ e216jshn25ckzbvmwlnh5jr3g: swarm-manager1 Ready 35o6tiywb700jesrt3dmllaza: swarm-worker1 Needs Rotation ``` +To list all nodes in JSON format, use the `json` directive: +```console +$ docker node ls --format json +{"Availability":"Active","EngineVersion":"20.10.5","Hostname":"docker-desktop","ID":"k8f4w7qtzpj5sqzclcqafw35g","ManagerStatus":"Leader","Self":true,"Status":"Ready","TLSStatus":"Ready"} +``` ## Related commands diff --git a/docs/reference/commandline/plugin_ls.md b/docs/reference/commandline/plugin_ls.md index 47a657d9d8..2ce47588c0 100644 --- a/docs/reference/commandline/plugin_ls.md +++ b/docs/reference/commandline/plugin_ls.md @@ -16,7 +16,12 @@ Aliases: Options: -f, --filter filter Provide filter values (e.g. 'enabled=true') - --format string Pretty-print plugins using a Go template + --format string Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --help Print usage --no-trunc Don't truncate output -q, --quiet Only display plugin IDs @@ -96,6 +101,12 @@ $ docker plugin ls --format "{{.ID}}: {{.Name}}" 4be01827a72e: vieux/sshfs:latest ``` +To list all plugins in JSON format, use the `json` directive: +```console +$ docker plugin ls --format json +{"Description":"sshFS plugin for Docker","Enabled":false,"ID":"856d89febb1c","Name":"vieux/sshfs:latest","PluginReference":"docker.io/vieux/sshfs:latest"} +``` + ## Related commands * [plugin create](plugin_create.md) diff --git a/docs/reference/commandline/ps.md b/docs/reference/commandline/ps.md index 02f8e27f22..1f575d7221 100644 --- a/docs/reference/commandline/ps.md +++ b/docs/reference/commandline/ps.md @@ -30,7 +30,12 @@ Options: - since=(|) - status=(created|restarting|removing|running|paused|exited) - volume=(|) - --format string Pretty-print containers using a Go template + --format string Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --help Print usage -n, --last int Show n last created containers (includes all states) (default -1) -l, --latest Show the latest created container (includes all states) @@ -445,3 +450,9 @@ a87ecb4f327c com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd c1d3b0166030 com.docker.swarm.node=debian,com.docker.swarm.cpu=6 41d50ecd2f57 com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd ``` + +To list all running containers in JSON format, use the `json` directive: +```console +$ docker ps --format json +{"Command":"\"/docker-entrypoint.…\"","CreatedAt":"2021-03-10 00:15:05 +0100 CET","ID":"a762a2b37a1d","Image":"nginx","Labels":"maintainer=NGINX Docker Maintainers \u003cdocker-maint@nginx.com\u003e","LocalVolumes":"0","Mounts":"","Names":"boring_keldysh","Networks":"bridge","Ports":"80/tcp","RunningFor":"4 seconds ago","Size":"0B","State":"running","Status":"Up 3 seconds"} +``` \ No newline at end of file diff --git a/docs/reference/commandline/secret_ls.md b/docs/reference/commandline/secret_ls.md index 395af6102e..ec5b1a4348 100644 --- a/docs/reference/commandline/secret_ls.md +++ b/docs/reference/commandline/secret_ls.md @@ -16,7 +16,13 @@ Aliases: Options: -f, --filter filter Filter output based on conditions provided - --format string Pretty-print secrets using a Go template + --format string Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates + --help Print usage -q, --quiet Only display IDs ``` @@ -148,6 +154,12 @@ b6fa739cedf5 secret-2 3 hours ago 78a85c484f71 secret-3 10 days ago ``` +To list all secrets in JSON format, use the `json` directive: +```console +$ docker secret ls --format json +{"CreatedAt":"28 seconds ago","Driver":"","ID":"4y7hvwrt1u8e9uxh5ygqj7mzc","Labels":"","Name":"mysecret","UpdatedAt":"28 seconds ago"} +``` + ## Related commands * [secret create](secret_create.md) diff --git a/docs/reference/commandline/service_ls.md b/docs/reference/commandline/service_ls.md index 97f7763abe..b9bf1c1033 100644 --- a/docs/reference/commandline/service_ls.md +++ b/docs/reference/commandline/service_ls.md @@ -16,7 +16,12 @@ Aliases: Options: -f, --filter filter Filter output based on conditions provided - --format string Pretty-print services using a Go template + --format string Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --help Print usage -q, --quiet Only display IDs ``` @@ -153,6 +158,12 @@ $ docker service ls --format "{{.ID}}: {{.Mode}} {{.Replicas}}" fm6uf97exkul: global 5/5 ``` +To list all services in JSON format, use the `json` directive: +```console +$ docker service ls --format json +{"ID":"ssniordqolsi","Image":"hello-world:latest","Mode":"replicated","Name":"hello","Ports":"","Replicas":"0/1"} +``` + ## Related commands * [service create](service_create.md) diff --git a/docs/reference/commandline/stack_ls.md b/docs/reference/commandline/stack_ls.md index 453db5f588..d6b7dccabc 100644 --- a/docs/reference/commandline/stack_ls.md +++ b/docs/reference/commandline/stack_ls.md @@ -16,7 +16,12 @@ Aliases: Options: --help Print usage - --format string Pretty-print stacks using a Go template + --format string Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates ``` ## Description @@ -68,6 +73,12 @@ web-server: 1 web-cache: 4 ``` +To list all stacks in JSON format, use the `json` directive: +```console +$ docker stack ls --format json +{"Name":"myapp","Namespace":"","Orchestrator":"Swarm","Services":"3"} +``` + ## Related commands * [stack deploy](stack_deploy.md) diff --git a/docs/reference/commandline/stack_ps.md b/docs/reference/commandline/stack_ps.md index 6328064892..0f124f9df9 100644 --- a/docs/reference/commandline/stack_ps.md +++ b/docs/reference/commandline/stack_ps.md @@ -13,7 +13,12 @@ List the tasks in the stack Options: -f, --filter filter Filter output based on conditions provided - --format string Pretty-print tasks using a Go template + --format string Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --help Print usage --no-resolve Do not map IDs to Names --no-trunc Do not truncate output @@ -157,6 +162,14 @@ voting_vote.2: dockersamples/examplevotingapp_vote:before voting_redis.2: redis:alpine ``` +To list all tasks in JSON format, use the `json` directive: +```console +$ docker stack ps --format json myapp +{"CurrentState":"Preparing 23 seconds ago","DesiredState":"Running","Error":"","ID":"2ufjubh79tn0","Image":"localstack/localstack:latest","Name":"myapp_localstack.1","Node":"docker-desktop","Ports":""} +{"CurrentState":"Running 20 seconds ago","DesiredState":"Running","Error":"","ID":"roee387ngf5r","Image":"redis:6.0.9-alpine3.12","Name":"myapp_redis.1","Node":"docker-desktop","Ports":""} +{"CurrentState":"Preparing 13 seconds ago","DesiredState":"Running","Error":"","ID":"yte68ouq7glh","Image":"postgres:13.2-alpine","Name":"myapp_repos-db.1","Node":"docker-desktop","Ports":""} +``` + ### Do not map IDs to Names The `--no-resolve` option shows IDs for task name, without mapping IDs to Names. diff --git a/docs/reference/commandline/stack_services.md b/docs/reference/commandline/stack_services.md index 8be549c48a..ba58179c56 100644 --- a/docs/reference/commandline/stack_services.md +++ b/docs/reference/commandline/stack_services.md @@ -13,7 +13,12 @@ List the services in the stack Options: -f, --filter filter Filter output based on conditions provided - --format string Pretty-print services using a Go template + --format string Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --help Print usage -q, --quiet Only display IDs ``` @@ -98,6 +103,14 @@ $ docker stack services --format "{{.ID}}: {{.Mode}} {{.Replicas}}" fm6uf97exkul: global 5/5 ``` +To list all services in JSON format, use the `json` directive: +```console +$ docker stack services ls --format json +{"ID":"0axqbl293vwm","Image":"localstack/localstack:latest","Mode":"replicated","Name":"myapp_localstack","Ports":"*:4566-\u003e4566/tcp, *:8080-\u003e8080/tcp","Replicas":"0/1"} +{"ID":"384xvtzigz3p","Image":"redis:6.0.9-alpine3.12","Mode":"replicated","Name":"myapp_redis","Ports":"*:6379-\u003e6379/tcp","Replicas":"1/1"} +{"ID":"hyujct8cnjkk","Image":"postgres:13.2-alpine","Mode":"replicated","Name":"myapp_repos-db","Ports":"*:5432-\u003e5432/tcp","Replicas":"0/1"} +``` + ## Related commands diff --git a/docs/reference/commandline/system_df.md b/docs/reference/commandline/system_df.md index a5f1e6d23d..fe72cc53fe 100644 --- a/docs/reference/commandline/system_df.md +++ b/docs/reference/commandline/system_df.md @@ -12,7 +12,12 @@ Usage: docker system df [OPTIONS] Show docker filesystem usage Options: - --format string Pretty-print images using a Go template + --format string Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --help Print usage -v, --verbose Show detailed information on space usage ``` @@ -122,6 +127,15 @@ Local Volumes 150.3 MB 150.3 MB (100%) ``` +To list all information in JSON format, use the `json` directive: +```console +$ docker system df --format json +{"Active":"2","Reclaimable":"2.498GB (94%)","Size":"2.631GB","TotalCount":"6","Type":"Images"} +{"Active":"1","Reclaimable":"1.114kB (49%)","Size":"2.23kB","TotalCount":"7","Type":"Containers"} +{"Active":"0","Reclaimable":"256.5MB (100%)","Size":"256.5MB","TotalCount":"1","Type":"Local Volumes"} +{"Active":"0","Reclaimable":"158B","Size":"158B","TotalCount":"17","Type":"Build Cache"} +``` + **Note** the format option is meaningless when verbose is true. ## Related commands diff --git a/docs/reference/commandline/volume_ls.md b/docs/reference/commandline/volume_ls.md index f010cfd605..4bf7ad75e2 100644 --- a/docs/reference/commandline/volume_ls.md +++ b/docs/reference/commandline/volume_ls.md @@ -20,7 +20,12 @@ Options: - driver= a volume's driver name - label= or label== - name= a volume's name - --format string Pretty-print volumes using a Go template + --format string Format output using a custom template: + 'table': Print output in table format with column headers (default) + 'table TEMPLATE': Print output in table format using the given Go template + 'json': Print in JSON format + 'TEMPLATE': Print output using the given Go template. + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --help Print usage -q, --quiet Only display volume names ``` @@ -182,6 +187,12 @@ vol2: local vol3: local ``` +To list all volumes in JSON format, use the `json` directive: +```console +$ docker volume ls --format json +{"Driver":"local","Labels":"","Links":"N/A","Mountpoint":"/var/lib/docker/volumes/docker-cli-dev-cache/_data","Name":"docker-cli-dev-cache","Scope":"local","Size":"N/A"} +``` + ## Related commands * [volume create](volume_create.md) From d8ecb00dda15702124e27bc2bce1e6a9fb3478ba Mon Sep 17 00:00:00 2001 From: Silvin Lubecki Date: Wed, 10 Mar 2021 00:50:05 +0100 Subject: [PATCH 7/8] Update shell completion scripts Signed-off-by: Silvin Lubecki --- contrib/completion/fish/docker.fish | 4 ++-- contrib/completion/zsh/_docker | 14 +++++++------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/contrib/completion/fish/docker.fish b/contrib/completion/fish/docker.fish index 41984746a7..eb3ddcc676 100644 --- a/contrib/completion/fish/docker.fish +++ b/contrib/completion/fish/docker.fish @@ -307,7 +307,7 @@ complete -c docker -A -f -n '__fish_seen_subcommand_from export' -a '(__fish_pri # history complete -c docker -f -n '__fish_docker_no_subcommand' -a history -d 'Show the history of an image' -complete -c docker -A -f -n '__fish_seen_subcommand_from history' -l format -d 'Pretty-print images using a Go template' +complete -c docker -A -f -n '__fish_seen_subcommand_from history' -l format -d 'Format the output using the given Go template' complete -c docker -A -f -n '__fish_seen_subcommand_from history' -l help -d 'Print usage' complete -c docker -A -f -n '__fish_seen_subcommand_from history' -s H -l human -d 'Print sizes and dates in human readable format' complete -c docker -A -f -n '__fish_seen_subcommand_from history' -l no-trunc -d "Don't truncate output" @@ -319,7 +319,7 @@ complete -c docker -f -n '__fish_docker_no_subcommand' -a images -d 'List images complete -c docker -A -f -n '__fish_seen_subcommand_from images' -s a -l all -d 'Show all images (default hides intermediate images)' complete -c docker -A -f -n '__fish_seen_subcommand_from images' -l digests -d 'Show digests' complete -c docker -A -f -n '__fish_seen_subcommand_from images' -s f -l filter -d 'Filter output based on conditions provided' -complete -c docker -A -f -n '__fish_seen_subcommand_from images' -l format -d 'Pretty-print images using a Go template' +complete -c docker -A -f -n '__fish_seen_subcommand_from images' -l format -d 'Format the output using the given Go template' complete -c docker -A -f -n '__fish_seen_subcommand_from images' -l help -d 'Print usage' complete -c docker -A -f -n '__fish_seen_subcommand_from images' -l no-trunc -d "Don't truncate output" complete -c docker -A -f -n '__fish_seen_subcommand_from images' -s q -l quiet -d 'Only show image IDs' diff --git a/contrib/completion/zsh/_docker b/contrib/completion/zsh/_docker index bad961ebbd..4923d91536 100644 --- a/contrib/completion/zsh/_docker +++ b/contrib/completion/zsh/_docker @@ -803,7 +803,7 @@ __docker_container_subcommand() { "($help -a --all)"{-a,--all}"[Show all containers]" \ "($help)--before=[Show only container created before...]:containers:__docker_complete_containers" \ "($help)*"{-f=,--filter=}"[Filter values]:filter:__docker_complete_ps_filters" \ - "($help)--format=[Pretty-print containers using a Go template]:template: " \ + "($help)--format=[Format the output using the given Go template]:template: " \ "($help -l --latest)"{-l,--latest}"[Show only the latest created container]" \ "($help -n --last)"{-n=,--last=}"[Show n last created containers (includes all states)]:n:(1 5 10 25 50)" \ "($help)--no-trunc[Do not truncate output]" \ @@ -908,7 +908,7 @@ __docker_container_subcommand() { _arguments $(__docker_arguments) \ $opts_help \ "($help -a --all)"{-a,--all}"[Show all containers (default shows just running)]" \ - "($help)--format=[Pretty-print images using a Go template]:template: " \ + "($help)--format=[Format the output using the given Go template]:template: " \ "($help)--no-stream[Disable streaming stats and only pull the first result]" \ "($help)--no-trunc[Do not truncate output]" \ "($help -)*:containers:__docker_complete_running_containers" && ret=0 @@ -1061,7 +1061,7 @@ __docker_image_subcommand() { "($help -a --all)"{-a,--all}"[Show all images]" \ "($help)--digests[Show digests]" \ "($help)*"{-f=,--filter=}"[Filter values]:filter:__docker_complete_images_filters" \ - "($help)--format=[Pretty-print images using a Go template]:template: " \ + "($help)--format=[Format the output using the given Go template]:template: " \ "($help)--no-trunc[Do not truncate output]" \ "($help -q --quiet)"{-q,--quiet}"[Only show image IDs]" \ "($help -): :__docker_complete_repositories" && ret=0 @@ -1293,7 +1293,7 @@ __docker_network_subcommand() { $opts_help \ "($help)--no-trunc[Do not truncate the output]" \ "($help)*"{-f=,--filter=}"[Provide filter values]:filter:__docker_network_complete_ls_filters" \ - "($help)--format=[Pretty-print networks using a Go template]:template: " \ + "($help)--format=[Format the output using the given Go template]:template: " \ "($help -q --quiet)"{-q,--quiet}"[Only display network IDs]" && ret=0 ;; (prune) @@ -2051,7 +2051,7 @@ __docker_service_subcommand() { _arguments $(__docker_arguments) \ $opts_help \ "($help)*"{-f=,--filter=}"[Filter output based on conditions provided]:filter:__docker_service_complete_ls_filters" \ - "($help)--format=[Pretty-print services using a Go template]:template: " \ + "($help)--format=[Format the output using the given Go template]:template: " \ "($help -q --quiet)"{-q,--quiet}"[Only display IDs]" && ret=0 ;; (rm|remove) @@ -2254,7 +2254,7 @@ __docker_stack_subcommand() { _arguments $(__docker_arguments) \ $opts_help \ "($help)*"{-f=,--filter=}"[Filter output based on conditions provided]:filter:__docker_stack_complete_services_filters" \ - "($help)--format=[Pretty-print services using a Go template]:template: " \ + "($help)--format=[Format the output using the given Go template]:template: " \ "($help -q --quiet)"{-q,--quiet}"[Only display IDs]" \ "($help -):stack:__docker_complete_stacks" && ret=0 ;; @@ -2521,7 +2521,7 @@ __docker_volume_subcommand() { _arguments $(__docker_arguments) \ $opts_help \ "($help)*"{-f=,--filter=}"[Provide filter values]:filter:__docker_volume_complete_ls_filters" \ - "($help)--format=[Pretty-print volumes using a Go template]:template: " \ + "($help)--format=[Format the output using the given Go template]:template: " \ "($help -q --quiet)"{-q,--quiet}"[Only display volume names]" && ret=0 ;; (prune) From 9c0234bbcbf8ba13e7da8d0933c2da55e16e2d27 Mon Sep 17 00:00:00 2001 From: Djordje Lukic Date: Tue, 8 Mar 2022 14:54:21 +0100 Subject: [PATCH 8/8] Output compact JSON by default for --format=json With this change all `inspect` commands will output a compact JSON representation of the elements, the default format (indented JSON) stays the same. Signed-off-by: Djordje Lukic Signed-off-by: Sebastiaan van Stijn --- cli/command/config/inspect.go | 2 +- cli/command/container/inspect.go | 2 +- cli/command/context/inspect.go | 2 +- cli/command/image/inspect.go | 2 +- cli/command/inspect/inspector.go | 76 ++++++++++++------- cli/command/inspect/inspector_test.go | 6 +- cli/command/network/inspect.go | 2 +- cli/command/node/inspect.go | 2 +- cli/command/plugin/inspect.go | 2 +- cli/command/secret/inspect.go | 2 +- cli/command/service/inspect.go | 2 +- cli/command/system/inspect.go | 2 +- cli/command/volume/inspect.go | 2 +- docs/reference/commandline/config_inspect.md | 2 +- docs/reference/commandline/context_inspect.md | 2 +- docs/reference/commandline/info.md | 2 +- docs/reference/commandline/network_inspect.md | 2 +- docs/reference/commandline/node_inspect.md | 2 +- docs/reference/commandline/plugin_inspect.md | 2 +- docs/reference/commandline/secret_inspect.md | 2 +- docs/reference/commandline/service_inspect.md | 2 +- docs/reference/commandline/volume_inspect.md | 2 +- 22 files changed, 70 insertions(+), 52 deletions(-) diff --git a/cli/command/config/inspect.go b/cli/command/config/inspect.go index ddce83fd7a..a5b57c776f 100644 --- a/cli/command/config/inspect.go +++ b/cli/command/config/inspect.go @@ -31,7 +31,7 @@ func newConfigInspectCommand(dockerCli command.Cli) *cobra.Command { }, } - cmd.Flags().StringVarP(&opts.Format, "format", "f", "json", flagsHelper.InspectFormatHelp) + cmd.Flags().StringVarP(&opts.Format, "format", "f", "", flagsHelper.InspectFormatHelp) cmd.Flags().BoolVar(&opts.Pretty, "pretty", false, "Print the information in a human friendly format") return cmd } diff --git a/cli/command/container/inspect.go b/cli/command/container/inspect.go index 168740fae0..b5d4060789 100644 --- a/cli/command/container/inspect.go +++ b/cli/command/container/inspect.go @@ -31,7 +31,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) + flags.StringVarP(&opts.format, "format", "f", "", flagsHelper.InspectFormatHelp) flags.BoolVarP(&opts.size, "size", "s", false, "Display total file sizes") return cmd diff --git a/cli/command/context/inspect.go b/cli/command/context/inspect.go index 246436c1ca..65233bae15 100644 --- a/cli/command/context/inspect.go +++ b/cli/command/context/inspect.go @@ -35,7 +35,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) + flags.StringVarP(&opts.format, "format", "f", "", flagsHelper.InspectFormatHelp) return cmd } diff --git a/cli/command/image/inspect.go b/cli/command/image/inspect.go index e08b5fc3d9..2e3d5bf086 100644 --- a/cli/command/image/inspect.go +++ b/cli/command/image/inspect.go @@ -30,7 +30,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) + flags.StringVarP(&opts.format, "format", "f", "", flagsHelper.InspectFormatHelp) return cmd } diff --git a/cli/command/inspect/inspector.go b/cli/command/inspect/inspector.go index 15dbea14ce..307972e2b0 100644 --- a/cli/command/inspect/inspector.go +++ b/cli/command/inspect/inspector.go @@ -15,7 +15,9 @@ import ( // Inspector defines an interface to implement to process elements type Inspector interface { + // Inspect writes the raw element in JSON format. Inspect(typedElement interface{}, rawElement []byte) error + // Flush writes the result of inspecting all elements into the output stream. Flush() error } @@ -38,10 +40,14 @@ func NewTemplateInspector(outputStream io.Writer, tmpl *template.Template) Inspe // NewTemplateInspectorFromString creates a new TemplateInspector from a string // which is compiled into a template. func NewTemplateInspectorFromString(out io.Writer, tmplStr string) (Inspector, error) { - if tmplStr == "" || tmplStr == "json" { + if tmplStr == "" { return NewIndentedInspector(out), nil } + if tmplStr == "json" { + return NewJSONInspector(out), nil + } + tmpl, err := templates.Parse(tmplStr) if err != nil { return nil, errors.Errorf("Template parsing error: %s", err) @@ -136,64 +142,80 @@ func (i *TemplateInspector) Flush() error { return err } -// IndentedInspector uses a buffer to stop the indented representation of an element. -type IndentedInspector struct { - outputStream io.Writer - elements []interface{} - rawElements [][]byte -} - -// NewIndentedInspector generates a new IndentedInspector. +// NewIndentedInspector generates a new inspector with an indented representation +// of elements. func NewIndentedInspector(outputStream io.Writer) Inspector { - return &IndentedInspector{ + return &elementsInspector{ outputStream: outputStream, + raw: func(dst *bytes.Buffer, src []byte) error { + return json.Indent(dst, src, "", " ") + }, + el: func(v interface{}) ([]byte, error) { + return json.MarshalIndent(v, "", " ") + }, } } -// Inspect writes the raw element with an indented json format. -func (i *IndentedInspector) Inspect(typedElement interface{}, rawElement []byte) error { +// NewJSONInspector generates a new inspector with a compact representation +// of elements. +func NewJSONInspector(outputStream io.Writer) Inspector { + return &elementsInspector{ + outputStream: outputStream, + raw: json.Compact, + el: json.Marshal, + } +} + +type elementsInspector struct { + outputStream io.Writer + elements []interface{} + rawElements [][]byte + raw func(dst *bytes.Buffer, src []byte) error + el func(v interface{}) ([]byte, error) +} + +func (e *elementsInspector) Inspect(typedElement interface{}, rawElement []byte) error { if rawElement != nil { - i.rawElements = append(i.rawElements, rawElement) + e.rawElements = append(e.rawElements, rawElement) } else { - i.elements = append(i.elements, typedElement) + e.elements = append(e.elements, typedElement) } return nil } -// Flush writes the result of inspecting all elements into the output stream. -func (i *IndentedInspector) Flush() error { - if len(i.elements) == 0 && len(i.rawElements) == 0 { - _, err := io.WriteString(i.outputStream, "[]\n") +func (e *elementsInspector) Flush() error { + if len(e.elements) == 0 && len(e.rawElements) == 0 { + _, err := io.WriteString(e.outputStream, "[]\n") return err } var buffer io.Reader - if len(i.rawElements) > 0 { + if len(e.rawElements) > 0 { bytesBuffer := new(bytes.Buffer) bytesBuffer.WriteString("[") - for idx, r := range i.rawElements { + for idx, r := range e.rawElements { bytesBuffer.Write(r) - if idx < len(i.rawElements)-1 { + if idx < len(e.rawElements)-1 { bytesBuffer.WriteString(",") } } bytesBuffer.WriteString("]") - indented := new(bytes.Buffer) - if err := json.Indent(indented, bytesBuffer.Bytes(), "", " "); err != nil { + output := new(bytes.Buffer) + if err := e.raw(output, bytesBuffer.Bytes()); err != nil { return err } - buffer = indented + buffer = output } else { - b, err := json.MarshalIndent(i.elements, "", " ") + b, err := e.el(e.elements) if err != nil { return err } buffer = bytes.NewReader(b) } - if _, err := io.Copy(i.outputStream, buffer); err != nil { + if _, err := io.Copy(e.outputStream, buffer); err != nil { return err } - _, err := io.WriteString(i.outputStream, "\n") + _, err := io.WriteString(e.outputStream, "\n") return err } diff --git a/cli/command/inspect/inspector_test.go b/cli/command/inspect/inspector_test.go index 74c49b2f82..637f3b92d1 100644 --- a/cli/command/inspect/inspector_test.go +++ b/cli/command/inspect/inspector_test.go @@ -277,11 +277,7 @@ func TestNewTemplateInspectorFromString(t *testing.T) { { name: "json specific value outputs json", template: "json", - expected: `[ - { - "Name": "test" - } -] + expected: `[{"Name":"test"}] `, }, { diff --git a/cli/command/network/inspect.go b/cli/command/network/inspect.go index 890ac77506..89c1d6c0ca 100644 --- a/cli/command/network/inspect.go +++ b/cli/command/network/inspect.go @@ -30,7 +30,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { }, } - cmd.Flags().StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) + cmd.Flags().StringVarP(&opts.format, "format", "f", "", flagsHelper.InspectFormatHelp) cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", false, "Verbose output for diagnostics") return cmd diff --git a/cli/command/node/inspect.go b/cli/command/node/inspect.go index 51f7c50e1d..977026f641 100644 --- a/cli/command/node/inspect.go +++ b/cli/command/node/inspect.go @@ -32,7 +32,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) + flags.StringVarP(&opts.format, "format", "f", "", flagsHelper.InspectFormatHelp) flags.BoolVar(&opts.pretty, "pretty", false, "Print the information in a human friendly format") return cmd } diff --git a/cli/command/plugin/inspect.go b/cli/command/plugin/inspect.go index baf166fccf..c84711af2b 100644 --- a/cli/command/plugin/inspect.go +++ b/cli/command/plugin/inspect.go @@ -29,7 +29,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) + flags.StringVarP(&opts.format, "format", "f", "", flagsHelper.InspectFormatHelp) return cmd } diff --git a/cli/command/secret/inspect.go b/cli/command/secret/inspect.go index 05962b9a8b..0a8df1bcea 100644 --- a/cli/command/secret/inspect.go +++ b/cli/command/secret/inspect.go @@ -30,7 +30,7 @@ func newSecretInspectCommand(dockerCli command.Cli) *cobra.Command { }, } - cmd.Flags().StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) + cmd.Flags().StringVarP(&opts.format, "format", "f", "", flagsHelper.InspectFormatHelp) cmd.Flags().BoolVar(&opts.pretty, "pretty", false, "Print the information in a human friendly format") return cmd } diff --git a/cli/command/service/inspect.go b/cli/command/service/inspect.go index a06149ec01..59e4c03cd2 100644 --- a/cli/command/service/inspect.go +++ b/cli/command/service/inspect.go @@ -38,7 +38,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) + flags.StringVarP(&opts.format, "format", "f", "", flagsHelper.InspectFormatHelp) flags.BoolVar(&opts.pretty, "pretty", false, "Print the information in a human friendly format") return cmd } diff --git a/cli/command/system/inspect.go b/cli/command/system/inspect.go index 56199aecde..e15d86a66d 100644 --- a/cli/command/system/inspect.go +++ b/cli/command/system/inspect.go @@ -37,7 +37,7 @@ func NewInspectCommand(dockerCli command.Cli) *cobra.Command { } flags := cmd.Flags() - flags.StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) + flags.StringVarP(&opts.format, "format", "f", "", flagsHelper.InspectFormatHelp) flags.StringVar(&opts.inspectType, "type", "", "Return JSON for specified type") flags.BoolVarP(&opts.size, "size", "s", false, "Display total file sizes if the type is container") diff --git a/cli/command/volume/inspect.go b/cli/command/volume/inspect.go index 3d3887635e..c2fbc39c8c 100644 --- a/cli/command/volume/inspect.go +++ b/cli/command/volume/inspect.go @@ -28,7 +28,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command { }, } - cmd.Flags().StringVarP(&opts.format, "format", "f", "json", flagsHelper.InspectFormatHelp) + cmd.Flags().StringVarP(&opts.format, "format", "f", "", flagsHelper.InspectFormatHelp) return cmd } diff --git a/docs/reference/commandline/config_inspect.md b/docs/reference/commandline/config_inspect.md index 1d8022bbbf..bb8c025cb0 100644 --- a/docs/reference/commandline/config_inspect.md +++ b/docs/reference/commandline/config_inspect.md @@ -15,7 +15,7 @@ Options: -f, --format string Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. - Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --pretty Print the information in a human friendly format --help Print usage ``` diff --git a/docs/reference/commandline/context_inspect.md b/docs/reference/commandline/context_inspect.md index 6d038b428f..7125ec3ac8 100644 --- a/docs/reference/commandline/context_inspect.md +++ b/docs/reference/commandline/context_inspect.md @@ -15,7 +15,7 @@ Options: -f, --format string Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. - Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates ``` ## Description diff --git a/docs/reference/commandline/info.md b/docs/reference/commandline/info.md index 316e301ab6..0071edd862 100644 --- a/docs/reference/commandline/info.md +++ b/docs/reference/commandline/info.md @@ -12,7 +12,7 @@ Usage: docker info [OPTIONS] Display system-wide information Options: - -f, --format string Format the output using the given Go template (default "json") + -f, --format string Format the output using the given Go template --help Print usage ``` diff --git a/docs/reference/commandline/network_inspect.md b/docs/reference/commandline/network_inspect.md index 2c0150253a..45dc88d3b4 100644 --- a/docs/reference/commandline/network_inspect.md +++ b/docs/reference/commandline/network_inspect.md @@ -15,7 +15,7 @@ Options: -f, --format string Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. - Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates -v, --verbose Verbose output for diagnostics --help Print usage ``` diff --git a/docs/reference/commandline/node_inspect.md b/docs/reference/commandline/node_inspect.md index 0ac4289909..7a492f5f05 100644 --- a/docs/reference/commandline/node_inspect.md +++ b/docs/reference/commandline/node_inspect.md @@ -15,7 +15,7 @@ Options: -f, --format string Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. - Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --pretty Print the information in a human friendly format --help Print usage ``` diff --git a/docs/reference/commandline/plugin_inspect.md b/docs/reference/commandline/plugin_inspect.md index 2369dc1d1d..d84f7d68fb 100644 --- a/docs/reference/commandline/plugin_inspect.md +++ b/docs/reference/commandline/plugin_inspect.md @@ -15,7 +15,7 @@ Options: -f, --format string Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. - Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --help Print usage ``` diff --git a/docs/reference/commandline/secret_inspect.md b/docs/reference/commandline/secret_inspect.md index ba5cc91211..67ce7a2763 100644 --- a/docs/reference/commandline/secret_inspect.md +++ b/docs/reference/commandline/secret_inspect.md @@ -15,7 +15,7 @@ Options: -f, --format string Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. - Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --pretty Print the information in a human friendly format --help Print usage ``` diff --git a/docs/reference/commandline/service_inspect.md b/docs/reference/commandline/service_inspect.md index f284b7e94b..791244d939 100644 --- a/docs/reference/commandline/service_inspect.md +++ b/docs/reference/commandline/service_inspect.md @@ -15,7 +15,7 @@ Options: -f, --format string Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. - Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --pretty Print the information in a human friendly format --help Print usage ``` diff --git a/docs/reference/commandline/volume_inspect.md b/docs/reference/commandline/volume_inspect.md index 9c2e3b75b1..86eab1e46c 100644 --- a/docs/reference/commandline/volume_inspect.md +++ b/docs/reference/commandline/volume_inspect.md @@ -15,7 +15,7 @@ Options: -f, --format string Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. - Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates (default "json") + Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates --help Print usage ```