Merge pull request #2178 from thaJeztah/19.03_backport_docs_updates

[19.03 backport] docs updates

README.md

@@ -1,4 +1,5 @@
-[![build status](https://circleci.com/gh/docker/cli.svg?style=shield)](https://circleci.com/gh/docker/cli/tree/master) [![Build Status](https://jenkins.dockerproject.org/job/docker/job/cli/job/master/badge/icon)](https://jenkins.dockerproject.org/job/docker/job/cli/job/master/)
+[![build status](https://circleci.com/gh/docker/cli.svg?style=shield)](https://circleci.com/gh/docker/cli/tree/master)
+[![Build Status](https://ci.docker.com/public/job/cli/job/master/badge/icon)](https://ci.docker.com/public/job/cli/job/master)
 
 docker/cli
 ==========

appveyor.yml

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

cli/compose/loader/loader.go

@@ -32,6 +32,14 @@ type Options struct {
 	SkipInterpolation bool
 	// Interpolation options
 	Interpolate *interp.Options
+	// Discard 'env_file' entries after resolving to 'environment' section
+	discardEnvFiles bool
+}
+
+// WithDiscardEnvFiles sets the Options to discard the `env_file` section after resolving to
+// the `environment` section
+func WithDiscardEnvFiles(opts *Options) {
+	opts.discardEnvFiles = true
 }
 
 // ParseYAML reads the bytes from a file, parses the bytes into a mapping
@@ -105,6 +113,11 @@ func Load(configDetails types.ConfigDetails, options ...func(*Options)) (*types.
 			return nil, err
 		}
 		cfg.Filename = file.Filename
+		if opts.discardEnvFiles {
+			for i := range cfg.Services {
+				cfg.Services[i].EnvFile = nil
+			}
+		}
 
 		configs = append(configs, cfg)
 	}

cli/compose/loader/loader_test.go

@@ -759,6 +759,38 @@ services:
 	assert.Check(t, is.DeepEqual([]string{"build", "links", "pid"}, unsupported))
 }
 
+func TestDiscardEnvFileOption(t *testing.T) {
+	dict, err := ParseYAML([]byte(`version: "3"
+services:
+  web:
+    image: nginx
+    env_file:
+     - example1.env
+     - example2.env
+`))
+	expectedEnvironmentMap := types.MappingWithEquals{
+		"FOO": strPtr("foo_from_env_file"),
+		"BAZ": strPtr("baz_from_env_file"),
+		"BAR": strPtr("bar_from_env_file_2"), // Original value is overwritten by example2.env
+		"QUX": strPtr("quz_from_env_file_2"),
+	}
+	assert.NilError(t, err)
+	configDetails := buildConfigDetails(dict, nil)
+
+	// Default behavior keeps the `env_file` entries
+	configWithEnvFiles, err := Load(configDetails)
+	assert.NilError(t, err)
+	assert.DeepEqual(t, configWithEnvFiles.Services[0].EnvFile, types.StringList{"example1.env",
+		"example2.env"})
+	assert.DeepEqual(t, configWithEnvFiles.Services[0].Environment, expectedEnvironmentMap)
+
+	// Custom behavior removes the `env_file` entries
+	configWithoutEnvFiles, err := Load(configDetails, WithDiscardEnvFiles)
+	assert.NilError(t, err)
+	assert.DeepEqual(t, configWithoutEnvFiles.Services[0].EnvFile, types.StringList(nil))
+	assert.DeepEqual(t, configWithoutEnvFiles.Services[0].Environment, expectedEnvironmentMap)
+}
+
 func TestBuildProperties(t *testing.T) {
 	dict, err := ParseYAML([]byte(`
 version: "3"

contrib/completion/bash/docker

@@ -550,17 +550,18 @@ __docker_complete_nodes() {
 # output to the IDs or names of matching items. This setting takes
 # precedence over the environment setting.
 __docker_services() {
-	local fields='$2'  # default: service name only
-	[ "${DOCKER_COMPLETION_SHOW_SERVICE_IDS}" = yes ] && fields='$1,$2' # ID & name
+	local format='{{.Name}}'  # default: service name only
+	[ "${DOCKER_COMPLETION_SHOW_SERVICE_IDS}" = yes ] && format='{{.ID}} {{.Name}}' # ID & name
 
 	if [ "$1" = "--id" ] ; then
-		fields='$1' # IDs only
+		format='{{.ID}}' # IDs only
 		shift
 	elif [ "$1" = "--name" ] ; then
-		fields='$2' # names only
+		format='{{.Name}}' # names only
 		shift
 	fi
-        __docker_q service ls "$@" | awk "NR>1 {print $fields}"
+
+	__docker_q service ls --quiet --format "$format" "$@"
 }
 
 # __docker_complete_services applies completion of services based on the current
@@ -572,7 +573,7 @@ __docker_complete_services() {
 		current="$2"
 		shift 2
 	fi
-	COMPREPLY=( $(compgen -W "$(__docker_services "$@")" -- "$current") )
+	COMPREPLY=( $(__docker_services "$@" --filter "name=$current") )
 }
 
 # __docker_tasks returns a list of all task IDs.
@@ -1204,6 +1205,7 @@ _docker_build() {
 
 _docker_builder() {
 	local subcommands="
+		build
 		prune
 	"
 	__docker_subcommands "$subcommands" && return
@@ -1218,6 +1220,10 @@ _docker_builder() {
 	esac
 }
 
+_docker_builder_build() {
+	_docker_image_build
+}
+
 _docker_builder_prune() {
 	case "$prev" in
 		--filter)

contrib/completion/fish/docker.fish

@@ -16,7 +16,7 @@
 
 function __fish_docker_no_subcommand --description 'Test if docker has yet to be given the subcommand'
     for i in (commandline -opc)
-        if contains -- $i attach build commit cp create diff events exec export history images import info inspect kill load login logout logs pause port ps pull push rename restart rm rmi run save search start stop tag top trust unpause version wait stats
+        if contains -- $i attach build commit cp create diff events exec export history images import info inspect kill load login logout logs network pause port ps pull push rename restart rm rmi run save search start stop tag top trust unpause version wait stats
             return 1
         end
     end
@@ -34,6 +34,11 @@ function __fish_print_docker_containers --description 'Print a list of docker co
     end
 end
 
+function __fish_print_docker_networks --description 'Print a list of docker networks'
+    docker network ls --format "{{.ID}}\n{{.Name}}" | tr ',' '\n'
+end
+
+
 function __fish_docker_no_subcommand_trust --description 'Test if docker has yet to be given the trust subcommand'
     if __fish_seen_subcommand_from trust
         for i in (commandline -opc)
@@ -370,6 +375,21 @@ complete -c docker -A -f -n '__fish_seen_subcommand_from logs' -l since -d 'Show
 complete -c docker -A -f -n '__fish_seen_subcommand_from logs' -l tail -d 'Output the specified number of lines at the end of logs (defaults to all logs)'
 complete -c docker -A -f -n '__fish_seen_subcommand_from logs' -a '(__fish_print_docker_containers running)' -d "Container"
 
+# network
+complete -c docker -f -n '__fish_docker_no_subcommand' -a network -d 'Manage networks'
+complete -c docker -A -f -n '__fish_seen_subcommand_from network' -a connect -d 'Connect a container to a network'
+complete -c docker -A -f -n '__fish_seen_subcommand_from network' -a create -d 'Create a network'
+complete -c docker -A -f -n '__fish_seen_subcommand_from network' -a disconnect -d 'Disconnect a container from a network'
+complete -c docker -A -f -n '__fish_seen_subcommand_from network' -a inspect -d 'Display detailed information on one or more networks'
+complete -c docker -A -f -n '__fish_seen_subcommand_from network' -a ls -d 'List networks'
+complete -c docker -A -f -n '__fish_seen_subcommand_from network' -a prune -d 'Remove all unused networks'
+complete -c docker -A -f -n '__fish_seen_subcommand_from network' -a rm -d 'Remove one or more networks'
+complete -c docker -A -f -n '__fish_seen_subcommand_from network' -l help -d 'Print usage'
+complete -c docker -A -f -n '__fish_seen_subcommand_from network rm' -a '(__fish_print_docker_networks)' -d "Network"
+complete -c docker -A -f -n '__fish_seen_subcommand_from network connect' -a '(__fish_print_docker_networks)' -d "Network"
+complete -c docker -A -f -n '__fish_seen_subcommand_from network disconnect' -a '(__fish_print_docker_networks)' -d "Network"
+complete -c docker -A -f -n '__fish_seen_subcommand_from network inspect' -a '(__fish_print_docker_networks)' -d "Network"
+
 # port
 complete -c docker -f -n '__fish_docker_no_subcommand' -a port -d 'Lookup the public-facing port that is NAT-ed to PRIVATE_PORT'
 complete -c docker -A -f -n '__fish_seen_subcommand_from port' -l help -d 'Print usage'

dockerfiles/Dockerfile.binary-native

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

dockerfiles/Dockerfile.cross

@@ -1,4 +1,4 @@
-ARG GO_VERSION=1.12.10
+ARG GO_VERSION=1.12.12
 
 FROM	dockercore/golang-cross:${GO_VERSION}
 ENV     DISABLE_WARN_OUTSIDE_CONTAINER=1

dockerfiles/Dockerfile.dev

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

dockerfiles/Dockerfile.e2e

@@ -1,4 +1,4 @@
-ARG GO_VERSION=1.12.10
+ARG GO_VERSION=1.12.12
 
 # Use Debian based image as docker-compose requires glibc.
 FROM golang:${GO_VERSION}

dockerfiles/Dockerfile.lint

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

docs/reference/builder.md

@@ -157,10 +157,12 @@ be UPPERCASE to distinguish them from arguments more easily.
 
 
 Docker runs instructions in a `Dockerfile` in order. A `Dockerfile` **must
-start with a \`FROM\` instruction**. The `FROM` instruction specifies the [*Base
-Image*](glossary.md#base-image) from which you are building. `FROM` may only be
-preceded by one or more `ARG` instructions, which declare arguments that are used
-in `FROM` lines in the `Dockerfile`.
+begin with a \`FROM\` instruction**. This may be after [parser
+directives](#parser-directives), [comments](#format), and globally scoped
+[ARGs](#arg). The `FROM` instruction specifies the [*Parent
+Image*](glossary.md#parent-image) from which you are building. `FROM`
+may only be preceded by one or more `ARG` instructions, which declare arguments
+that are used in `FROM` lines in the `Dockerfile`.
 
 Docker treats lines that *begin* with `#` as a comment, unless the line is
 a valid [parser directive](#parser-directives). A `#` marker anywhere
@@ -1720,8 +1722,8 @@ The following `ARG` variables are set automatically:
 * `TARGETVARIANT` - variant component of TARGETPLATFORM
 * `BUILDPLATFORM` - platform of the node performing the build.
 * `BUILDOS` - OS component of BUILDPLATFORM
-* `BUILDARCH` - OS component of BUILDPLATFORM
-* `BUILDVARIANT` - OS component of BUILDPLATFORM
+* `BUILDARCH` - architecture component of BUILDPLATFORM
+* `BUILDVARIANT` - variant component of BUILDPLATFORM
 
 These arguments are defined in the global scope so are not automatically
 available inside build stages or for your `RUN` commands. To expose one of

docs/reference/commandline/cli.md

@@ -54,7 +54,7 @@ each `docker` command with `sudo`. To avoid having to use `sudo` with the
 For more information about installing Docker or `sudo` configuration, refer to
 the [installation](https://docs.docker.com/install/) instructions for your operating system.
 
-### Environment variables
+## Environment variables
 
 For easy reference, the following list of environment variables are supported
 by the `docker` command line:
@@ -96,28 +96,43 @@ variables.
 ### Configuration files
 
 By default, the Docker command line stores its configuration files in a
-directory called `.docker` within your `$HOME` directory. However, you can
-specify a different location via the `DOCKER_CONFIG` environment variable
-or the `--config` command line option. If both are specified, then the
-`--config` option overrides the `DOCKER_CONFIG` environment variable.
-For example:
-
-    docker --config ~/testconfigs/ ps
-
-Instructs Docker to use the configuration files in your `~/testconfigs/`
-directory when running the `ps` command.
+directory called `.docker` within your `$HOME` directory.
 
 Docker manages most of the files in the configuration directory
-and you should not modify them. However, you *can modify* the
+and you should not modify them. However, you *can* modify the
 `config.json` file to control certain aspects of how the `docker`
 command behaves.
 
-Currently, you can modify the `docker` command behavior using environment
+You can modify the `docker` command behavior using environment
 variables or command-line options. You can also use options within
-`config.json` to modify some of the same behavior. When using these
-mechanisms, you must keep in mind the order of precedence among them. Command
-line options override environment variables and environment variables override
-properties you specify in a `config.json` file.
+`config.json` to modify some of the same behavior. If an environment variable
+and the `--config` flag are set, the flag takes precedent over the environment
+variable. Command line options override environment variables and environment
+variables override properties you specify in a `config.json` file.
+
+
+### Change the `.docker` directory
+
+To specify a different directory, use the `DOCKER_CONFIG`
+environment variable or the `--config` command line option. If both are
+specified, then the `--config` option overrides the `DOCKER_CONFIG` environment
+variable. The example below overrides the `docker ps` command using a
+`config.json` file located in the `~/testconfigs/` directory.
+
+```bash
+$ docker --config ~/testconfigs/ ps
+```
+
+This flag only applies to whatever command is being ran. For persistent
+configuration, you can set the `DOCKER_CONFIG` environment variable in your
+shell (e.g. `~/.profile` or `~/.bashrc`). The example below sets the new
+directory to be `HOME/newdir/.docker`.
+
+```bash
+echo export DOCKER_CONFIG=$HOME/newdir/.docker > ~/.profile
+```
+
+### `config.json` properties
 
 The `config.json` file stores a JSON encoding of several properties:
 
@@ -265,6 +280,31 @@ Following is a sample `config.json` file:
 {% endraw %}
 ```
 
+### Experimental features
+
+Experimental features provide early access to future product functionality.
+These features are intended only for testing and feedback as they may change
+between releases without warning or can be removed entirely from a future
+release.
+
+> Experimental features must not be used in production environments.
+{: .warning }
+
+To enable experimental features, edit the `config.json` file and set
+`experimental` to `enabled`. The example below enables experimental features
+in a `config.json` file that already enables a debug feature.
+
+```json
+{
+  "experimental": "enabled",
+  "debug": true
+}
+```
+
+You can also enable experimental features from the Docker Desktop menu. See the
+[Docker Desktop Getting Started page](https://docs.docker.com/docker-for-mac#experimental-features)
+for more information.
+
 ### Notary
 
 If using your own notary server and a self-signed certificate or an internal

docs/reference/commandline/pause.md

@@ -27,14 +27,14 @@ Options:
 ## Description
 
 The `docker pause` command suspends all processes in the specified containers.
-On Linux, this uses the cgroups freezer. Traditionally, when suspending a process
+On Linux, this uses the freezer cgroup. Traditionally, when suspending a process
 the `SIGSTOP` signal is used, which is observable by the process being suspended.
-With the cgroups freezer the process is unaware, and unable to capture,
+With the freezer cgroup the process is unaware, and unable to capture,
 that it is being suspended, and subsequently resumed. On Windows, only Hyper-V
 containers can be paused.
 
 See the
-[cgroups freezer documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt)
+[freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt)
 for further details.
 
 ## Examples

docs/reference/commandline/ps.md

@@ -75,6 +75,22 @@ $ docker ps -a
 container that exposes TCP ports `100, 101, 102` displays `100-102/tcp` in
 the `PORTS` column.
 
+### Show disk usage by container
+
+The `docker ps -s` command displays two different on-disk-sizes for each container:
+
+```bash
+$ docker ps -s
+CONTAINER ID   IMAGE          COMMAND                  CREATED        STATUS       PORTS   NAMES        SIZE                                                                                      SIZE
+e90b8831a4b8   nginx          "/bin/bash -c 'mkdir "   11 weeks ago   Up 4 hours           my_nginx     35.58 kB (virtual 109.2 MB)
+00c6131c5e30   telegraf:1.5   "/entrypoint.sh"         11 weeks ago   Up 11 weeks          my_telegraf  0 B (virtual 209.5 MB)
+```
+  * The "size" information shows the amount of data (on disk) that is used for the _writable_ layer of each container
+  * The "virtual size" is the total amount of disk-space used for the read-only _image_ data used by the container and the writable layer.
+  
+For more information, refer to the [container size on disk](https://docs.docker.com/storage/storagedriver/#container-size-on-disk) section.
+
+
 ### Filtering
 
 The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more
@@ -431,4 +447,4 @@ a87ecb4f327c        com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd
 01946d9d34d8
 c1d3b0166030        com.docker.swarm.node=debian,com.docker.swarm.cpu=6
 41d50ecd2f57        com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd
-```
+```

docs/reference/commandline/search.md

@@ -83,7 +83,7 @@ This example displays images with a name containing 'busybox',
 at least 3 stars and the description isn't truncated in the output:
 
 ```bash
-$ docker search --stars=3 --no-trunc busybox
+$ docker search --filter=stars=3 --no-trunc busybox
 NAME                 DESCRIPTION                                                                               STARS     OFFICIAL   AUTOMATED
 busybox              Busybox base image.                                                                       325       [OK]       
 progrium/busybox                                                                                               50                   [OK]

docs/reference/commandline/unpause.md

@@ -27,10 +27,10 @@ Options:
 ## Description
 
 The `docker unpause` command un-suspends all processes in the specified containers.
-On Linux, it does this using the cgroups freezer.
+On Linux, it does this using the freezer cgroup.
 
 See the
-[cgroups freezer documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt)
+[freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt)
 for further details.
 
 ## Examples

man/src/container/pause.md

@@ -1,11 +1,11 @@
 The `docker container pause` command suspends all processes in the specified containers.
-On Linux, this uses the cgroups freezer. Traditionally, when suspending a process
+On Linux, this uses the freezer cgroup. Traditionally, when suspending a process
 the `SIGSTOP` signal is used, which is observable by the process being suspended.
-With the cgroups freezer the process is unaware, and unable to capture,
+With the freezer cgroup the process is unaware, and unable to capture,
 that it is being suspended, and subsequently resumed. On Windows, only Hyper-V
 containers can be paused.
 
-See the [cgroups freezer documentation]
+See the [freezer cgroup documentation]
 (https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) for
 further details.
 

man/src/container/unpause.md

@@ -1,6 +1,6 @@
 The `docker container unpause` command un-suspends all processes in a container.
-On Linux, it does this using the cgroups freezer.
+On Linux, it does this using the freezer cgroup.
 
-See the [cgroups freezer documentation]
+See the [freezer cgroup documentation]
 (https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) for
 further details.

vendor.conf

@@ -88,7 +88,7 @@ golang.org/x/time                                   fbb02b2291d28baffd63558aa44b
 google.golang.org/genproto                          02b4e95473316948020af0b7a4f0f22c73929b0e
 google.golang.org/grpc                              25c4f928eaa6d96443009bd842389fb4fa48664e # v1.20.1
 gopkg.in/inf.v0                                     d2d2541c53f18d2a059457998ce2876cc8e67cbf # v0.9.1
-gopkg.in/yaml.v2                                    5420a8b6744d3b0345ab293f6fcba19c978f1183 # v2.2.1
+gopkg.in/yaml.v2                                    bb4e33bf68bf89cad44d386192cbed201f35b241 # v2.2.3
 gotest.tools                                        1083505acf35a0bd8a696b26837e1fb3187a7a83 # v2.3.0
 k8s.io/api                                          40a48860b5abbba9aa891b02b32da429b08d96a0 # kubernetes-1.14.0
 k8s.io/apimachinery                                 d7deff9243b165ee192f5551710ea4285dcfd615 # kubernetes-1.14.0

vendor/gopkg.in/yaml.v2/decode.go

@@ -229,6 +229,10 @@ type decoder struct {
 	mapType reflect.Type
 	terrors []string
 	strict  bool
+
+	decodeCount int
+	aliasCount  int
+	aliasDepth  int
 }
 
 var (
@@ -315,6 +319,13 @@ func (d *decoder) prepare(n *node, out reflect.Value) (newout reflect.Value, unm
 }
 
 func (d *decoder) unmarshal(n *node, out reflect.Value) (good bool) {
+	d.decodeCount++
+	if d.aliasDepth > 0 {
+		d.aliasCount++
+	}
+	if d.aliasCount > 100 && d.decodeCount > 1000 && float64(d.aliasCount)/float64(d.decodeCount) > 0.99 {
+		failf("document contains excessive aliasing")
+	}
 	switch n.kind {
 	case documentNode:
 		return d.document(n, out)
@@ -353,7 +364,9 @@ func (d *decoder) alias(n *node, out reflect.Value) (good bool) {
 		failf("anchor '%s' value contains itself", n.value)
 	}
 	d.aliases[n] = true
+	d.aliasDepth++
 	good = d.unmarshal(n.alias, out)
+	d.aliasDepth--
 	delete(d.aliases, n)
 	return good
 }

vendor/gopkg.in/yaml.v2/encode.go

@@ -13,6 +13,19 @@ import (
 	"unicode/utf8"
 )
 
+// jsonNumber is the interface of the encoding/json.Number datatype.
+// Repeating the interface here avoids a dependency on encoding/json, and also
+// supports other libraries like jsoniter, which use a similar datatype with
+// the same interface. Detecting this interface is useful when dealing with
+// structures containing json.Number, which is a string under the hood. The
+// encoder should prefer the use of Int64(), Float64() and string(), in that
+// order, when encoding this type.
+type jsonNumber interface {
+	Float64() (float64, error)
+	Int64() (int64, error)
+	String() string
+}
+
 type encoder struct {
 	emitter yaml_emitter_t
 	event   yaml_event_t
@@ -89,6 +102,21 @@ func (e *encoder) marshal(tag string, in reflect.Value) {
 	}
 	iface := in.Interface()
 	switch m := iface.(type) {
+	case jsonNumber:
+		integer, err := m.Int64()
+		if err == nil {
+			// In this case the json.Number is a valid int64
+			in = reflect.ValueOf(integer)
+			break
+		}
+		float, err := m.Float64()
+		if err == nil {
+			// In this case the json.Number is a valid float64
+			in = reflect.ValueOf(float)
+			break
+		}
+		// fallback case - no number could be obtained
+		in = reflect.ValueOf(m.String())
 	case time.Time, *time.Time:
 		// Although time.Time implements TextMarshaler,
 		// we don't want to treat it as a string for YAML

vendor/gopkg.in/yaml.v2/resolve.go

@@ -81,7 +81,7 @@ func resolvableTag(tag string) bool {
 	return false
 }
 
-var yamlStyleFloat = regexp.MustCompile(`^[-+]?[0-9]*\.?[0-9]+([eE][-+][0-9]+)?$`)
+var yamlStyleFloat = regexp.MustCompile(`^[-+]?(\.[0-9]+|[0-9]+(\.[0-9]*)?)([eE][-+]?[0-9]+)?$`)
 
 func resolve(tag string, in string) (rtag string, out interface{}) {
 	if !resolvableTag(tag) {