Merge f617883fdf into 8a7c5ae68f

cmd/docker: add tests for flag-completions, and refactor

cmd/docker/completions.go

@@ -1,7 +1,6 @@
 package main
 
 import (
-	"github.com/docker/cli/cli/command/completion"
 	"github.com/docker/cli/cli/context/store"
 	"github.com/spf13/cobra"
 )
@@ -10,18 +9,15 @@ type contextStoreProvider interface {
 	ContextStore() store.Store
 }
 
-func registerCompletionFuncForGlobalFlags(dockerCLI contextStoreProvider, cmd *cobra.Command) error {
-	err := cmd.RegisterFlagCompletionFunc("context", func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
+func completeContextNames(dockerCLI contextStoreProvider) func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
+	return func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
 		names, _ := store.Names(dockerCLI.ContextStore())
 		return names, cobra.ShellCompDirectiveNoFileComp
-	})
-	if err != nil {
-		return err
 	}
-	err = cmd.RegisterFlagCompletionFunc("log-level", completion.FromList("debug", "info", "warn", "error", "fatal"))
-	if err != nil {
-		return err
-	}
-
-	return nil
+}
+
+var logLevels = []string{"debug", "info", "warn", "error", "fatal", "panic"}
+
+func completeLogLevels(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
+	return cobra.FixedCompletions(logLevels, cobra.ShellCompDirectiveNoFileComp)(nil, nil, "")
 }

cmd/docker/completions_test.go

@@ -0,0 +1,49 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/docker/cli/cli/context/store"
+	"github.com/spf13/cobra"
+	"gotest.tools/v3/assert"
+	is "gotest.tools/v3/assert/cmp"
+)
+
+type fakeCLI struct {
+	contextStore store.Store
+}
+
+func (c *fakeCLI) ContextStore() store.Store {
+	return c.contextStore
+}
+
+type fakeContextStore struct {
+	store.Store
+	names []string
+}
+
+func (f fakeContextStore) List() (c []store.Metadata, _ error) {
+	for _, name := range f.names {
+		c = append(c, store.Metadata{Name: name})
+	}
+	return c, nil
+}
+
+func TestCompleteContextNames(t *testing.T) {
+	expectedNames := []string{"context-b", "context-c", "context-a"}
+	cli := &fakeCLI{
+		contextStore: fakeContextStore{
+			names: expectedNames,
+		},
+	}
+
+	values, directives := completeContextNames(cli)(nil, nil, "")
+	assert.Check(t, is.Equal(directives, cobra.ShellCompDirectiveNoFileComp))
+	assert.Check(t, is.DeepEqual(values, expectedNames))
+}
+
+func TestCompleteLogLevels(t *testing.T) {
+	values, directives := completeLogLevels(nil, nil, "")
+	assert.Check(t, is.Equal(directives, cobra.ShellCompDirectiveNoFileComp))
+	assert.Check(t, is.DeepEqual(values, logLevels))
+}

cmd/docker/docker.go

@@ -100,7 +100,11 @@ func newDockerCommand(dockerCli *command.DockerCli) *cli.TopLevelCommand {
 	cmd.SetErr(dockerCli.Err())
 
 	opts, helpCmd = cli.SetupRootCommand(cmd)
-	_ = registerCompletionFuncForGlobalFlags(dockerCli, cmd)
+
+	// TODO(thaJeztah): move configuring completion for these flags to where the flags are added.
+	_ = cmd.RegisterFlagCompletionFunc("context", completeContextNames(dockerCli))
+	_ = cmd.RegisterFlagCompletionFunc("log-level", completeLogLevels)
+
 	cmd.Flags().BoolP("version", "v", false, "Print version information and quit")
 	setFlagErrorFunc(dockerCli, cmd)
 

contrib/completion/zsh/_docker

@@ -1558,31 +1558,21 @@ __docker_plugin_complete_ls_filters() {
 __docker_plugins() {
     [[ $PREFIX = -* ]] && return 1
     integer ret=1
-    local line s
+    local filter line s
     declare -a lines plugins args
 
     filter=$1; shift
     [[ $filter != "none" ]] && args=("-f $filter")
 
-    lines=(${(f)${:-"$(_call_program commands docker $docker_options plugin ls $args)"$'\n'}})
+    # Output plugins in format "name:tag\|description"
+    lines=(${(f)${:-"$(_call_program commands docker $docker_options plugin ls --format='{{.Name}}\|{{.Description}}' $args)"}})
 
-    # Parse header line to find columns
-    local i=1 j=1 k header=${lines[1]}
-    declare -A begin end
-    while (( j < ${#header} - 1 )); do
-        i=$(( j + ${${header[$j,-1]}[(i)[^ ]]} - 1 ))
-        j=$(( i + ${${header[$i,-1]}[(i)  ]} - 1 ))
-        k=$(( j + ${${header[$j,-1]}[(i)[^ ]]} - 2 ))
-        begin[${header[$i,$((j-1))]}]=$i
-        end[${header[$i,$((j-1))]}]=$k
-    done
-    end[${header[$i,$((j-1))]}]=-1
-    lines=(${lines[2,-1]})
-
-    # Name
+    # Suggestion entries: name:tag -- description
     for line in $lines; do
-        s="${line[${begin[NAME]},${end[NAME]}]%% ##}"
-        s="$s:${(l:7:: :::)${${line[${begin[TAG]},${end[TAG]}]}%% ##}}"
+        # - Remove redundant :latest tag
+        # - Quote : in name:tag (_describe splits on : to separate entry and description)
+        # - Replace \| separator with :
+        s="${${${line//:latest/}//:/\:}//\|/:}"
         plugins=($plugins $s)
     done
 

docs/reference/commandline/image_tag.md

@@ -12,38 +12,50 @@ Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE
 
 ## Description
 
-A full image name has the following format and components:
+A Docker image reference consists of several components that describe where the
+image is stored and its identity. These components are:
 
-`[HOST[:PORT_NUMBER]/]PATH`
+```text
+[HOST[:PORT]/]NAMESPACE/REPOSITORY[:TAG]
+```
 
-- `HOST`: The optional registry hostname specifies where the image is located.
-  The hostname must comply with standard DNS rules, but may not contain
-  underscores. If you don't specify a hostname, the command uses Docker's public
-  registry at `registry-1.docker.io` by default. Note that `docker.io` is the
-  canonical reference for Docker's public registry.
-- `PORT_NUMBER`: If a hostname is present, it may optionally be followed by a
-  registry port number in the format `:8080`.
-- `PATH`: The path consists of slash-separated components. Each
-  component may contain lowercase letters, digits and separators. A separator is
-  defined as a period, one or two underscores, or one or more hyphens. A component
-  may not start or end with a separator. While the
-  [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec)
-  supports more than two slash-separated components, most registries only support
-  two slash-separated components. For Docker's public registry, the path format is
-  as follows:
-  - `[NAMESPACE/]REPOSITORY`: The first, optional component is typically a
-  user's or an organization's namespace. The second, mandatory component is the
-  repository name. When the namespace is not present, Docker uses `library`
-  as the default namespace.
+`HOST`
+: Specifies the registry location where the image resides. If omitted, Docker
+  defaults to Docker Hub (`docker.io`).
 
-After the image name, the optional `TAG` is a custom, human-readable manifest
-identifier that's typically a specific version or variant of an image. The tag
-must be valid ASCII and can contain lowercase and uppercase letters, digits,
-underscores, periods, and hyphens. It can't start with a period or hyphen and
-must be no longer than 128 characters. If you don't specify a tag, the command uses `latest` by default.
+`PORT`
+: An optional port number for the registry, if necessary (for example, `:5000`).
 
-You can group your images together using names and tags, and then
-[push](image_push.md) them to a registry.
+`NAMESPACE/REPOSITORY`
+: The namespace (optional) usually represents a user or organization. The
+  repository is required and identifies the specific image. If the namespace is
+  omitted, Docker defaults to `library`, the namespace reserved for Docker
+  Official Images.
+
+`TAG`
+: An optional identifier used to specify a particular version or variant of the
+  image. If no tag is provided, Docker defaults to `latest`.
+
+### Example image references
+
+`example.com:5000/team/my-app:2.0`
+
+- Host: `example.com`
+- Port: `5000`
+- Namespace: `team`
+- Repository: `my-app`
+- Tag: `2.0`
+
+`alpine`
+
+- Host: `docker.io` (default)
+- Namespace: `library` (default)
+- Repository: `alpine`
+- Tag: `latest` (default)
+
+For more information on the structure and rules of image naming, refer to the
+[Distribution reference](https://pkg.go.dev/github.com/distribution/reference#pkg-overview)
+as the canonical definition of the format.
 
 ## Examples
 

docs/reference/commandline/system_events.md

@@ -26,7 +26,7 @@ per Docker object type. Different event types have different scopes. Local
 scoped events are only seen on the node they take place on, and Swarm scoped
 events are seen on all managers.
 
-Only the last 1000 log events are returned. You can use filters to further limit
+Only the last 256 log events are returned. You can use filters to further limit
 the number of events returned.
 
 ### Object types
@@ -156,7 +156,7 @@ that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap
 seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a
 fraction of a second no more than nine digits long.
 
-Only the last 1000 log events are returned. You can use filters to further limit
+Only the last 256 log events are returned. You can use filters to further limit
 the number of events returned.
 
 #### <a name="filter"></a> Filtering (--filter)

templates/templates_test.go

@@ -89,3 +89,55 @@ func TestParseTruncateFunction(t *testing.T) {
 		})
 	}
 }
+
+func TestHeaderFunctions(t *testing.T) {
+	const source = "hello world"
+
+	tests := []struct {
+		doc      string
+		template string
+	}{
+		{
+			doc:      "json",
+			template: `{{ json .}}`,
+		},
+		{
+			doc:      "split",
+			template: `{{ split . ","}}`,
+		},
+		{
+			doc:      "join",
+			template: `{{ join . ","}}`,
+		},
+		{
+			doc:      "title",
+			template: `{{ title .}}`,
+		},
+		{
+			doc:      "lower",
+			template: `{{ lower .}}`,
+		},
+		{
+			doc:      "upper",
+			template: `{{ upper .}}`,
+		},
+		{
+			doc:      "truncate",
+			template: `{{ truncate . 2}}`,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.doc, func(t *testing.T) {
+			tmpl, err := New("").Funcs(HeaderFunctions).Parse(tc.template)
+			assert.NilError(t, err)
+
+			var b bytes.Buffer
+			assert.NilError(t, tmpl.Execute(&b, source))
+
+			// All header-functions are currently stubs, and don't modify the input.
+			expected := source
+			assert.Equal(t, expected, b.String())
+		})
+	}
+}

vendor.mod

@@ -25,7 +25,7 @@ require (
 	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510
 	github.com/mattn/go-runewidth v0.0.15
 	github.com/moby/patternmatcher v0.6.0
-	github.com/moby/swarmkit/v2 v2.0.0-20240611172349-ea1a7cec35cb
+	github.com/moby/swarmkit/v2 v2.0.0-20241017191044-e8ecf83ee08e
 	github.com/moby/sys/capability v0.3.0
 	github.com/moby/sys/sequential v0.6.0
 	github.com/moby/sys/signal v0.7.1

vendor.sum

@@ -180,8 +180,8 @@ github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3N
 github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
 github.com/moby/patternmatcher v0.6.0 h1:GmP9lR19aU5GqSSFko+5pRqHi+Ohk1O69aFiKkVGiPk=
 github.com/moby/patternmatcher v0.6.0/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc=
-github.com/moby/swarmkit/v2 v2.0.0-20240611172349-ea1a7cec35cb h1:1UTTg2EgO3nuyV03wREDzldqqePzQ4+0a5G1C1y1bIo=
-github.com/moby/swarmkit/v2 v2.0.0-20240611172349-ea1a7cec35cb/go.mod h1:kNy225f/gWAnF8wPftteMc5nbAHhrH+HUfvyjmhFjeQ=
+github.com/moby/swarmkit/v2 v2.0.0-20241017191044-e8ecf83ee08e h1:1yC8fRqStY6NirU/swI74fsrHvZVMbtxsHcvl8YpzDg=
+github.com/moby/swarmkit/v2 v2.0.0-20241017191044-e8ecf83ee08e/go.mod h1:mTTGIAz/59OGZR5Qe+QByIe3Nxc+sSuJkrsStFhr6Lg=
 github.com/moby/sys/capability v0.3.0 h1:kEP+y6te0gEXIaeQhIi0s7vKs/w0RPoH1qPa6jROcVg=
 github.com/moby/sys/capability v0.3.0/go.mod h1:4g9IK291rVkms3LKCDOoYlnV8xKwoDTpIrNEE35Wq0I=
 github.com/moby/sys/sequential v0.6.0 h1:qrx7XFUd/5DxtqcoH1h438hF5TmOvzC/lspjy7zgvCU=

vendor/modules.txt

@@ -197,7 +197,7 @@ github.com/moby/docker-image-spec/specs-go/v1
 ## explicit; go 1.19
 github.com/moby/patternmatcher
 github.com/moby/patternmatcher/ignorefile
-# github.com/moby/swarmkit/v2 v2.0.0-20240611172349-ea1a7cec35cb
+# github.com/moby/swarmkit/v2 v2.0.0-20241017191044-e8ecf83ee08e
 ## explicit; go 1.18
 github.com/moby/swarmkit/v2/api
 github.com/moby/swarmkit/v2/api/deepcopy