Merge pull request #4 from moby/20.10_update_vendor

[20.10] update BuildKit and Docker vendor

.circleci/config.yml

@@ -42,7 +42,7 @@ jobs:
     docker: [{image: 'docker:20.10-git'}]
     environment:
       DOCKER_BUILDKIT: 1
-      BUILDX_VERSION: "v0.5.1"
+      BUILDX_VERSION: "v0.8.2"
     parallelism: 3
     steps:
       - checkout

.golangci.yml

@@ -5,12 +5,10 @@ linters:
     - dogsled
     - gocyclo
     - goimports
-    - golint
     - gosec
     - gosimple
     - govet
     - ineffassign
-    - interfacer
     - lll
     - megacheck
     - misspell
@@ -21,6 +19,7 @@ linters:
     - unconvert
     - unparam
     - unused
+    - revive
     - varcheck
 
   disable:
@@ -54,30 +53,65 @@ issues:
     - parameter .* always receives
 
   exclude-rules:
-    # These are copied from the default exclude rules, except for "ineffective break statement"
-    # and GoDoc checks.
-    # https://github.com/golangci/golangci-lint/blob/0cc87df732aaf1d5ad9ce9ca538d38d916918b36/pkg/config/config.go#L36
-    - text: "Error return value of .((os\\.)?std(out|err)\\..*|.*Close|.*Flush|os\\.Remove(All)?|.*printf?|os\\.(Un)?Setenv). is not checked"
+    # We prefer to use an "exclude-list" so that new "default" exclusions are not
+    # automatically inherited. We can decide whether or not to follow upstream
+    # defaults when updating golang-ci-lint versions.
+    # Unfortunately, this means we have to copy the whole exclusion pattern, as
+    # (unlike the "include" option), the "exclude" option does not take exclusion
+    # ID's.
+    #
+    # These exclusion patterns are copied from the default excluses at:
+    # https://github.com/golangci/golangci-lint/blob/v1.44.0/pkg/config/issues.go#L10-L104
+
+    # EXC0001
+    - text: "Error return value of .((os\\.)?std(out|err)\\..*|.*Close|.*Flush|os\\.Remove(All)?|.*print(f|ln)?|os\\.(Un)?Setenv). is not checked"
       linters:
         - errcheck
+    # EXC0003
     - text: "func name will be used as test\\.Test.* by other packages, and that stutters; consider calling this"
       linters:
-        - golint
-    - text: "G103: Use of unsafe calls should be audited"
+        - revive
+    # EXC0006
+    - text: "Use of unsafe calls should be audited"
       linters:
         - gosec
-    - text: "G104: Errors unhandled"
+    # EXC0007
+    - text: "Subprocess launch(ed with variable|ing should be audited)"
       linters:
         - gosec
-    - text: "G204: Subprocess launch(ed with (variable|function call)|ing should be audited)"
+    # EXC0008
+    # TODO: evaluate these and fix where needed: G307: Deferring unsafe method "*os.File" on type "Close" (gosec)
+    - text: "(G104|G307)"
       linters:
         - gosec
-    - text: "(G301|G302): (Expect directory permissions to be 0750 or less|Expect file permissions to be 0600 or less)"
+    # EXC0009
+    - text: "(Expect directory permissions to be 0750 or less|Expect file permissions to be 0600 or less)"
       linters:
         - gosec
-    - text: "G304: Potential file inclusion via variable"
+    # EXC0010
+    - text: "Potential file inclusion via variable"
       linters:
         - gosec
-    - text: "(G201|G202): SQL string (formatting|concatenation)"
+
+    # Looks like the match in "EXC0007" above doesn't catch this one
+    # TODO: consider upstreaming this to golangci-lint's default exclusion rules
+    - text: "G204: Subprocess launched with a potential tainted input or cmd arguments"
       linters:
         - gosec
+    # Looks like the match in "EXC0009" above doesn't catch this one
+    # TODO: consider upstreaming this to golangci-lint's default exclusion rules
+    - text: "G306: Expect WriteFile permissions to be 0600 or less"
+      linters:
+        - gosec
+
+    # Exclude some linters from running on tests files.
+    - path: _test\.go
+      linters:
+        - errcheck
+        - gosec
+
+  # Maximum issues count per one linter. Set to 0 to disable. Default is 50.
+  max-issues-per-linter: 0
+
+  # Maximum count of issues with the same text. Set to 0 to disable. Default is 3.
+  max-same-issues: 0

Dockerfile

@@ -1,23 +1,12 @@
-# syntax=docker/dockerfile:1.3
+# syntax=docker/dockerfile:1
 
 ARG BASE_VARIANT=alpine
-ARG GO_VERSION=1.16.9
-ARG XX_VERSION=1.0.0-rc.2
-
-FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-${BASE_VARIANT} AS gostable
-FROM --platform=$BUILDPLATFORM golang:1.17rc1-${BASE_VARIANT} AS golatest
-
-FROM gostable AS go-linux
-FROM gostable AS go-darwin
-FROM gostable AS go-windows-amd64
-FROM gostable AS go-windows-386
-FROM gostable AS go-windows-arm
-FROM golatest AS go-windows-arm64
-FROM go-windows-${TARGETARCH} AS go-windows
+ARG GO_VERSION=1.18.7
+ARG XX_VERSION=1.1.0
 
 FROM --platform=$BUILDPLATFORM tonistiigi/xx:${XX_VERSION} AS xx
 
-FROM go-${TARGETOS} AS build-base-alpine
+FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-${BASE_VARIANT} AS build-base-alpine
 COPY --from=xx / /
 RUN apk add --no-cache clang lld llvm file git
 WORKDIR /go/src/github.com/docker/cli
@@ -27,7 +16,7 @@ ARG TARGETPLATFORM
 # gcc is installed for libgcc only
 RUN xx-apk add --no-cache musl-dev gcc
 
-FROM go-${TARGETOS} AS build-base-buster
+FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-buster AS build-base-buster
 COPY --from=xx / /
 RUN apt-get update && apt-get install --no-install-recommends -y clang lld file
 WORKDIR /go/src/github.com/docker/cli
@@ -55,7 +44,7 @@ RUN --mount=ro --mount=type=cache,target=/root/.cache \
     TARGET=/out ./scripts/build/binary && \
     xx-verify $([ "$GO_LINKMODE" = "static" ] && echo "--static") /out/docker
 
-FROM build-base-${BASE_VARIANT} AS dev 
+FROM build-base-${BASE_VARIANT} AS dev
 COPY . .
 
 FROM scratch AS binary

appveyor.yml

@@ -4,7 +4,7 @@ clone_folder: c:\gopath\src\github.com\docker\cli
 
 environment:
   GOPATH: c:\gopath
-  GOVERSION: 1.16.9
+  GOVERSION: 1.18.7
   DEPVERSION: v0.4.1
 
 install:

cli-plugins/manager/manager_unix.go

@@ -1,3 +1,4 @@
+//go:build !windows
 // +build !windows
 
 package manager

cli-plugins/manager/suffix_unix.go

@@ -1,3 +1,4 @@
+//go:build !windows
 // +build !windows
 
 package manager

cli/command/config/formatter_test.go

@@ -19,13 +19,11 @@ func TestConfigContextFormatWrite(t *testing.T) {
 		// Errors
 		{
 			formatter.Context{Format: "{{InvalidFunction}}"},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			formatter.Context{Format: "{{nil}}"},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		// Table format
 		{formatter.Context{Format: NewFormat("table", false)},

cli/command/config/inspect_test.go

@@ -36,7 +36,7 @@ func TestConfigInspectErrors(t *testing.T) {
 			flags: map[string]string{
 				"format": "{{invalid format}}",
 			},
-			expectedError: "Template parsing error",
+			expectedError: "template parsing error",
 		},
 		{
 			args: []string{"foo", "bar"},

cli/command/container/create.go

@@ -155,7 +155,7 @@ func (cid *cidFile) Close() error {
 		return nil
 	}
 	if err := os.Remove(cid.path); err != nil {
-		return errors.Errorf("failed to remove the CID file '%s': %s \n", cid.path, err)
+		return errors.Wrapf(err, "failed to remove the CID file '%s'", cid.path)
 	}
 
 	return nil
@@ -166,7 +166,7 @@ func (cid *cidFile) Write(id string) error {
 		return nil
 	}
 	if _, err := cid.file.Write([]byte(id)); err != nil {
-		return errors.Errorf("Failed to write the container ID to the file: %s", err)
+		return errors.Wrap(err, "failed to write the container ID to the file")
 	}
 	cid.written = true
 	return nil
@@ -177,12 +177,12 @@ func newCIDFile(path string) (*cidFile, error) {
 		return &cidFile{}, nil
 	}
 	if _, err := os.Stat(path); err == nil {
-		return nil, errors.Errorf("Container ID file found, make sure the other container isn't running or delete %s", path)
+		return nil, errors.Errorf("container ID file found, make sure the other container isn't running or delete %s", path)
 	}
 
 	f, err := os.Create(path)
 	if err != nil {
-		return nil, errors.Errorf("Failed to create the container ID file: %s", err)
+		return nil, errors.Wrap(err, "failed to create the container ID file")
 	}
 
 	return &cidFile{path: path, file: f}, nil

cli/command/container/create_test.go

@@ -39,7 +39,7 @@ func TestNewCIDFileWhenFileAlreadyExists(t *testing.T) {
 	defer tempfile.Remove()
 
 	_, err := newCIDFile(tempfile.Path())
-	assert.ErrorContains(t, err, "Container ID file found")
+	assert.ErrorContains(t, err, "container ID file found")
 }
 
 func TestCIDFileCloseWithNoWrite(t *testing.T) {

cli/command/container/formatter_stats.go

@@ -181,14 +181,14 @@ func (c *statsContext) ID() string {
 
 func (c *statsContext) CPUPerc() string {
 	if c.s.IsInvalid {
-		return fmt.Sprintf("--")
+		return "--"
 	}
 	return fmt.Sprintf("%.2f%%", c.s.CPUPercentage)
 }
 
 func (c *statsContext) MemUsage() string {
 	if c.s.IsInvalid {
-		return fmt.Sprintf("-- / --")
+		return "-- / --"
 	}
 	if c.os == winOSType {
 		return units.BytesSize(c.s.Memory)
@@ -198,28 +198,28 @@ func (c *statsContext) MemUsage() string {
 
 func (c *statsContext) MemPerc() string {
 	if c.s.IsInvalid || c.os == winOSType {
-		return fmt.Sprintf("--")
+		return "--"
 	}
 	return fmt.Sprintf("%.2f%%", c.s.MemoryPercentage)
 }
 
 func (c *statsContext) NetIO() string {
 	if c.s.IsInvalid {
-		return fmt.Sprintf("--")
+		return "--"
 	}
 	return fmt.Sprintf("%s / %s", units.HumanSizeWithPrecision(c.s.NetworkRx, 3), units.HumanSizeWithPrecision(c.s.NetworkTx, 3))
 }
 
 func (c *statsContext) BlockIO() string {
 	if c.s.IsInvalid {
-		return fmt.Sprintf("--")
+		return "--"
 	}
 	return fmt.Sprintf("%s / %s", units.HumanSizeWithPrecision(c.s.BlockRead, 3), units.HumanSizeWithPrecision(c.s.BlockWrite, 3))
 }
 
 func (c *statsContext) PIDs() string {
 	if c.s.IsInvalid || c.os == winOSType {
-		return fmt.Sprintf("--")
+		return "--"
 	}
 	return fmt.Sprintf("%d", c.s.PidsCurrent)
 }

cli/command/container/formatter_stats_test.go

@@ -54,13 +54,11 @@ func TestContainerStatsContextWrite(t *testing.T) {
 	}{
 		{
 			formatter.Context{Format: "{{InvalidFunction}}"},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			formatter.Context{Format: "{{nil}}"},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		{
 			formatter.Context{Format: "table {{.MemUsage}}"},

cli/command/container/rm_test.go

@@ -14,13 +14,17 @@ import (
 )
 
 func TestRemoveForce(t *testing.T) {
-	var removed []string
+	var (
+		removed1 []string
+		removed2 []string
+	)
 
 	cli := test.NewFakeCli(&fakeClient{
 		containerRemoveFunc: func(ctx context.Context, container string, options types.ContainerRemoveOptions) error {
-			removed = append(removed, container)
+			removed1 = append(removed1, container)
+			removed2 = append(removed2, container)
 			if container == "nosuchcontainer" {
-				return errdefs.NotFound(fmt.Errorf("Error: No such container: " + container))
+				return errdefs.NotFound(fmt.Errorf("Error: no such container: " + container))
 			}
 			return nil
 		},
@@ -31,16 +35,16 @@ func TestRemoveForce(t *testing.T) {
 
 	t.Run("without force", func(t *testing.T) {
 		cmd.SetArgs([]string{"nosuchcontainer", "mycontainer"})
-		removed = []string{}
-		assert.ErrorContains(t, cmd.Execute(), "No such container")
-		sort.Strings(removed)
-		assert.DeepEqual(t, removed, []string{"mycontainer", "nosuchcontainer"})
+		removed1 = []string{}
+		assert.ErrorContains(t, cmd.Execute(), "no such container")
+		sort.Strings(removed1)
+		assert.DeepEqual(t, removed1, []string{"mycontainer", "nosuchcontainer"})
 	})
 	t.Run("with force", func(t *testing.T) {
 		cmd.SetArgs([]string{"--force", "nosuchcontainer", "mycontainer"})
-		removed = []string{}
+		removed2 = []string{}
 		assert.NilError(t, cmd.Execute())
-		sort.Strings(removed)
-		assert.DeepEqual(t, removed, []string{"mycontainer", "nosuchcontainer"})
+		sort.Strings(removed2)
+		assert.DeepEqual(t, removed2, []string{"mycontainer", "nosuchcontainer"})
 	})
 }

cli/command/container/signals_unix.go

@@ -1,3 +1,4 @@
+//go:build !windows
 // +build !windows
 
 package container

cli/command/container/signals_unix_test.go

@@ -1,3 +1,4 @@
+//go:build !windows
 // +build !windows
 
 package container

cli/command/formatter/container_test.go

@@ -130,13 +130,11 @@ func TestContainerContextWrite(t *testing.T) {
 		// Errors
 		{
 			Context{Format: "{{InvalidFunction}}"},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			Context{Format: "{{nil}}"},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		// Table Format
 		{

cli/command/formatter/disk_usage_test.go

@@ -61,8 +61,7 @@ CACHE ID   CACHE TYPE   SIZE      CREATED   LAST USED   USAGE     SHARED
 					Format: "{{InvalidFunction}}",
 				},
 			},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			DiskUsageContext{
@@ -70,8 +69,7 @@ CACHE ID   CACHE TYPE   SIZE      CREATED   LAST USED   USAGE     SHARED
 					Format: "{{nil}}",
 				},
 			},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		// Table Format
 		{

cli/command/formatter/formatter.go

@@ -64,7 +64,7 @@ func (c *Context) preFormat() {
 func (c *Context) parseFormat() (*template.Template, error) {
 	tmpl, err := templates.Parse(c.finalFormat)
 	if err != nil {
-		return tmpl, errors.Errorf("Template parsing error: %v\n", err)
+		return tmpl, errors.Wrap(err, "template parsing error")
 	}
 	return tmpl, err
 }
@@ -85,7 +85,7 @@ func (c *Context) postFormat(tmpl *template.Template, subContext SubContext) {
 
 func (c *Context) contextFormat(tmpl *template.Template, subContext SubContext) error {
 	if err := tmpl.Execute(c.buffer, subContext); err != nil {
-		return errors.Errorf("Template parsing error: %v\n", err)
+		return errors.Wrap(err, "template parsing error")
 	}
 	if c.Format.IsTable() && c.header != nil {
 		c.header = subContext.FullHeader()

cli/command/formatter/image_test.go

@@ -119,8 +119,7 @@ func TestImageContextWrite(t *testing.T) {
 					Format: "{{InvalidFunction}}",
 				},
 			},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			ImageContext{
@@ -128,8 +127,7 @@ func TestImageContextWrite(t *testing.T) {
 					Format: "{{nil}}",
 				},
 			},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		// Table Format
 		{

cli/command/formatter/volume_test.go

@@ -62,13 +62,11 @@ func TestVolumeContextWrite(t *testing.T) {
 		// Errors
 		{
 			Context{Format: "{{InvalidFunction}}"},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			Context{Format: "{{nil}}"},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		// Table format
 		{

cli/command/image/build.go

@@ -297,7 +297,7 @@ func runBuild(dockerCli command.Cli, options buildOptions) error {
 		}
 
 		if err := build.ValidateContextDirectory(contextDir, excludes); err != nil {
-			return errors.Errorf("error checking context: '%s'.", err)
+			return errors.Wrap(err, "error checking context")
 		}
 
 		// And canonicalize dockerfile name to a platform-independent one

cli/command/image/build/context_unix.go

@@ -1,3 +1,4 @@
+//go:build !windows
 // +build !windows
 
 package build

cli/command/image/build/context_windows.go

@@ -1,5 +1,3 @@
-// +build windows
-
 package build
 
 import (

cli/command/inspect/inspector.go

@@ -44,7 +44,7 @@ func NewTemplateInspectorFromString(out io.Writer, tmplStr string) (Inspector, e
 
 	tmpl, err := templates.Parse(tmplStr)
 	if err != nil {
-		return nil, errors.Errorf("Template parsing error: %s", err)
+		return nil, errors.Errorf("template parsing error: %s", err)
 	}
 	return NewTemplateInspector(out, tmpl), nil
 }
@@ -94,7 +94,7 @@ func (i *TemplateInspector) Inspect(typedElement interface{}, rawElement []byte)
 	buffer := new(bytes.Buffer)
 	if err := i.tmpl.Execute(buffer, typedElement); err != nil {
 		if rawElement == nil {
-			return errors.Errorf("Template parsing error: %v", err)
+			return errors.Errorf("template parsing error: %v", err)
 		}
 		return i.tryRawInspectFallback(rawElement)
 	}
@@ -118,7 +118,7 @@ func (i *TemplateInspector) tryRawInspectFallback(rawElement []byte) error {
 
 	tmplMissingKey := i.tmpl.Option("missingkey=error")
 	if rawErr := tmplMissingKey.Execute(buffer, raw); rawErr != nil {
-		return errors.Errorf("Template parsing error: %v", rawErr)
+		return errors.Errorf("template parsing error: %v", rawErr)
 	}
 
 	i.buffer.Write(buffer.Bytes())

cli/command/inspect/inspector_test.go

@@ -62,7 +62,7 @@ func TestTemplateInspectorTemplateError(t *testing.T) {
 		t.Fatal("Expected error got nil")
 	}
 
-	if !strings.HasPrefix(err.Error(), "Template parsing error") {
+	if !strings.HasPrefix(err.Error(), "template parsing error") {
 		t.Fatalf("Expected template error, got %v", err)
 	}
 }
@@ -98,7 +98,7 @@ func TestTemplateInspectorRawFallbackError(t *testing.T) {
 		t.Fatal("Expected error got nil")
 	}
 
-	if !strings.HasPrefix(err.Error(), "Template parsing error") {
+	if !strings.HasPrefix(err.Error(), "template parsing error") {
 		t.Fatalf("Expected template error, got %v", err)
 	}
 }

cli/command/network/formatter_test.go

@@ -79,13 +79,11 @@ func TestNetworkContextWrite(t *testing.T) {
 		// Errors
 		{
 			formatter.Context{Format: "{{InvalidFunction}}"},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			formatter.Context{Format: "{{nil}}"},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		// Table format
 		{

cli/command/node/formatter_test.go

@@ -62,15 +62,13 @@ func TestNodeContextWrite(t *testing.T) {
 
 		// Errors
 		{
-			context: formatter.Context{Format: "{{InvalidFunction}}"},
-			expected: `Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			context:     formatter.Context{Format: "{{InvalidFunction}}"},
+			expected:    `template parsing error: template: :1: function "InvalidFunction" not defined`,
 			clusterInfo: swarm.ClusterInfo{TLSInfo: swarm.TLSInfo{TrustRoot: "hi"}},
 		},
 		{
-			context: formatter.Context{Format: "{{nil}}"},
-			expected: `Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			context:     formatter.Context{Format: "{{nil}}"},
+			expected:    `template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 			clusterInfo: swarm.ClusterInfo{TLSInfo: swarm.TLSInfo{TrustRoot: "hi"}},
 		},
 		// Table format

cli/command/plugin/formatter_test.go

@@ -59,13 +59,11 @@ func TestPluginContextWrite(t *testing.T) {
 		// Errors
 		{
 			formatter.Context{Format: "{{InvalidFunction}}"},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			formatter.Context{Format: "{{nil}}"},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		// Table format
 		{

cli/command/plugin/inspect_test.go

@@ -61,7 +61,7 @@ func TestInspectErrors(t *testing.T) {
 			flags: map[string]string{
 				"format": "{{invalid format}}",
 			},
-			expectedError: "Template parsing error",
+			expectedError: "template parsing error",
 		},
 	}
 

cli/command/plugin/list_test.go

@@ -41,7 +41,7 @@ func TestListErrors(t *testing.T) {
 			flags: map[string]string{
 				"format": "{{invalid format}}",
 			},
-			expectedError: "Template parsing error",
+			expectedError: "template parsing error",
 		},
 	}
 

cli/command/registry/formatter_search_test.go

@@ -112,13 +112,11 @@ func TestSearchContextWrite(t *testing.T) {
 		// Errors
 		{
 			formatter.Context{Format: "{{InvalidFunction}}"},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			formatter.Context{Format: "{{nil}}"},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		// Table format
 		{

cli/command/secret/formatter_test.go

@@ -19,13 +19,11 @@ func TestSecretContextFormatWrite(t *testing.T) {
 		// Errors
 		{
 			formatter.Context{Format: "{{InvalidFunction}}"},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			formatter.Context{Format: "{{nil}}"},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		// Table format
 		{formatter.Context{Format: NewFormat("table", false)},

cli/command/secret/inspect_test.go

@@ -36,7 +36,7 @@ func TestSecretInspectErrors(t *testing.T) {
 			flags: map[string]string{
 				"format": "{{invalid format}}",
 			},
-			expectedError: "Template parsing error",
+			expectedError: "template parsing error",
 		},
 		{
 			args: []string{"foo", "bar"},

cli/command/service/formatter_test.go

@@ -29,13 +29,11 @@ func TestServiceContextWrite(t *testing.T) {
 		// Errors
 		{
 			formatter.Context{Format: "{{InvalidFunction}}"},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			formatter.Context{Format: "{{nil}}"},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		// Table format
 		{

cli/command/service/opts.go

@@ -914,7 +914,7 @@ func addServiceFlags(flags *pflag.FlagSet, opts *serviceOptions, defaultFlagValu
 }
 
 const (
-	flagCredentialSpec          = "credential-spec"
+	flagCredentialSpec          = "credential-spec" //nolint:gosec // ignore G101: Potential hardcoded credentials
 	flagPlacementPref           = "placement-pref"
 	flagPlacementPrefAdd        = "placement-pref-add"
 	flagPlacementPrefRemove     = "placement-pref-rm"

cli/command/stack/formatter/formatter_test.go

@@ -16,13 +16,11 @@ func TestStackContextWrite(t *testing.T) {
 		// Errors
 		{
 			formatter.Context{Format: "{{InvalidFunction}}"},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			formatter.Context{Format: "{{nil}}"},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		// Table format
 		{

cli/command/stack/list_test.go

@@ -33,7 +33,7 @@ func TestListErrors(t *testing.T) {
 			flags: map[string]string{
 				"format": "{{invalid format}}",
 			},
-			expectedError: "Template parsing error",
+			expectedError: "template parsing error",
 		},
 		{
 			serviceListFunc: func(options types.ServiceListOptions) ([]swarm.Service, error) {

cli/command/stack/loader/loader.go

@@ -28,6 +28,7 @@ func LoadComposefile(dockerCli command.Cli, opts options.Deploy) (*composetypes.
 	config, err := loader.Load(configDetails)
 	if err != nil {
 		if fpe, ok := err.(*loader.ForbiddenPropertiesError); ok {
+			//nolint:revive // ignore capitalization error; this error is intentionally formatted multi-line
 			return nil, errors.Errorf("Compose file contains unsupported options:\n\n%s\n",
 				propertyWarnings(fpe.Properties))
 		}

cli/command/stack/services_test.go

@@ -62,7 +62,7 @@ func TestStackServicesErrors(t *testing.T) {
 			serviceListFunc: func(options types.ServiceListOptions) ([]swarm.Service, error) {
 				return []swarm.Service{*Service()}, nil
 			},
-			expectedError: "Template parsing error",
+			expectedError: "template parsing error",
 		},
 	}
 

cli/command/system/info.go

@@ -506,7 +506,7 @@ func formatInfo(dockerCli command.Cli, info info, format string) error {
 	tmpl, err := templates.Parse(format)
 	if err != nil {
 		return cli.StatusError{StatusCode: 64,
-			Status: "Template parsing error: " + err.Error()}
+			Status: "template parsing error: " + err.Error()}
 	}
 	err = tmpl.Execute(dockerCli.Out(), info)
 	dockerCli.Out().Write([]byte{'\n'})

cli/command/system/info_test.go

@@ -394,7 +394,7 @@ func TestFormatInfo(t *testing.T) {
 		{
 			doc:           "syntax",
 			template:      "{{}",
-			expectedError: `Status: Template parsing error: template: :1: unexpected "}" in command, Code: 64`,
+			expectedError: `Status: template parsing error: template: :1: unexpected "}" in command, Code: 64`,
 		},
 		{
 			doc:           "syntax",

cli/command/system/version.go

@@ -235,7 +235,7 @@ func newVersionTemplate(templateFormat string) (*template.Template, error) {
 	tmpl := templates.New("version").Funcs(template.FuncMap{"getDetailsOrder": getDetailsOrder})
 	tmpl, err := tmpl.Parse(templateFormat)
 
-	return tmpl, errors.Wrap(err, "Template parsing error")
+	return tmpl, errors.Wrap(err, "template parsing error")
 }
 
 func getDetailsOrder(v types.ComponentVersion) []string {

cli/command/task/formatter_test.go

@@ -20,13 +20,11 @@ func TestTaskContextWrite(t *testing.T) {
 	}{
 		{
 			formatter.Context{Format: "{{InvalidFunction}}"},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			formatter.Context{Format: "{{nil}}"},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		{
 			formatter.Context{Format: NewTaskFormat("table", true)},

cli/command/trust/formatter_test.go

@@ -95,15 +95,13 @@ func TestTrustTagContextWrite(t *testing.T) {
 			formatter.Context{
 				Format: "{{InvalidFunction}}",
 			},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			formatter.Context{
 				Format: "{{nil}}",
 			},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		// Table Format
 		{
@@ -191,15 +189,13 @@ func TestSignerInfoContextWrite(t *testing.T) {
 			formatter.Context{
 				Format: "{{InvalidFunction}}",
 			},
-			`Template parsing error: template: :1: function "InvalidFunction" not defined
-`,
+			`template parsing error: template: :1: function "InvalidFunction" not defined`,
 		},
 		{
 			formatter.Context{
 				Format: "{{nil}}",
 			},
-			`Template parsing error: template: :1:2: executing "" at <nil>: nil is not a command
-`,
+			`template parsing error: template: :1:2: executing "" at <nil>: nil is not a command`,
 		},
 		// Table Format
 		{

cli/command/volume/create.go

@@ -32,7 +32,7 @@ func newCreateCommand(dockerCli command.Cli) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if len(args) == 1 {
 				if options.name != "" {
-					return errors.Errorf("Conflicting options: either specify --name or provide positional arg, not both\n")
+					return errors.Errorf("conflicting options: either specify --name or provide positional arg, not both")
 				}
 				options.name = args[0]
 			}

cli/command/volume/create_test.go

@@ -26,7 +26,7 @@ func TestVolumeCreateErrors(t *testing.T) {
 			flags: map[string]string{
 				"name": "volumeName",
 			},
-			expectedError: "Conflicting options: either specify --name or provide positional arg, not both",
+			expectedError: "conflicting options: either specify --name or provide positional arg, not both",
 		},
 		{
 			args:          []string{"too", "many"},

cli/command/volume/inspect_test.go

@@ -35,7 +35,7 @@ func TestVolumeInspectErrors(t *testing.T) {
 			flags: map[string]string{
 				"format": "{{invalid format}}",
 			},
-			expectedError: "Template parsing error",
+			expectedError: "template parsing error",
 		},
 		{
 			args: []string{"foo", "bar"},

cli/compose/interpolation/interpolation.go

@@ -99,7 +99,7 @@ func newPathError(path Path, err error) error {
 		return nil
 	case *template.InvalidTemplateError:
 		return errors.Errorf(
-			"invalid interpolation format for %s: %#v. You may need to escape any $ with another $.",
+			"invalid interpolation format for %s: %#v; you may need to escape any $ with another $",
 			path, err.Template)
 	default:
 		return errors.Wrapf(err, "error while interpolating %s", path)

cli/compose/interpolation/interpolation_test.go

@@ -58,7 +58,7 @@ func TestInvalidInterpolation(t *testing.T) {
 		},
 	}
 	_, err := Interpolate(services, Options{LookupValue: defaultMapping})
-	assert.Error(t, err, `invalid interpolation format for servicea.image: "${". You may need to escape any $ with another $.`)
+	assert.Error(t, err, `invalid interpolation format for servicea.image: "${"; you may need to escape any $ with another $`)
 }
 
 func TestInterpolateWithDefaults(t *testing.T) {

cli/config/config.go

@@ -104,14 +104,18 @@ func LoadFromReader(configData io.Reader) (*configfile.ConfigFile, error) {
 	return &configFile, err
 }
 
-// TODO remove this temporary hack, which is used to warn about the deprecated ~/.dockercfg file
-var printLegacyFileWarning bool
-
 // Load reads the configuration files in the given directory, and sets up
 // the auth config information and returns values.
 // FIXME: use the internal golang config parser
 func Load(configDir string) (*configfile.ConfigFile, error) {
-	printLegacyFileWarning = false
+	cfg, _, err := load(configDir)
+	return cfg, err
+}
+
+// TODO remove this temporary hack, which is used to warn about the deprecated ~/.dockercfg file
+// so we can remove the bool return value and collapse this back into `Load`
+func load(configDir string) (*configfile.ConfigFile, bool, error) {
+	printLegacyFileWarning := false
 
 	if configDir == "" {
 		configDir = Dir()
@@ -127,11 +131,11 @@ func Load(configDir string) (*configfile.ConfigFile, error) {
 		if err != nil {
 			err = errors.Wrap(err, filename)
 		}
-		return configFile, err
+		return configFile, printLegacyFileWarning, err
 	} else if !os.IsNotExist(err) {
 		// if file is there but we can't stat it for any reason other
 		// than it doesn't exist then stop
-		return configFile, errors.Wrap(err, filename)
+		return configFile, printLegacyFileWarning, errors.Wrap(err, filename)
 	}
 
 	// Can't find latest config file so check for the old one
@@ -140,16 +144,16 @@ func Load(configDir string) (*configfile.ConfigFile, error) {
 		printLegacyFileWarning = true
 		defer file.Close()
 		if err := configFile.LegacyLoadFromReader(file); err != nil {
-			return configFile, errors.Wrap(err, filename)
+			return configFile, printLegacyFileWarning, errors.Wrap(err, filename)
 		}
 	}
-	return configFile, nil
+	return configFile, printLegacyFileWarning, nil
 }
 
 // LoadDefaultConfigFile attempts to load the default config file and returns
 // an initialized ConfigFile struct if none is found.
 func LoadDefaultConfigFile(stderr io.Writer) *configfile.ConfigFile {
-	configFile, err := Load(Dir())
+	configFile, printLegacyFileWarning, err := load(Dir())
 	if err != nil {
 		fmt.Fprintf(stderr, "WARNING: Error loading config file: %v\n", err)
 	}

cli/config/configfile/file.go

@@ -119,7 +119,7 @@ func (configFile *ConfigFile) LegacyLoadFromReader(configData io.Reader) error {
 // LoadFromReader reads the configuration data given and sets up the auth config
 // information with given directory and populates the receiver object
 func (configFile *ConfigFile) LoadFromReader(configData io.Reader) error {
-	if err := json.NewDecoder(configData).Decode(&configFile); err != nil && !errors.Is(err, io.EOF) {
+	if err := json.NewDecoder(configData).Decode(configFile); err != nil && !errors.Is(err, io.EOF) {
 		return err
 	}
 	var err error

cli/config/configfile/file_unix.go

@@ -1,3 +1,4 @@
+//go:build !windows
 // +build !windows
 
 package configfile

cli/config/credentials/default_store_unsupported.go

@@ -1,3 +1,4 @@
+//go:build !windows && !darwin && !linux
 // +build !windows,!darwin,!linux
 
 package credentials

cli/config/credentials/native_store.go

@@ -7,7 +7,7 @@ import (
 )
 
 const (
-	remoteCredentialsPrefix = "docker-credential-"
+	remoteCredentialsPrefix = "docker-credential-" //nolint:gosec // ignore G101: Potential hardcoded credentials
 	tokenUsername           = "<token>"
 )
 

cli/connhelper/commandconn/commandconn_unix_test.go

@@ -1,3 +1,4 @@
+//go:build !windows
 // +build !windows
 
 package commandconn

cli/connhelper/commandconn/pdeathsig_nolinux.go

@@ -1,3 +1,4 @@
+//go:build !linux
 // +build !linux
 
 package commandconn

cli/connhelper/commandconn/session_unix.go

@@ -1,3 +1,4 @@
+//go:build !windows
 // +build !windows
 
 package commandconn

contrib/completion/bash/docker

@@ -5485,6 +5485,23 @@ _docker_wait() {
 	_docker_container_wait
 }
 
+COMPOSE_PLUGIN_PATH=$(docker info --format '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}}{{end}}{{end}}')
+
+_docker_compose() {
+	local completionCommand="__completeNoDesc"
+	local resultArray=($COMPOSE_PLUGIN_PATH $completionCommand compose)
+	for value in "${words[@]:2}"; do
+		if [ -z "$value" ]; then
+			resultArray+=( "''" )
+		else
+			resultArray+=( "$value" )
+		fi
+	done
+	local result=$(eval "${resultArray[*]}" 2> /dev/null | grep -v '^:[0-9]*$')
+
+	COMPREPLY=( $(compgen -W "${result}" -- "$current") )
+}
+
 _docker() {
 	local previous_extglob_setting=$(shopt -p extglob)
 	shopt -s extglob
@@ -5554,11 +5571,17 @@ _docker() {
 		wait
 	)
 
+	local known_plugin_commands=()
+
+	if [ -f "$COMPOSE_PLUGIN_PATH" ] ; then
+		known_plugin_commands+=("compose")
+	fi
+
 	local experimental_server_commands=(
 		checkpoint
 	)
 
-	local commands=(${management_commands[*]} ${top_level_commands[*]})
+	local commands=(${management_commands[*]} ${top_level_commands[*]} ${known_plugin_commands[*]})
 	[ -z "$DOCKER_HIDE_LEGACY_COMMANDS" ] && commands+=(${legacy_commands[*]})
 
 	# These options are valid as global options for all client commands

contrib/completion/zsh/_docker

@@ -2652,7 +2652,7 @@ __docker_commands() {
     then
         local -a lines
         lines=(${(f)"$(_call_program commands docker 2>&1)"})
-        _docker_subcommands=(${${${(M)${lines[$((${lines[(i)*Commands:]} + 1)),-1]}:# *}## #}/ ##/:})
+        _docker_subcommands=(${${${(M)${lines[$((${lines[(i)*Commands:]} + 1)),-1]}:# *}## #}/\*# ##/:})
         _docker_subcommands=($_docker_subcommands 'daemon:Enable daemon mode' 'help:Show help for a command')
         (( $#_docker_subcommands > 2 )) && _store_cache docker_subcommands _docker_subcommands
     fi
@@ -3094,6 +3094,7 @@ _docker() {
     _arguments $(__docker_arguments) -C \
         "(: -)"{-h,--help}"[Print usage]" \
         "($help)--config[Location of client config files]:path:_directories" \
+        "($help -c --context)"{-c=,--context=}"[Execute the command in a docker context]:context:__docker_complete_contexts" \
         "($help -D --debug)"{-D,--debug}"[Enable debug mode]" \
         "($help -H --host)"{-H=,--host=}"[tcp://host:port to bind/connect to]:host: " \
         "($help -l --log-level)"{-l=,--log-level=}"[Logging level]:level:(debug info warn error fatal)" \
@@ -3109,7 +3110,8 @@ _docker() {
 
     local host=${opt_args[-H]}${opt_args[--host]}
     local config=${opt_args[--config]}
-    local docker_options="${host:+--host $host} ${config:+--config $config}"
+    local context=${opt_args[-c]}${opt_args[--context]}
+    local docker_options="${host:+--host $host} ${config:+--config $config} ${context:+--context $context} "
 
     case $state in
         (command)

docker-bake.hcl

@@ -1,3 +1,6 @@
+variable "GO_VERSION" {
+    default = "1.18.7"
+}
 variable "VERSION" {
     default = ""
 }

dockerfiles/Dockerfile.binary-native

@@ -1,4 +1,4 @@
-ARG GO_VERSION=1.16.9
+ARG GO_VERSION=1.18.7
 
 FROM    golang:${GO_VERSION}-alpine
 

dockerfiles/Dockerfile.dev

@@ -1,6 +1,6 @@
-# syntax=docker/dockerfile:1.3
+# syntax=docker/dockerfile:1
 
-ARG GO_VERSION=1.16.9
+ARG GO_VERSION=1.18.7
 
 FROM golang:${GO_VERSION}-alpine AS golang
 ENV  CGO_ENABLED=0

dockerfiles/Dockerfile.e2e

@@ -1,4 +1,4 @@
-ARG GO_VERSION=1.16.9
+ARG GO_VERSION=1.18.7
 
 # Use Debian based image as docker-compose requires glibc.
 FROM golang:${GO_VERSION}-buster
@@ -10,7 +10,7 @@ RUN apt-get update && apt-get install -y \
     openssh-client \
     && rm -rf /var/lib/apt/lists/*
 
-ARG COMPOSE_VERSION=1.25.1
+ARG COMPOSE_VERSION=1.29.2
 RUN curl -fsSL https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose \
     && chmod +x /usr/local/bin/docker-compose
 
@@ -39,7 +39,6 @@ ARG GITCOMMIT
 ENV VERSION=${VERSION}
 ENV GITCOMMIT=${GITCOMMIT}
 ENV DOCKER_BUILDKIT=1
-ENV COMPOSE_DOCKER_CLI_BUILD=1
 RUN ./scripts/build/binary
 RUN ./scripts/build/plugins e2e/cli-plugins/plugins/*
 

dockerfiles/Dockerfile.lint

@@ -1,16 +1,16 @@
-# syntax=docker/dockerfile:1.3
+# syntax=docker/dockerfile:1
 
-ARG GO_VERSION=1.16.9
-ARG GOLANGCI_LINTER_SHA="v1.21.0"
+ARG GO_VERSION=1.18.7
+ARG GOLANGCI_LINT_VERSION=v1.45.2
 
 FROM    golang:${GO_VERSION}-alpine AS build
 ENV     CGO_ENABLED=0
 RUN     apk add --no-cache git
-ARG     GOLANGCI_LINTER_SHA
+ARG     GOLANGCI_LINT_VERSION
 ARG     GO111MODULE=on
 RUN --mount=type=cache,target=/root/.cache/go-build \
     --mount=type=cache,target=/go/pkg/mod \
-        go get github.com/golangci/golangci-lint/cmd/golangci-lint@${GOLANGCI_LINTER_SHA}
+        go install github.com/golangci/golangci-lint/cmd/golangci-lint@${GOLANGCI_LINT_VERSION}
 
 FROM    golang:${GO_VERSION}-alpine AS lint
 ENV     GO111MODULE=off

docs/deprecated.md

@@ -48,56 +48,58 @@ The table below provides an overview of the current status of deprecated feature
   alternatives. In such cases, a warning may be printed, and users should not rely
   on this feature.
 
-Status     | Feature                                                                                                                            | Deprecated | Remove
------------|------------------------------------------------------------------------------------------------------------------------------------|------------|------------
-Deprecated | [Support for encrypted TLS private keys](#support-for-encrypted-tls-private-keys)                                                  | v20.10     | -
-Deprecated | [Kubernetes stack and context support](#kubernetes-stack-and-context-support)                                                      | v20.10     | -
-Deprecated | [Pulling images from non-compliant image registries](#pulling-images-from-non-compliant-image-registries)                          | v20.10     | -
-Deprecated | [Linux containers on Windows (LCOW)](#linux-containers-on-windows-lcow-experimental)                                               | v20.10     | -
-Deprecated | [BLKIO weight options with cgroups v1](#blkio-weight-options-with-cgroups-v1)                                                      | v20.10     | -
-Deprecated | [Kernel memory limit](#kernel-memory-limit)                                                                                        | v20.10     | -
-Deprecated | [Classic Swarm and overlay networks using external key/value stores](#classic-swarm-and-overlay-networks-using-cluster-store)      | v20.10     | -
-Deprecated | [Support for the legacy `~/.dockercfg` configuration file for authentication](#support-for-legacy-dockercfg-configuration-files)   | v20.10     | -
-Deprecated | [CLI plugins support](#cli-plugins-support)                                                                                        | v20.10     | -
-Deprecated | [Dockerfile legacy `ENV name value` syntax](#dockerfile-legacy-env-name-value-syntax)                                              | v20.10     | -
-Removed    | [`docker build --stream` flag (experimental)](#docker-build---stream-flag-experimental)                                            | v20.10     | v20.10
-Deprecated | [Configuration options for experimental CLI features](#configuration-options-for-experimental-cli-features)                        | v19.03     | v20.10
-Deprecated | [Pushing and pulling with image manifest v2 schema 1](#pushing-and-pulling-with-image-manifest-v2-schema-1)                        | v19.03     | v20.10
-Removed    | [`docker engine` subcommands](#docker-engine-subcommands)                                                                          | v19.03     | v20.10
-Removed    | [Top-level `docker deploy` subcommand (experimental)](#top-level-docker-deploy-subcommand-experimental)                            | v19.03     | v20.10
-Removed    | [`docker stack deploy` using "dab" files (experimental)](#docker-stack-deploy-using-dab-files-experimental)                        | v19.03     | v20.10
-Deprecated | [AuFS storage driver](#aufs-storage-driver)                                                                                        | v19.03     | -
-Deprecated | [Legacy "overlay" storage driver](#legacy-overlay-storage-driver)                                                                  | v18.09     | -
-Deprecated | [Device mapper storage driver](#device-mapper-storage-driver)                                                                      | v18.09     | -
-Removed    | [Use of reserved namespaces in engine labels](#use-of-reserved-namespaces-in-engine-labels)                                        | v18.06     | v20.10
-Removed    | [`--disable-legacy-registry` override daemon option](#--disable-legacy-registry-override-daemon-option)                            | v17.12     | v19.03
-Removed    | [Interacting with V1 registries](#interacting-with-v1-registries)                                                                  | v17.06     | v17.12
-Removed    | [Asynchronous `service create` and `service update` as default](#asynchronous-service-create-and-service-update-as-default)        | v17.05     | v17.10
-Removed    | [`-g` and `--graph` flags on `dockerd`](#-g-and---graph-flags-on-dockerd)                                                          | v17.05     | -
-Deprecated | [Top-level network properties in NetworkSettings](#top-level-network-properties-in-networksettings)                                | v1.13      | v17.12
-Removed    | [`filter` param for `/images/json` endpoint](#filter-param-for-imagesjson-endpoint)                                                | v1.13      | v20.10
-Removed    | [`repository:shortid` image references](#repositoryshortid-image-references)                                                       | v1.13      | v17.12
-Removed    | [`docker daemon` subcommand](#docker-daemon-subcommand)                                                                            | v1.13      | v17.12
-Removed    | [Duplicate keys with conflicting values in engine labels](#duplicate-keys-with-conflicting-values-in-engine-labels)                | v1.13      | v17.12
-Deprecated | [`MAINTAINER` in Dockerfile](#maintainer-in-dockerfile)                                                                            | v1.13      | -
-Deprecated | [API calls without a version](#api-calls-without-a-version)                                                                        | v1.13      | v17.12
-Removed    | [Backing filesystem without `d_type` support for overlay/overlay2](#backing-filesystem-without-d_type-support-for-overlayoverlay2) | v1.13      | v17.12
-Removed    | [`--automated` and `--stars` flags on `docker search`](#--automated-and---stars-flags-on-docker-search)                            | v1.12      | v20.10
-Deprecated | [`-h` shorthand for `--help`](#-h-shorthand-for---help)                                                                            | v1.12      | v17.09
-Removed    | [`-e` and `--email` flags on `docker login`](#-e-and---email-flags-on-docker-login)                                                | v1.11      | v17.06
-Deprecated | [Separator (`:`) of `--security-opt` flag on `docker run`](#separator--of---security-opt-flag-on-docker-run)                       | v1.11      | v17.06
-Deprecated | [Ambiguous event fields in API](#ambiguous-event-fields-in-api)                                                                    | v1.10      | -
-Removed    | [`-f` flag on `docker tag`](#-f-flag-on-docker-tag)                                                                                | v1.10      | v1.12
-Removed    | [HostConfig at API container start](#hostconfig-at-api-container-start)                                                            | v1.10      | v1.12
-Removed    | [`--before` and `--since` flags on `docker ps`](#--before-and---since-flags-on-docker-ps)                                          | v1.10      | v1.12
-Removed    | [Driver-specific log tags](#driver-specific-log-tags)                                                                              | v1.9       | v1.12
-Removed    | [Docker Content Trust `ENV` passphrase variables name change](#docker-content-trust-env-passphrase-variables-name-change)          | v1.9       | v1.12
-Removed    | [`/containers/(id or name)/copy` endpoint](#containersid-or-namecopy-endpoint)                                                     | v1.8       | v1.12
-Removed    | [LXC built-in exec driver](#lxc-built-in-exec-driver)                                                                              | v1.8       | v1.10
-Removed    | [Old Command Line Options](#old-command-line-options)                                                                              | v1.8       | v1.10
-Removed    | [`--api-enable-cors` flag on `dockerd`](#--api-enable-cors-flag-on-dockerd)                                                        | v1.6       | v17.09
-Removed    | [`--run` flag on `docker commit`](#--run-flag-on-docker-commit)                                                                    | v0.10      | v1.13
-Removed    | [Three arguments form in `docker import`](#three-arguments-form-in-docker-import)                                                  | v0.6.7     | v1.12
+| Status     | Feature                                                                                                                            | Deprecated | Remove |
+|------------|------------------------------------------------------------------------------------------------------------------------------------|------------|--------|
+| Deprecated | [Support for encrypted TLS private keys](#support-for-encrypted-tls-private-keys)                                                  | v20.10     | -      |
+| Deprecated | [Kubernetes stack and context support](#kubernetes-stack-and-context-support)                                                      | v20.10     | -      |
+| Deprecated | [Pulling images from non-compliant image registries](#pulling-images-from-non-compliant-image-registries)                          | v20.10     | -      |
+| Deprecated | [Linux containers on Windows (LCOW)](#linux-containers-on-windows-lcow-experimental)                                               | v20.10     | -      |
+| Deprecated | [BLKIO weight options with cgroups v1](#blkio-weight-options-with-cgroups-v1)                                                      | v20.10     | -      |
+| Deprecated | [Kernel memory limit](#kernel-memory-limit)                                                                                        | v20.10     | -      |
+| Deprecated | [Classic Swarm and overlay networks using external key/value stores](#classic-swarm-and-overlay-networks-using-cluster-store)      | v20.10     | -      |
+| Deprecated | [Support for the legacy `~/.dockercfg` configuration file for authentication](#support-for-legacy-dockercfg-configuration-files)   | v20.10     | -      |
+| Deprecated | [CLI plugins support](#cli-plugins-support)                                                                                        | v20.10     | -      |
+| Deprecated | [Dockerfile legacy `ENV name value` syntax](#dockerfile-legacy-env-name-value-syntax)                                              | v20.10     | -      |
+| Removed    | [`docker build --stream` flag (experimental)](#docker-build---stream-flag-experimental)                                            | v20.10     | v20.10 |
+| Deprecated | [`fluentd-async-connect` log opt](#fluentd-async-connect-log-opt)                                                                  | v20.10     | -      |
+| Deprecated | [Configuration options for experimental CLI features](#configuration-options-for-experimental-cli-features)                        | v19.03     | v20.10 |
+| Deprecated | [Pushing and pulling with image manifest v2 schema 1](#pushing-and-pulling-with-image-manifest-v2-schema-1)                        | v19.03     | v20.10 |
+| Removed    | [`docker engine` subcommands](#docker-engine-subcommands)                                                                          | v19.03     | v20.10 |
+| Removed    | [Top-level `docker deploy` subcommand (experimental)](#top-level-docker-deploy-subcommand-experimental)                            | v19.03     | v20.10 |
+| Removed    | [`docker stack deploy` using "dab" files (experimental)](#docker-stack-deploy-using-dab-files-experimental)                        | v19.03     | v20.10 |
+| Disabled   | [Support for the `overlay2.override_kernel_check` storage option](#support-for-the-overlay2override_kernel_check-storage-option)   | v19.03     | -      |
+| Deprecated | [AuFS storage driver](#aufs-storage-driver)                                                                                        | v19.03     | -      |
+| Deprecated | [Legacy "overlay" storage driver](#legacy-overlay-storage-driver)                                                                  | v18.09     | -      |
+| Deprecated | [Device mapper storage driver](#device-mapper-storage-driver)                                                                      | v18.09     | -      |
+| Removed    | [Use of reserved namespaces in engine labels](#use-of-reserved-namespaces-in-engine-labels)                                        | v18.06     | v20.10 |
+| Removed    | [`--disable-legacy-registry` override daemon option](#--disable-legacy-registry-override-daemon-option)                            | v17.12     | v19.03 |
+| Removed    | [Interacting with V1 registries](#interacting-with-v1-registries)                                                                  | v17.06     | v17.12 |
+| Removed    | [Asynchronous `service create` and `service update` as default](#asynchronous-service-create-and-service-update-as-default)        | v17.05     | v17.10 |
+| Removed    | [`-g` and `--graph` flags on `dockerd`](#-g-and---graph-flags-on-dockerd)                                                          | v17.05     | -      |
+| Deprecated | [Top-level network properties in NetworkSettings](#top-level-network-properties-in-networksettings)                                | v1.13      | v17.12 |
+| Removed    | [`filter` param for `/images/json` endpoint](#filter-param-for-imagesjson-endpoint)                                                | v1.13      | v20.10 |
+| Removed    | [`repository:shortid` image references](#repositoryshortid-image-references)                                                       | v1.13      | v17.12 |
+| Removed    | [`docker daemon` subcommand](#docker-daemon-subcommand)                                                                            | v1.13      | v17.12 |
+| Removed    | [Duplicate keys with conflicting values in engine labels](#duplicate-keys-with-conflicting-values-in-engine-labels)                | v1.13      | v17.12 |
+| Deprecated | [`MAINTAINER` in Dockerfile](#maintainer-in-dockerfile)                                                                            | v1.13      | -      |
+| Deprecated | [API calls without a version](#api-calls-without-a-version)                                                                        | v1.13      | v17.12 |
+| Removed    | [Backing filesystem without `d_type` support for overlay/overlay2](#backing-filesystem-without-d_type-support-for-overlayoverlay2) | v1.13      | v17.12 |
+| Removed    | [`--automated` and `--stars` flags on `docker search`](#--automated-and---stars-flags-on-docker-search)                            | v1.12      | v20.10 |
+| Deprecated | [`-h` shorthand for `--help`](#-h-shorthand-for---help)                                                                            | v1.12      | v17.09 |
+| Removed    | [`-e` and `--email` flags on `docker login`](#-e-and---email-flags-on-docker-login)                                                | v1.11      | v17.06 |
+| Deprecated | [Separator (`:`) of `--security-opt` flag on `docker run`](#separator--of---security-opt-flag-on-docker-run)                       | v1.11      | v17.06 |
+| Deprecated | [Ambiguous event fields in API](#ambiguous-event-fields-in-api)                                                                    | v1.10      | -      |
+| Removed    | [`-f` flag on `docker tag`](#-f-flag-on-docker-tag)                                                                                | v1.10      | v1.12  |
+| Removed    | [HostConfig at API container start](#hostconfig-at-api-container-start)                                                            | v1.10      | v1.12  |
+| Removed    | [`--before` and `--since` flags on `docker ps`](#--before-and---since-flags-on-docker-ps)                                          | v1.10      | v1.12  |
+| Removed    | [Driver-specific log tags](#driver-specific-log-tags)                                                                              | v1.9       | v1.12  |
+| Removed    | [Docker Content Trust `ENV` passphrase variables name change](#docker-content-trust-env-passphrase-variables-name-change)          | v1.9       | v1.12  |
+| Removed    | [`/containers/(id or name)/copy` endpoint](#containersid-or-namecopy-endpoint)                                                     | v1.8       | v1.12  |
+| Removed    | [LXC built-in exec driver](#lxc-built-in-exec-driver)                                                                              | v1.8       | v1.10  |
+| Removed    | [Old Command Line Options](#old-command-line-options)                                                                              | v1.8       | v1.10  |
+| Removed    | [`--api-enable-cors` flag on `dockerd`](#--api-enable-cors-flag-on-dockerd)                                                        | v1.6       | v17.09 |
+| Removed    | [`--run` flag on `docker commit`](#--run-flag-on-docker-commit)                                                                    | v0.10      | v1.13  |
+| Removed    | [Three arguments form in `docker import`](#three-arguments-form-in-docker-import)                                                  | v0.6.7     | v1.12  |
 
 ### Support for encrypted TLS private keys
 
@@ -254,6 +256,21 @@ Users that want to use this feature are encouraged to enable BuildKit by setting
 the `DOCKER_BUILDKIT=1` environment variable or through the daemon or CLI configuration
 files.
 
+### `fluentd-async-connect` log opt
+
+**Deprecated in Release: v20.10**
+
+The `--log-opt fluentd-async-connect` option for the fluentd logging driver is
+[deprecated in favor of `--log-opt fluentd-async`](https://github.com/moby/moby/pull/39086).
+A deprecation message is logged in the daemon logs if the old option is used:
+
+```console
+fluent#New: AsyncConnect is now deprecated, please use Async instead
+```
+
+Users are encouraged to use the `fluentd-async` option going forward, as support
+for the old option will be removed in a future release.
+
 ### Pushing and pulling with image manifest v2 schema 1
 
 **Deprecated in Release: v19.03**
@@ -307,6 +324,19 @@ format, support for the DAB file format and the top-level docker deploy command
 (hidden by default in 19.03), will be removed, in favour of `docker stack deploy`
 using compose files.
 
+### Support for the `overlay2.override_kernel_check` storage option
+
+**Deprecated in Release: v19.03**
+**Disabled in Release: v19.03**
+
+This daemon configuration option disabled the Linux kernel version check used
+to detect if the kernel supported OverlayFS with multiple lower dirs, which is
+required for the overlay2 storage driver. Starting with Docker v19.03.7, the
+detection was improved to no longer depend on the kernel _version_, so this
+option was no longer used.
+
+Docker v22.06 logs a warning in the daemon logs if this option is set, and
+users should remove this option from their daemon configuration.
 
 ### AuFS storage driver
 

docs/extend/legacy_plugins.md

@@ -77,7 +77,7 @@ The sections below provide an inexhaustive overview of available plugins.
 | [Local Persist Plugin](https://github.com/CWSpear/local-persist)                                   | A volume plugin that extends the default `local` driver's functionality by allowing you specify a mountpoint anywhere on the host, which enables the files to *always persist*, even if the volume is removed via `docker volume rm`.                                                                         |
 | [NetApp Plugin](https://github.com/NetApp/netappdvp) (nDVP)                                        | A volume plugin that provides direct integration with the Docker ecosystem for the NetApp storage portfolio. The nDVP package supports the provisioning and management of storage resources from the storage platform to Docker hosts, with a robust framework for adding additional platforms in the future. |
 | [Netshare plugin](https://github.com/ContainX/docker-volume-netshare)                              | A volume plugin that provides volume management for NFS 3/4, AWS EFS and CIFS file systems.                                                                                                                                                                                                                   |
-| [Nimble Storage Volume Plugin](https://connect.nimblestorage.com/community/app-integration/docker) | A volume plug-in that integrates with Nimble Storage Unified Flash Fabric arrays. The plug-in abstracts array volume capabilities to the Docker administrator to allow self-provisioning of secure multi-tenant volumes and clones.                                                                           |
+| [Nimble Storage Volume Plugin](https://scod.hpedev.io/docker_volume_plugins/hpe_nimble_storage/index.html) | A volume plug-in that integrates with Nimble Storage Unified Flash Fabric arrays. The plug-in abstracts array volume capabilities to the Docker administrator to allow self-provisioning of secure multi-tenant volumes and clones.                                                                           |
 | [OpenStorage Plugin](https://github.com/libopenstorage/openstorage)                                | A cluster-aware volume plugin that provides volume management for file and block storage solutions.  It implements a vendor neutral specification for implementing extensions such as CoS, encryption, and snapshots. It has example drivers based on FUSE, NFS, NBD and EBS to name a few.                   |
 | [Portworx Volume Plugin](https://github.com/portworx/px-dev)                                       | A volume plugin that turns any server into a scale-out converged compute/storage node, providing container granular storage and highly available volumes across any node, using a shared-nothing storage backend that works with any docker scheduler.                                                        |
 | [Quobyte Volume Plugin](https://github.com/quobyte/docker-volume)                                  | A volume plugin that connects Docker to [Quobyte](https://www.quobyte.com/containers)'s data center file system, a general-purpose scalable and fault-tolerant storage platform.                                                                                                                               |

docs/reference/builder.md

@@ -112,7 +112,7 @@ instructions.
 
 Whenever possible, Docker uses a build-cache to accelerate the `docker build`
 process significantly. This is indicated by the `CACHED` message in the console
-output. (For more information, see the [`Dockerfile` best practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/):
+output. (For more information, see the [`Dockerfile` best practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/)):
 
 ```console
 $ docker build -t svendowideit/ambassador .
@@ -159,8 +159,8 @@ implementation. For example, BuildKit can:
 To use the BuildKit backend, you need to set an environment variable
 `DOCKER_BUILDKIT=1` on the CLI before invoking `docker build`.
 
-To learn about the experimental Dockerfile syntax available to BuildKit-based
-builds [refer to the documentation in the BuildKit repository](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md).
+To learn about the Dockerfile syntax available to BuildKit-based
+builds [refer to the documentation in the BuildKit repository](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md).
 
 ## Format
 
@@ -1632,7 +1632,7 @@ If you forget to add `exec` to the beginning of your `ENTRYPOINT`:
 ```dockerfile
 FROM ubuntu
 ENTRYPOINT top -b
-CMD --ignored-param1
+CMD -- --ignored-param1
 ```
 
 You can then run it (giving it a name for the next step):
@@ -1640,12 +1640,15 @@ You can then run it (giving it a name for the next step):
 ```console
 $ docker run -it --name test top --ignored-param2
 
-Mem: 1704184K used, 352484K free, 0K shrd, 0K buff, 140621524238337K cached
-CPU:   9% usr   2% sys   0% nic  88% idle   0% io   0% irq   0% sirq
-Load average: 0.01 0.02 0.05 2/101 7
-  PID  PPID USER     STAT   VSZ %VSZ %CPU COMMAND
-    1     0 root     S     3168   0%   0% /bin/sh -c top -b cmd cmd2
-    7     1 root     R     3164   0%   0% top -b
+top - 13:58:24 up 17 min,  0 users,  load average: 0.00, 0.00, 0.00
+Tasks:   2 total,   1 running,   1 sleeping,   0 stopped,   0 zombie
+%Cpu(s): 16.7 us, 33.3 sy,  0.0 ni, 50.0 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
+MiB Mem :   1990.8 total,   1354.6 free,    231.4 used,    404.7 buff/cache
+MiB Swap:   1024.0 total,   1024.0 free,      0.0 used.   1639.8 avail Mem
+
+  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
+    1 root      20   0    2612    604    536 S   0.0   0.0   0:00.02 sh
+    6 root      20   0    5956   3188   2768 R   0.0   0.2   0:00.00 top
 ```
 
 You can see from the output of `top` that the specified `ENTRYPOINT` is not `PID 1`.
@@ -1654,12 +1657,12 @@ If you then run `docker stop test`, the container will not exit cleanly - the
 `stop` command will be forced to send a `SIGKILL` after the timeout:
 
 ```console
-$ docker exec -it test ps aux
+$ docker exec -it test ps waux
 
-PID   USER     COMMAND
-    1 root     /bin/sh -c top -b cmd cmd2
-    7 root     top -b
-    8 root     ps aux
+USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
+root         1  0.4  0.0   2612   604 pts/0    Ss+  13:58   0:00 /bin/sh -c top -b --ignored-param2
+root         6  0.0  0.1   5956  3188 pts/0    S+   13:58   0:00 top -b
+root         7  0.0  0.1   5884  2816 pts/1    Rs+  13:58   0:00 ps waux
 
 $ /usr/bin/time docker stop test
 
@@ -1824,6 +1827,11 @@ RUN pwd
 The output of the final `pwd` command in this `Dockerfile` would be
 `/path/$DIRNAME`
 
+If not specified, the default working directory is `/`. In practice, if you aren't building a Dockerfile from scratch (`FROM scratch`), 
+the `WORKDIR` may likely be set by the base image you're using.
+
+Therefore, to avoid unintended operations in unknown directories, it is best practice to set your `WORKDIR` explicitly.
+
 ## ARG
 
 ```dockerfile

docs/reference/commandline/build.md

@@ -99,16 +99,16 @@ $ docker build https://github.com/docker/rootfs.git#container:docker
 The following table represents all the valid suffixes with their build
 contexts:
 
-Build Syntax Suffix             | Commit Used           | Build Context Used
---------------------------------|-----------------------|-------------------
-`myrepo.git`                    | `refs/heads/master`   | `/`
-`myrepo.git#mytag`              | `refs/tags/mytag`     | `/`
-`myrepo.git#mybranch`           | `refs/heads/mybranch` | `/`
-`myrepo.git#pull/42/head`       | `refs/pull/42/head`   | `/`
-`myrepo.git#:myfolder`          | `refs/heads/master`   | `/myfolder`
-`myrepo.git#master:myfolder`    | `refs/heads/master`   | `/myfolder`
-`myrepo.git#mytag:myfolder`     | `refs/tags/mytag`     | `/myfolder`
-`myrepo.git#mybranch:myfolder`  | `refs/heads/mybranch` | `/myfolder`
+| Build Syntax Suffix            | Commit Used           | Build Context Used |
+|--------------------------------|-----------------------|--------------------|
+| `myrepo.git`                   | `refs/heads/master`   | `/`                |
+| `myrepo.git#mytag`             | `refs/tags/mytag`     | `/`                |
+| `myrepo.git#mybranch`          | `refs/heads/mybranch` | `/`                |
+| `myrepo.git#pull/42/head`      | `refs/pull/42/head`   | `/`                |
+| `myrepo.git#:myfolder`         | `refs/heads/master`   | `/myfolder`        |
+| `myrepo.git#master:myfolder`   | `refs/heads/master`   | `/myfolder`        |
+| `myrepo.git#mytag:myfolder`    | `refs/tags/mytag`     | `/myfolder`        |
+| `myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder`        |
 
 > **Note**
 >
@@ -461,11 +461,11 @@ technology. On Linux, the only supported is the `default` option which uses
 Linux namespaces. On Microsoft Windows, you can specify these values:
 
 
-| Value     | Description                                                                                                                                                   |
-|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value.  |
-| `process` | Namespace isolation only.                                                                                                                                     |
-| `hyperv`  | Hyper-V hypervisor partition-based isolation.                                                                                                                 |
+| Value     | Description                                                                                                                                                                    |
+|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. |
+| `process` | Namespace isolation only.                                                                                                                                                      |
+| `hyperv`  | Hyper-V hypervisor partition-based isolation.                                                                                                                                  |
 
 Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
 
@@ -485,10 +485,10 @@ image. Commands after the target stage will be skipped.
 
 ```dockerfile
 FROM debian AS build-env
-...
+# ...
 
 FROM alpine AS production-env
-...
+# ...
 ```
 
 ```console

docs/reference/commandline/config_ls.md

@@ -113,7 +113,7 @@ using a Go template.
 Valid placeholders for the Go template are listed below:
 
 | Placeholder  | Description                                                                          |
-| ------------ | ------------------------------------------------------------------------------------ |
+|--------------|--------------------------------------------------------------------------------------|
 | `.ID`        | Config ID                                                                            |
 | `.Name`      | Config name                                                                          |
 | `.CreatedAt` | Time when the config was created                                                     |

docs/reference/commandline/context.md

@@ -0,0 +1,45 @@
+---
+title: "context"
+description: "The context command description and usage"
+keywords: "context"
+---
+
+# config
+
+```markdown
+Manage contexts
+
+Usage:
+docker context [command]
+
+Available Commands:
+create      Create new context
+export      Export a context to a tar or kubeconfig file
+import      Import a context from a tar or zip file
+inspect     Display detailed information on one or more contexts
+list        List available contexts
+rm          Remove one or more contexts
+show        Print the current context
+update      Update a context
+use         Set the default context
+
+Flags:
+-h, --help   Help for context
+
+Use "docker context [command] --help" for more information about a command.
+```
+
+## Description
+
+Manage contexts.
+
+## Related commands
+
+* [context create](context_create.md)
+* [context export](context_export.md)
+* [context import](context_import.md)
+* [context inspect](context_inspect.md)
+* [context list](context_ls.md)
+* [context rm](context_rm.md)
+* [context update](context_update.md)
+* [context use](context_use.md)

docs/reference/commandline/context_use.md

@@ -13,6 +13,7 @@ Set the current docker context
 ```
 
 ## Description
+
 Set the default context to use, when `DOCKER_HOST`, `DOCKER_CONTEXT` environment
 variables and `--host`, `--context` global options are not set.
 To disable usage of contexts, you can use the special `default` context.

docs/reference/commandline/cp.md

@@ -89,6 +89,28 @@ you must be explicit with a relative or absolute path, for example:
 
     `/path/to/file:name.txt` or `./file:name.txt`
 
+## Examples
+
+Copy a local file into container
+
+```console
+$ docker cp ./some_file CONTAINER:/work
+```
+
+Copy files from container to local path
+
+```console
+$ docker cp CONTAINER:/var/logs/ /tmp/app_logs
+```
+
+Copy a file from container to stdout. Please note `cp` command produces a tar stream
+
+```console
+$ docker cp CONTAINER:/var/logs/app.log - | tar x -O | grep "ERROR"
+```
+
+### Corner cases
+
 It is not possible to copy certain system files such as resources under
 `/proc`, `/sys`, `/dev`, [tmpfs](run.md#mount-tmpfs---tmpfs), and mounts created by
 the user in the container. However, you can still copy such files by manually

docs/reference/commandline/create.md

@@ -98,6 +98,7 @@ Options:
       --privileged                    Give extended privileges to this container
   -p, --publish value                 Publish a container's port(s) to the host (default [])
   -P, --publish-all                   Publish all exposed ports to random ports
+      --pull string                   Pull image before creating ("always"|"missing"|"never") (default "missing")
       --read-only                     Mount the container's root filesystem as read only
       --restart string                Restart policy to apply when a container exits (default "no")
                                       Possible values are: no, on-failure[:max-retry], always, unless-stopped
@@ -134,35 +135,51 @@ Options:
 
 ## Description
 
-The `docker create` command creates a writeable container layer over the
-specified image and prepares it for running the specified command.  The
+The `docker container create` (or shorthand: `docker create`) command creates a
+new container from the specified image, without starting it.
+
+When creating a container, the docker daemon creates a writeable container layer
+over the specified image and prepares it for running the specified command.  The
 container ID is then printed to `STDOUT`.  This is similar to `docker run -d`
-except the container is never started.  You can then use the
-`docker start <container_id>` command to start the container at any point.
+except the container is never started. You can then use the `docker container start`
+(or shorthand: `docker start`) command to start the container at any point.
 
 This is useful when you want to set up a container configuration ahead of time
 so that it is ready to start when you need it. The initial status of the
 new container is `created`.
 
-Please see the [run command](run.md) section and the [Docker run reference](../run.md) for more details.
+The `docker create` command shares most of its options with the `docker run`
+command (which performs a `docker create` before starting it). Refer to the
+[`docker run` command](run.md) section and the [Docker run reference](../run.md)
+for details on the available flags and options.
 
 ## Examples
 
 ### Create and start a container
 
-```console
-$ docker create -t -i fedora bash
+The following example creates an interactive container with a pseudo-TTY attached,
+then starts the container and attaches to it:
 
+```console
+$ docker container create -i -t --name mycontainer alpine
 6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752
 
-$ docker start -a -i 6d8af538ec5
+$ docker container start --attach -i mycontainer
+/ # echo hello world
+hello world
+```
 
-bash-4.2#
+The above is the equivalent of a `docker run`:
+
+```console
+$ docker run -it --name mycontainer2 alpine
+/ # echo hello world
+hello world
 ```
 
 ### Initialize volumes
 
-As of v1.4.0 container volumes are initialized during the `docker create` phase
+Container volumes are initialized during the `docker create` phase
 (i.e., `docker run` too). For example, this allows you to `create` the `data`
 volume container, and then use it from another container:
 
@@ -199,59 +216,3 @@ drwxr-sr-x  3 1000 staff   60 Dec  1 03:28 .local
 drwx--S---  2 1000 staff  460 Dec  5 00:51 .ssh
 drwxr-xr-x 32 1000 staff 1140 Dec  5 04:01 docker
 ```
-
-
-Set storage driver options per container.
-
-```console
-$ docker create -it --storage-opt size=120G fedora /bin/bash
-```
-
-This (size) will allow to set the container rootfs size to 120G at creation time.
-This option is only available for the `devicemapper`, `btrfs`, `overlay2`,
-`windowsfilter` and `zfs` graph drivers.
-For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers,
-user cannot pass a size less than the Default BaseFS Size.
-For the `overlay2` storage driver, the size option is only available if the
-backing fs is `xfs` and mounted with the `pquota` mount option.
-Under these conditions, user can pass any size less than the backing fs size.
-
-### Specify isolation technology for container (--isolation)
-
-This option is useful in situations where you are running Docker containers on
-Windows. The `--isolation=<value>` option sets a container's isolation
-technology. On Linux, the only supported is the `default` option which uses
-Linux namespaces. On Microsoft Windows, you can specify these values:
-
-
-| Value     | Description                                                                                                                                                   |
-|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value if the
-daemon is running on Windows server, or `hyperv` if running on Windows client.  |
-| `process` | Namespace isolation only.                                                                                                                                     |
-| `hyperv`   | Hyper-V hypervisor partition-based isolation.                                                                                                                  |
-
-Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
-
-### Dealing with dynamically created devices (--device-cgroup-rule)
-
-Devices available to a container are assigned at creation time. The
-assigned devices will both be added to the cgroup.allow file and
-created into the container once it is run. This poses a problem when
-a new device needs to be added to running container.
-
-One of the solutions is to add a more permissive rule to a container
-allowing it access to a wider range of devices. For example, supposing
-our container needs access to a character device with major `42` and
-any number of minor number (added as new devices appear), the
-following rule would be added:
-
-```console
-$ docker create --device-cgroup-rule='c 42:* rmw' -name my-container my-image
-```
-
-Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 <minor>`
-the required device when it is added.
-
-NOTE: initially present devices still need to be explicitly added to
-the create/run command

docs/reference/commandline/dockerd.md

@@ -115,8 +115,8 @@ Options with [] may be specified multiple times.
 uses different binaries for the daemon and client. To run the daemon you
 type `dockerd`.
 
-To run the daemon with debug output, use `dockerd -D` or add `"debug": true` to
-the `daemon.json` file.
+To run the daemon with debug output, use `dockerd --debug` or add `"debug": true`
+to [the `daemon.json` file](#daemon-configuration-file).
 
 > **Enabling experimental features**
 > 
@@ -312,7 +312,7 @@ article explains how to tune your existing setup without the use of options.
 
 The `btrfs` driver is very fast for `docker build` - but like `devicemapper`
 does not share executable memory between devices. Use
-`dockerd -s btrfs -g /mnt/btrfs_partition`.
+`dockerd --storage-driver btrfs --data-root /mnt/btrfs_partition`.
 
 The `zfs` driver is probably not as fast as `btrfs` but has a longer track record
 on stability. Thanks to `Single Copy ARC` shared blocks between clones will be
@@ -773,7 +773,7 @@ time of writing, the following is the list of `libdm` log levels as well as
 their corresponding levels when output by `dockerd`.
 
 | `libdm` Level | Value | `--log-level` |
-| ------------- | -----:| ------------- |
+|---------------|------:|---------------|
 | `_LOG_FATAL`  |     2 | error         |
 | `_LOG_ERR`    |     3 | error         |
 | `_LOG_WARN`   |     4 | warn          |
@@ -820,20 +820,11 @@ $ sudo dockerd -s btrfs --storage-opt btrfs.min_space=10G
 
 #### Overlay2 options
 
-##### `overlay2.override_kernel_check`
-
-Overrides the Linux kernel version check allowing overlay2. Support for
-specifying multiple lower directories needed by overlay2 was added to the
-Linux kernel in 4.0.0. However, some older kernel versions may be patched
-to add multiple lower directory support for OverlayFS. This option should
-only be used after verifying this support exists in the kernel. Applying
-this option on a kernel without this support will cause failures on mount.
-
 ##### `overlay2.size`
 
 Sets the default max size of the container. It is supported only when the
 backing fs is `xfs` and mounted with `pquota` mount option. Under these
-conditions the user can pass any size less then the backing fs size.
+conditions the user can pass any size less than the backing fs size.
 
 ###### Example
 
@@ -1233,14 +1224,14 @@ for `/var/lib/docker/tmp`. The `DOCKER_TMPDIR` and the data directory can be
 set like this:
 
 ```console
-$ DOCKER_TMPDIR=/mnt/disk2/tmp /usr/local/bin/dockerd -D -g /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1
+$ DOCKER_TMPDIR=/mnt/disk2/tmp /usr/local/bin/dockerd --data-root /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1
 ```
 
 or
 
 ```console
 $ export DOCKER_TMPDIR=/mnt/disk2/tmp
-$ /usr/local/bin/dockerd -D -g /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1
+$ /usr/local/bin/dockerd --data-root /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1
 ````
 
 #### Default cgroup parent
@@ -1462,7 +1453,7 @@ This is a full example of the allowed configuration options on Linux:
 > daemon startup as a flag.
 > On systems that use `systemd` to start the Docker daemon, `-H` is already set, so
 > you cannot use the `hosts` key in `daemon.json` to add listening addresses.
-> See https://docs.docker.com/engine/admin/systemd/#custom-docker-daemon-options for how
+> See ["custom Docker daemon options"](https://docs.docker.com/config/daemon/systemd/#custom-docker-daemon-options) for how
 > to accomplish this task with a systemd drop-in file.
 
 ##### On Windows
@@ -1554,7 +1545,7 @@ The list of currently supported options that can be reconfigured is this:
   be used to run containers.
 - `authorization-plugin`: it specifies the authorization plugins to use.
 - `allow-nondistributable-artifacts`: Replaces the set of registries to which the daemon will push nondistributable artifacts with a new set of registries.
-- `insecure-registries`: it replaces the daemon insecure registries with a new set of insecure registries. If some existing insecure registries in daemon's configuration are not in newly reloaded insecure resgitries, these existing ones will be removed from daemon's config.
+- `insecure-registries`: it replaces the daemon insecure registries with a new set of insecure registries. If some existing insecure registries in daemon's configuration are not in newly reloaded insecure registries, these existing ones will be removed from daemon's config.
 - `registry-mirrors`: it replaces the daemon registry mirrors with a new set of registry mirrors. If some existing registry mirrors in daemon's configuration are not in newly reloaded registry mirrors, these existing ones will be removed from daemon's config.
 - `shutdown-timeout`: it replaces the daemon's existing configuration timeout with a new timeout for shutting down all containers.
 - `features`: it explicitly enables or disables specific features.

docs/reference/commandline/history.md

@@ -54,14 +54,14 @@ using a Go template.
 
 Valid placeholders for the Go template are listed below:
 
-| Placeholder     | Description |
-| --------------- | ----------- |
-| `.ID`           | Image ID    |
+| Placeholder     | Description                                                                                               |
+|-----------------|-----------------------------------------------------------------------------------------------------------|
+| `.ID`           | Image ID                                                                                                  |
 | `.CreatedSince` | Elapsed time since the image was created if `--human=true`, otherwise timestamp of when image was created |
-| `.CreatedAt`    | Timestamp of when image was created |
-| `.CreatedBy`    | Command that was used to create the image |
-| `.Size`         | Image disk size |
-| `.Comment`      | Comment for image |
+| `.CreatedAt`    | Timestamp of when image was created                                                                       |
+| `.CreatedBy`    | Command that was used to create the image                                                                 |
+| `.Size`         | Image disk size                                                                                           |
+| `.Comment`      | Comment for image                                                                                         |
 
 When using the `--format` option, the `history` command will either
 output the data exactly as the template declares or, when using the

docs/reference/commandline/images.md

@@ -293,15 +293,15 @@ using a Go template.
 
 Valid placeholders for the Go template are listed below:
 
-| Placeholder | Description|
-| ---- | ---- |
-| `.ID` | Image ID |
-| `.Repository` | Image repository |
-| `.Tag` | Image tag |
-| `.Digest` | Image digest |
+| Placeholder     | Description                              |
+|-----------------|------------------------------------------|
+| `.ID`           | Image ID                                 |
+| `.Repository`   | Image repository                         |
+| `.Tag`          | Image tag                                |
+| `.Digest`       | Image digest                             |
 | `.CreatedSince` | Elapsed time since the image was created |
-| `.CreatedAt` | Time when the image was created |
-| `.Size` | Image disk size |
+| `.CreatedAt`    | Time when the image was created          |
+| `.Size`         | Image disk size                          |
 
 When using the `--format` option, the `image` command will either
 output the data exactly as the template declares or, when using the

docs/reference/commandline/import.md

@@ -28,16 +28,15 @@ specify an archive, Docker untars it in the container relative to the `/`
 the host. To import from a remote location, specify a `URI` that begins with the
 `http://` or `https://` protocol.
 
-The `--change` option will apply `Dockerfile` instructions to the image
-that is created.
-Supported `Dockerfile` instructions:
+The `--change` option applies `Dockerfile` instructions to the image that is
+created. Supported `Dockerfile` instructions:
 `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR`
 
 ## Examples
 
 ### Import from a remote location
 
-This will create a new untagged image.
+This creates a new untagged image.
 
 ```console
 $ docker import https://example.com/exampleimage.tgz

docs/reference/commandline/index.md

@@ -118,15 +118,15 @@ read the [`dockerd`](dockerd.md) reference page.
 
 ### Swarm management commands
 
-| Command | Description                                                        |
-|:--------|:-------------------------------------------------------------------|
-| [swarm init](swarm_init.md) | Initialize a swarm                             |
-| [swarm join](swarm_join.md) | Join a swarm as a manager node or worker node  |
-| [swarm leave](swarm_leave.md) | Remove the current node from the swarm       |
-| [swarm join-token](swarm_join_token.md) | Display or rotate join tokens      |
-| [swarm unlock](swarm_unlock.md) | Unlock swarm                               |
-| [swarm unlock-key](swarm_unlock_key.md) | Manage the unlock key              |
-| [swarm update](swarm_update.md) | Update attributes of a swarm               |
+| Command                                 | Description                                   |
+|:----------------------------------------|:----------------------------------------------|
+| [swarm init](swarm_init.md)             | Initialize a swarm                            |
+| [swarm join](swarm_join.md)             | Join a swarm as a manager node or worker node |
+| [swarm leave](swarm_leave.md)           | Remove the current node from the swarm        |
+| [swarm join-token](swarm_join-token.md) | Display or rotate join tokens                 |
+| [swarm unlock](swarm_unlock.md)         | Unlock swarm                                  |
+| [swarm unlock-key](swarm_unlock-key.md) | Manage the unlock key                         |
+| [swarm update](swarm_update.md)         | Update attributes of a swarm                  |
 
 ### Swarm service commands
 

docs/reference/commandline/network_connect.md

@@ -36,7 +36,8 @@ $ docker network connect multi-host-network container1
 
 ### Connect a container to a network when it starts
 
-You can also use the `docker run --network=<network-name>` option to start a container and immediately connect it to a network.
+You can also use the `docker run --network=<network-name>` option to start a
+container and immediately connect it to a network.
 
 ```console
 $ docker run -itd --network=multi-host-network busybox
@@ -87,14 +88,17 @@ $ docker network create --subnet 172.20.0.0/16 --ip-range 172.20.240.0/20 multi-
 $ docker network connect --ip 172.20.128.2 multi-host-network container2
 ```
 
-To verify the container is connected, use the `docker network inspect` command. Use `docker network disconnect` to remove a container from the network.
+To verify the container is connected, use the `docker network inspect` command.
+Use `docker network disconnect` to remove a container from the network.
 
 Once connected in network, containers can communicate using only another
 container's IP address or name. For `overlay` networks or custom plugins that
 support multi-host connectivity, containers connected to the same multi-host
 network but launched from different Engines can also communicate in this way.
 
-You can connect a container to one or more networks. The networks need not be the same type. For example, you can connect a single container bridge and overlay networks.
+You can connect a container to one or more networks. The networks need not be
+the same type. For example, you can connect a single container bridge and overlay
+networks.
 
 ## Related commands
 

docs/reference/commandline/network_create.md

@@ -184,7 +184,7 @@ network driver, again with their approximate equivalents to `docker daemon`.
 |--------------|----------------|--------------------------------------------|
 | `--gateway`  | -              | IPv4 or IPv6 Gateway for the master subnet |
 | `--ip-range` | `--fixed-cidr` | Allocate IPs from a range                  |
-| `--internal` | -              | Restrict external access to the network   |
+| `--internal` | -              | Restrict external access to the network    |
 | `--ipv6`     | `--ipv6`       | Enable IPv6 networking                     |
 | `--subnet`   | `--bip`        | Subnet for network                         |
 

docs/reference/commandline/network_ls.md

@@ -204,17 +204,17 @@ using a Go template.
 
 Valid placeholders for the Go template are listed below:
 
-Placeholder  | Description
--------------|------------------------------------------------------------------------------------------
-`.ID`        | Network ID
-`.Name`      | Network name
-`.Driver`    | Network driver
-`.Scope`     | Network scope (local, global)
-`.IPv6`      | Whether IPv6 is enabled on the network or not.
-`.Internal`  | Whether the network is internal or not.
-`.Labels`    | All labels assigned to the network.
-`.Label`     | Value of a specific label for this network. For example `{{.Label "project.version"}}`
-`.CreatedAt` | Time when the network was created
+| Placeholder  | Description                                                                            |
+|--------------|----------------------------------------------------------------------------------------|
+| `.ID`        | Network ID                                                                             |
+| `.Name`      | Network name                                                                           |
+| `.Driver`    | Network driver                                                                         |
+| `.Scope`     | Network scope (local, global)                                                          |
+| `.IPv6`      | Whether IPv6 is enabled on the network or not.                                         |
+| `.Internal`  | Whether the network is internal or not.                                                |
+| `.Labels`    | All labels assigned to the network.                                                    |
+| `.Label`     | Value of a specific label for this network. For example `{{.Label "project.version"}}` |
+| `.CreatedAt` | Time when the network was created                                                      |
 
 When using the `--format` option, the `network ls` command will either
 output the data exactly as the template declares or, when using the

docs/reference/commandline/node_ls.md

@@ -177,16 +177,16 @@ using a Go template.
 
 Valid placeholders for the Go template are listed below:
 
-Placeholder      | Description
------------------|------------------------------------------------------------------------------------------
-`.ID`            | Node ID
-`.Self`          | Node of the daemon (`true/false`, `true`indicates that the node is the same as current docker daemon)
-`.Hostname`      | Node hostname
-`.Status`        | Node status
-`.Availability`  | Node availability ("active", "pause", or "drain")
-`.ManagerStatus` | Manager status of the node
-`.TLSStatus`     | TLS status of the node ("Ready", or "Needs Rotation" has TLS certificate signed by an old CA)
-`.EngineVersion` | Engine version
+| Placeholder      | Description                                                                                           |
+|------------------|-------------------------------------------------------------------------------------------------------|
+| `.ID`            | Node ID                                                                                               |
+| `.Self`          | Node of the daemon (`true/false`, `true`indicates that the node is the same as current docker daemon) |
+| `.Hostname`      | Node hostname                                                                                         |
+| `.Status`        | Node status                                                                                           |
+| `.Availability`  | Node availability ("active", "pause", or "drain")                                                     |
+| `.ManagerStatus` | Manager status of the node                                                                            |
+| `.TLSStatus`     | TLS status of the node ("Ready", or "Needs Rotation" has TLS certificate signed by an old CA)         |
+| `.EngineVersion` | Engine version                                                                                        |
 
 When using the `--format` option, the `node ls` command will either
 output the data exactly as the template declares or, when using the

docs/reference/commandline/node_ps.md

@@ -115,16 +115,16 @@ using a Go template.
 
 Valid placeholders for the Go template are listed below:
 
-Placeholder     | Description
-----------------|------------------------------------------------------------------------------------------
-`.ID`           | Task ID
-`.Name`         | Task name
-`.Image`        | Task image
-`.Node`         | Node ID
-`.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`)
-`.CurrentState` | Current state of the task
-`.Error`        | Error
-`.Ports`        | Task published ports
+| Placeholder     | Description                                                      |
+|-----------------|------------------------------------------------------------------|
+| `.ID`           | Task ID                                                          |
+| `.Name`         | Task name                                                        |
+| `.Image`        | Task image                                                       |
+| `.Node`         | Node ID                                                          |
+| `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) |
+| `.CurrentState` | Current state of the task                                        |
+| `.Error`        | Error                                                            |
+| `.Ports`        | Task published ports                                             |
 
 When using the `--format` option, the `node ps` command will either
 output the data exactly as the template declares or, when using the

docs/reference/commandline/plugin_ls.md

@@ -75,13 +75,13 @@ using a Go template.
 
 Valid placeholders for the Go template are listed below:
 
-Placeholder        | Description
--------------------|------------------------------------------------------------
-`.ID`              | Plugin ID
-`.Name`            | Plugin name and tag
-`.Description`     | Plugin description
-`.Enabled`         | Whether plugin is enabled or not
-`.PluginReference` | The reference used to push/pull from a registry
+| Placeholder        | Description                                     |
+|--------------------|-------------------------------------------------|
+| `.ID`              | Plugin ID                                       |
+| `.Name`            | Plugin name and tag                             |
+| `.Description`     | Plugin description                              |
+| `.Enabled`         | Whether plugin is enabled or not                |
+| `.PluginReference` | The reference used to push/pull from a registry |
 
 When using the `--format` option, the `plugin ls` command will either
 output the data exactly as the template declares or, when using the

docs/reference/commandline/pull.md

@@ -109,8 +109,8 @@ refer to [understand images, containers, and storage drivers](https://docs.docke
 So far, you've pulled images by their name (and "tag"). Using names and tags is
 a convenient way to work with images. When using tags, you can `docker pull` an
 image again to make sure you have the most up-to-date version of that image.
-For example, `docker pull ubuntu:14.04` pulls the latest version of the Ubuntu
-14.04 image.
+For example, `docker pull ubuntu:20.04` pulls the latest version of the Ubuntu
+20.04 image.
 
 In some cases you don't want images to be updated to newer versions, but prefer
 to use a fixed version of an image. Docker enables you to pull an image by its
@@ -119,7 +119,7 @@ of an image to pull. Doing so, allows you to "pin" an image to that version,
 and guarantee that the image you're using is always the same.
 
 To know the digest of an image, pull the image first. Let's pull the latest
-`ubuntu:14.04` image from Docker Hub:
+`ubuntu:20.04` image from Docker Hub:
 
 ```console
 $ docker pull ubuntu:20.04

docs/reference/commandline/run.md

@@ -108,6 +108,7 @@ Options:
       --privileged                    Give extended privileges to this container
   -p, --publish value                 Publish a container's port(s) to the host (default [])
   -P, --publish-all                   Publish all exposed ports to random ports
+      --pull string                   Pull image before running ("always"|"missing"|"never") (default "missing")
       --read-only                     Mount the container's root filesystem as read only
       --restart string                Restart policy to apply when a container exits (default "no")
                                       Possible values are : no, on-failure[:max-retry], always, unless-stopped
@@ -348,7 +349,7 @@ explains in detail how to manipulate ports in Docker.
 
 Note that ports which are not bound to the host (i.e., `-p 80:80` instead of
 `-p 127.0.0.1:80:80`) will be accessible from the outside. This also applies if
-you configured UFW to block this specific port, as Docker manages his
+you configured UFW to block this specific port, as Docker manages its
 own iptables rules. [Read more](https://docs.docker.com/network/iptables/)
 
 ```console
@@ -358,6 +359,48 @@ $ docker run --expose 80 ubuntu bash
 This exposes port `80` of the container without publishing the port to the host
 system's interfaces.
 
+### <a name="pull"></a> Set the pull policy (--pull)
+
+Use the `--pull` flag to set the image pull policy when creating (and running)
+the container.
+
+The `--pull` flag can take one of these values:
+
+| Value               | Description                                                                                                       |
+|:--------------------|:------------------------------------------------------------------------------------------------------------------|
+| `missing` (default) | Pull the image if it was not found in the image cache, or use the cached image otherwise.                         |
+| `never`             | Do not pull the image, even if it's missing, and produce an error if the image does not exist in the image cache. |
+| `always`            | Always perform a pull before creating the container.                                                              |
+
+When creating (and running) a container from an image, the daemon checks if the
+image exists in the local image cache. If the image is missing, an error is
+returned to the cli, allowing it to initiate a pull.
+
+The default (`missing`) is to only pull the image if it is not present in the
+daemon's image cache. This default allows you to run images that only exist
+locally (for example, images you built from a Dockerfile, but that have not
+been pushed to a registry), and reduces networking.
+
+The `always` option always initiates a pull before creating the container. This
+option makes sure the image is up-to-date, and prevents you from using outdated
+images, but may not be suitable in situations where you want to test a locally
+built image before pushing (as pulling the image overwrites the existing image
+in the image cache).
+
+The `never` option disables (implicit) pulling images when creating containers,
+and only uses images that are available in the image cache. If the specified
+image is not found, an error is produced, and the container is not created.
+This option is useful in situations where networking is not available, or to
+prevent images from being pulled implicitly when creating containers.
+
+The following example shows `docker run` with the `--pull=never` option set,
+which produces en error as the image is missing in the image-cache:
+
+```console
+$ docker run --pull=never hello-world
+docker: Error response from daemon: No such image: hello-world:latest.
+```
+
 ### Set environment variables (-e, --env, --env-file)
 
 ```console
@@ -403,10 +446,10 @@ VAR1=value1
 VAR2=value2
 USER
 
-$ docker run --env-file env.list ubuntu env | grep VAR
+$ docker run --env-file env.list ubuntu env | grep -E 'VAR|USER'
 VAR1=value1
 VAR2=value2
-USER=denis
+USER=jonzeolla
 ```
 
 ### Set metadata on container (-l, --label, --label-file)
@@ -544,14 +587,15 @@ retrieve the container's ID once the container has finished running.
 ### Add host device to container (--device)
 
 ```console
-$ docker run --device=/dev/sdc:/dev/xvdc \
-             --device=/dev/sdd --device=/dev/zero:/dev/nulo \
-             -i -t \
-             ubuntu ls -l /dev/{xvdc,sdd,nulo}
+$ docker run -it --rm \
+    --device=/dev/sdc:/dev/xvdc \
+    --device=/dev/sdd \
+    --device=/dev/zero:/dev/foobar \
+    ubuntu ls -l /dev/{xvdc,sdd,foobar}
 
 brw-rw---- 1 root disk 8, 2 Feb  9 16:05 /dev/xvdc
 brw-rw---- 1 root disk 8, 3 Feb  9 16:05 /dev/sdd
-crw-rw-rw- 1 root root 1, 5 Feb  9 16:05 /dev/nulo
+crw-rw-rw- 1 root root 1, 5 Feb  9 16:05 /dev/foobar
 ```
 
 It is often necessary to directly expose devices to a container. The `--device`
@@ -610,9 +654,32 @@ PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.micro
 > This option fails if the container isolation is `hyperv` or when running Linux
 > Containers on Windows (LCOW).
 
+### <a name="device-cgroup-rule"></a> Using dynamically created devices (--device-cgroup-rule)
+
+Devices available to a container are assigned at creation time. The
+assigned devices will both be added to the cgroup.allow file and
+created into the container once it is run. This poses a problem when
+a new device needs to be added to running container.
+
+One of the solutions is to add a more permissive rule to a container
+allowing it access to a wider range of devices. For example, supposing
+our container needs access to a character device with major `42` and
+any number of minor number (added as new devices appear), the
+following rule would be added:
+
+```console
+$ docker run -d --device-cgroup-rule='c 42:* rmw' -name my-container my-image
+```
+
+Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 <minor>`
+the required device when it is added.
+
+> **Note**: initially present devices still need to be explicitly added to the
+> `docker run` / `docker create` command.
+
 ### Access an NVIDIA GPU
 
-The `--gpus­` flag allows you to access NVIDIA GPU resources. First you need to
+The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to
 install [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/).
 Visit [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/)
 for more information.
@@ -634,7 +701,7 @@ $ docker run -it --rm --gpus device=GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a ubu
 The example below exposes the first and third GPUs.
 
 ```console
-$ docker run -it --rm --gpus device=0,2 nvidia-smi
+$ docker run -it --rm --gpus '"device=0,2"' nvidia-smi
 ```
 
 ### Restart policies (--restart)
@@ -719,7 +786,7 @@ $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n"
 > In other words, the following script is not supported:
 >
 > ```console
-> $ docker run -it --ulimit as=1024 fedora /bin/bash`
+> $ docker run -it --ulimit as=1024 fedora /bin/bash
 > ```
 
 The values are sent to the appropriate `syscall` as they are set.
@@ -775,9 +842,9 @@ and 30 seconds for Windows containers.
 ### Specify isolation technology for container (--isolation)
 
 This option is useful in situations where you are running Docker containers on
-Windows. The `--isolation <value>` option sets a container's isolation technology.
-On Linux, the only supported is the `default` option which uses
-Linux namespaces. These two commands are equivalent on Linux:
+Windows. The `--isolation=<value>` option sets a container's isolation technology.
+On Linux, the only supported is the `default` option which uses Linux namespaces.
+These two commands are equivalent on Linux:
 
 ```console
 $ docker run -d busybox top
@@ -786,16 +853,15 @@ $ docker run -d --isolation default busybox top
 
 On Windows, `--isolation` can take one of these values:
 
+| Value     | Description                                                                                |
+|:----------|:-------------------------------------------------------------------------------------------|
+| `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). |
+| `process` | Shared-kernel namespace isolation.                                                         |
+| `hyperv`  | Hyper-V hypervisor partition-based isolation.                                              |
 
-| Value     | Description                                                                                                       |
-|:----------|:------------------------------------------------------------------------------------------------------------------|
-| `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below).                        |
-| `process` | Shared-kernel namespace isolation (not supported on Windows client operating systems older than Windows 10 1809). |
-| `hyperv`  | Hyper-V hypervisor partition-based isolation.                                                                     |
-
-The default isolation on Windows server operating systems is `process`. The default
-isolation on Windows client operating systems is `hyperv`. An attempt to start a container on a client
-operating system older than Windows 10 1809 with `--isolation process` will fail.
+The default isolation on Windows server operating systems is `process`, and `hyperv`
+on Windows client operating systems, such as Windows 10. Process isolation is more
+performant, but requires the image to
 
 On Windows server, assuming the default configuration, these commands are equivalent
 and result in `process` isolation:

docs/reference/commandline/search.md

@@ -140,7 +140,7 @@ using a Go template.
 Valid placeholders for the Go template are:
 
 | Placeholder    | Description                       |
-| -------------- | --------------------------------- |
+|----------------|-----------------------------------|
 | `.Name`        | Image Name                        |
 | `.Description` | Image description                 |
 | `.StarCount`   | Number of stars for the image     |

docs/reference/commandline/secret_ls.md

@@ -113,7 +113,7 @@ using a Go template.
 Valid placeholders for the Go template are listed below:
 
 | Placeholder  | Description                                                                          |
-| ------------ | ------------------------------------------------------------------------------------ |
+|--------------|--------------------------------------------------------------------------------------|
 | `.ID`        | Secret ID                                                                            |
 | `.Name`      | Secret name                                                                          |
 | `.CreatedAt` | Time when the secret was created                                                     |

docs/reference/commandline/service_create.md

@@ -670,16 +670,15 @@ or _exclude_ (`!=`) rule. Multiple constraints find nodes that satisfy every
 expression (AND match). Constraints can match node or Docker Engine labels as
 follows:
 
-node attribute       | matches                        | example
----------------------|--------------------------------|-----------------------------------------------
-`node.id`            | Node ID                        | `node.id==2ivku8v2gvtg4`
-`node.hostname`      | Node hostname                  | `node.hostname!=node-2`
-`node.role`          | Node role (`manager`/`worker`) | `node.role==manager`
-`node.platform.os`   | Node operating system          | `node.platform.os==windows`
-`node.platform.arch` | Node architecture              | `node.platform.arch==x86_64`
-`node.labels`        | User-defined node labels       | `node.labels.security==high`
-`engine.labels`      | Docker Engine's labels         | `engine.labels.operatingsystem==ubuntu-14.04`
-
+| node attribute       | matches                        | example                                       |
+|----------------------|--------------------------------|-----------------------------------------------|
+| `node.id`            | Node ID                        | `node.id==2ivku8v2gvtg4`                      |
+| `node.hostname`      | Node hostname                  | `node.hostname!=node-2`                       |
+| `node.role`          | Node role (`manager`/`worker`) | `node.role==manager`                          |
+| `node.platform.os`   | Node operating system          | `node.platform.os==windows`                   |
+| `node.platform.arch` | Node architecture              | `node.platform.arch==x86_64`                  |
+| `node.labels`        | User-defined node labels       | `node.labels.security==high`                  |
+| `engine.labels`      | Docker Engine's labels         | `engine.labels.operatingsystem==ubuntu-14.04` |
 
 `engine.labels` apply to Docker Engine labels like operating system, drivers,
 etc. Swarm administrators add `node.labels` for operational purposes by using

docs/reference/commandline/service_ls.md

@@ -130,14 +130,14 @@ using a Go template.
 
 Valid placeholders for the Go template are listed below:
 
-Placeholder | Description
-------------|------------------------------------------------------------------------------------------
-`.ID`       | Service ID
-`.Name`     | Service name
-`.Mode`     | Service mode (replicated, global)
-`.Replicas` | Service replicas
-`.Image`    | Service image
-`.Ports`    | Service ports published in ingress mode
+| Placeholder | Description                             |
+|-------------|-----------------------------------------|
+| `.ID`       | Service ID                              |
+| `.Name`     | Service name                            |
+| `.Mode`     | Service mode (replicated, global)       |
+| `.Replicas` | Service replicas                        |
+| `.Image`    | Service image                           |
+| `.Ports`    | Service ports published in ingress mode |
 
 When using the `--format` option, the `service ls` command will either
 output the data exactly as the template declares or, when using the

docs/reference/commandline/service_ps.md

@@ -157,16 +157,16 @@ using a Go template.
 
 Valid placeholders for the Go template are listed below:
 
-Placeholder     | Description
-----------------|------------------------------------------------------------------------------------------
-`.ID`           | Task ID
-`.Name`         | Task name
-`.Image`        | Task image
-`.Node`         | Node ID
-`.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`)
-`.CurrentState` | Current state of the task
-`.Error`        | Error
-`.Ports`        | Task published ports
+| Placeholder     | Description                                                      |
+|-----------------|------------------------------------------------------------------|
+| `.ID`           | Task ID                                                          |
+| `.Name`         | Task name                                                        |
+| `.Image`        | Task image                                                       |
+| `.Node`         | Node ID                                                          |
+| `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) |
+| `.CurrentState` | Current state of the task                                        |
+| `.Error`        | Error                                                            |
+| `.Ports`        | Task published ports                                             |
 
 When using the `--format` option, the `service ps` command will either
 output the data exactly as the template declares or, when using the

docs/reference/commandline/stack_ls.md

@@ -52,7 +52,7 @@ The formatting option (`--format`) pretty-prints stacks using a Go template.
 Valid placeholders for the Go template are listed below:
 
 | Placeholder     | Description        |
-| --------------- | ------------------ |
+|-----------------|--------------------|
 | `.Name`         | Stack name         |
 | `.Services`     | Number of services |
 | `.Orchestrator` | Orchestrator name  |

docs/reference/commandline/stack_ps.md

@@ -129,16 +129,16 @@ The formatting options (`--format`) pretty-prints tasks output using a Go templa
 
 Valid placeholders for the Go template are listed below:
 
-Placeholder     | Description
-----------------|------------------------------------------------------------------------------------------
-`.ID`           | Task ID
-`.Name`         | Task name
-`.Image`        | Task image
-`.Node`         | Node ID
-`.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`)
-`.CurrentState` | Current state of the task
-`.Error`        | Error
-`.Ports`        | Task published ports
+| Placeholder     | Description                                                      |
+|-----------------|------------------------------------------------------------------|
+| `.ID`           | Task ID                                                          |
+| `.Name`         | Task name                                                        |
+| `.Image`        | Task image                                                       |
+| `.Node`         | Node ID                                                          |
+| `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) |
+| `.CurrentState` | Current state of the task                                        |
+| `.Error`        | Error                                                            |
+| `.Ports`        | Task published ports                                             |
 
 When using the `--format` option, the `stack ps` command will either
 output the data exactly as the template declares or, when using the

docs/reference/commandline/stack_services.md

@@ -88,13 +88,13 @@ using a Go template.
 
 Valid placeholders for the Go template are listed below:
 
-Placeholder | Description
-------------|-------------------------------------------------------------------
-`.ID`       | Service ID
-`.Name`     | Service name
-`.Mode`     | Service mode (replicated, global)
-`.Replicas` | Service replicas
-`.Image`    | Service image
+| Placeholder | Description                       |
+|-------------|-----------------------------------|
+| `.ID`       | Service ID                        |
+| `.Name`     | Service name                      |
+| `.Mode`     | Service mode (replicated, global) |
+| `.Replicas` | Service replicas                  |
+| `.Image`    | Service image                     |
 
 When using the `--format` option, the `stack services` command will either
 output the data exactly as the template declares or, when using the

docs/reference/commandline/stats.md

@@ -85,6 +85,13 @@ b95a83497c91        awesome_brattain    0.28%               5.629MiB / 1.952GiB
 67b2525d8ad1        foobar              0.00%               1.727MiB / 1.952GiB   0.09%               2.48kB / 0B         4.11MB / 0B         2
 ```
 
+Running `docker stats` on container with name nginx and getting output in `json` format.
+
+```console
+$ docker stats nginx --no-stream --format "{{ json . }}"
+{"BlockIO":"0B / 13.3kB","CPUPerc":"0.03%","Container":"nginx","ID":"ed37317fbf42","MemPerc":"0.24%","MemUsage":"2.352MiB / 982.5MiB","Name":"nginx","NetIO":"539kB / 606kB","PIDs":"2"}
+```
+
 Running `docker stats` with customized format on all (Running and Stopped) containers.
 
 ```console
@@ -131,18 +138,17 @@ using a Go template.
 
 Valid placeholders for the Go template are listed below:
 
-Placeholder  | Description
------------- | --------------------------------------------
-`.Container` | Container name or ID (user input)
-`.Name`      | Container name
-`.ID`        | Container ID
-`.CPUPerc`   | CPU percentage
-`.MemUsage`  | Memory usage
-`.NetIO`     | Network IO
-`.BlockIO`   | Block IO
-`.MemPerc`   | Memory percentage (Not available on Windows)
-`.PIDs`      | Number of PIDs (Not available on Windows)
-
+| Placeholder  | Description                                  |
+|--------------|----------------------------------------------|
+| `.Container` | Container name or ID (user input)            |
+| `.Name`      | Container name                               |
+| `.ID`        | Container ID                                 |
+| `.CPUPerc`   | CPU percentage                               |
+| `.MemUsage`  | Memory usage                                 |
+| `.NetIO`     | Network IO                                   |
+| `.BlockIO`   | Block IO                                     |
+| `.MemPerc`   | Memory percentage (Not available on Windows) |
+| `.PIDs`      | Number of PIDs (Not available on Windows)    |
 
 When using the `--format` option, the `stats` command either
 outputs the data exactly as the template declares or, when using the

docs/reference/commandline/system_df.md

@@ -87,7 +87,7 @@ using a Go template.
 Valid placeholders for the Go template are listed below:
 
 | Placeholder    | Description                                |
-| -------------- | ------------------------------------------ |
+|----------------|--------------------------------------------|
 | `.Type`        | `Images`, `Containers` and `Local Volumes` |
 | `.TotalCount`  | Total number of items                      |
 | `.Active`      | Number of active items                     |
@@ -122,7 +122,7 @@ Local Volumes       150.3 MB            150.3 MB (100%)
 <Paste>
 ```
 
-**Note** the format option is meaningless when verbose is true.
+The format option has no effect when the `--verbose` option is used.
 
 ## Related commands
 * [system prune](system_prune.md)

docs/reference/commandline/volume_ls.md

@@ -158,14 +158,14 @@ using a Go template.
 
 Valid placeholders for the Go template are listed below:
 
-Placeholder   | Description
---------------|------------------------------------------------------------------------------------------
-`.Name`       | Volume name
-`.Driver`     | Volume driver
-`.Scope`      | Volume scope (local, global)
-`.Mountpoint` | The mount point of the volume on the host
-`.Labels`     | All labels assigned to the volume
-`.Label`      | Value of a specific label for this volume. For example `{{.Label "project.version"}}`
+| Placeholder   | Description                                                                           |
+|---------------|---------------------------------------------------------------------------------------|
+| `.Name`       | Volume name                                                                           |
+| `.Driver`     | Volume driver                                                                         |
+| `.Scope`      | Volume scope (local, global)                                                          |
+| `.Mountpoint` | The mount point of the volume on the host                                             |
+| `.Labels`     | All labels assigned to the volume                                                     |
+| `.Label`      | Value of a specific label for this volume. For example `{{.Label "project.version"}}` |
 
 When using the `--format` option, the `volume ls` command will either
 output the data exactly as the template declares or, when using the

docs/reference/run.md

@@ -1249,12 +1249,12 @@ by default a container is not allowed to access any devices, but a
 "privileged" container is given access to all devices (see
 the documentation on [cgroups devices](https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt)).
 
-When the operator executes `docker run --privileged`, Docker will enable
-access to all devices on the host as well as set some configuration
-in AppArmor or SELinux to allow the container nearly all the same access to the
-host as processes running outside containers on the host. Additional
-information about running with `--privileged` is available on the
-[Docker Blog](https://blog.docker.com/2013/09/docker-can-now-run-within-docker/).
+The --privileged flag gives all capabilities to the container. When the operator
+executes `docker run --privileged`, Docker will enable access to all devices on
+the host as well as set some configuration in AppArmor or SELinux to allow the
+container nearly all the same access to the host as processes running outside
+containers on the host. Additional information about running with `--privileged`
+is available on the [Docker Blog](https://blog.docker.com/2013/09/docker-can-now-run-within-docker/).
 
 If you want to limit access to a specific device or devices you can use
 the `--device` flag. It allows you to specify one or more devices that
@@ -1407,16 +1407,20 @@ The container can have a different logging driver than the Docker daemon. Use
 the `--log-driver=VALUE` with the `docker run` command to configure the
 container's logging driver. The following options are supported:
 
-| Driver      | Description                                                                                                                   |
-|:------------|:------------------------------------------------------------------------------------------------------------------------------|
-| `none`      | Disables any logging for the container. `docker logs` won't be available with this driver.                                    |
-| `json-file` | Default logging driver for Docker. Writes JSON messages to file.  No logging options are supported for this driver.           |
-| `syslog`    | Syslog logging driver for Docker. Writes log messages to syslog.                                                              |
-| `journald`  | Journald logging driver for Docker. Writes log messages to `journald`.                                                        |
-| `gelf`      | Graylog Extended Log Format (GELF) logging driver for Docker. Writes log messages to a GELF endpoint likeGraylog or Logstash. |
-| `fluentd`   | Fluentd logging driver for Docker. Writes log messages to `fluentd` (forward input).                                          |
-| `awslogs`   | Amazon CloudWatch Logs logging driver for Docker. Writes log messages to Amazon CloudWatch Logs                               |
-| `splunk`    | Splunk logging driver for Docker. Writes log messages to `splunk` using Event Http Collector.                                 |
+| Driver       | Description                                                                                                                    |
+|:-------------|:-------------------------------------------------------------------------------------------------------------------------------|
+| `none`       | Disables any logging for the container. `docker logs` won't be available with this driver.                                     |
+| `local`      | Logs are stored in a custom format designed for minimal overhead.                                                              |
+| `json-file`  | Default logging driver for Docker. Writes JSON messages to file.  No logging options are supported for this driver.            |
+| `syslog`     | Syslog logging driver for Docker. Writes log messages to syslog.                                                               |
+| `journald`   | Journald logging driver for Docker. Writes log messages to `journald`.                                                         |
+| `gelf`       | Graylog Extended Log Format (GELF) logging driver for Docker. Writes log messages to a GELF endpoint likeGraylog or Logstash.  |
+| `fluentd`    | Fluentd logging driver for Docker. Writes log messages to `fluentd` (forward input).                                           |
+| `awslogs`    | Amazon CloudWatch Logs logging driver for Docker. Writes log messages to Amazon CloudWatch Logs.                               |
+| `splunk`     | Splunk logging driver for Docker. Writes log messages to `splunk` using Event Http Collector.                                  |
+| `etwlogs`    | Event Tracing for Windows (ETW) events. Writes log messages as Event Tracing for Windows (ETW) events. Only Windows platforms. |                                                  
+| `gcplogs`    | Google Cloud Platform (GCP) Logging. Writes log messages to Google Cloud Platform (GCP) Logging.                               |
+| `logentries` | Rapid7 Logentries. Writes log messages to Rapid7 Logentries.                                                                   |
 
 The `docker logs` command is available only for the `json-file` and `journald`
 logging drivers.  For detailed information on working with logging drivers, see

opts/hosts_unix.go

@@ -1,3 +1,4 @@
+//go:build !windows
 // +build !windows
 
 package opts

opts/hosts_windows.go

@@ -1,5 +1,3 @@
-// +build windows
-
 package opts
 
 // defaultHost constant defines the default host string used by docker on Windows