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:
@@ -99,7 +99,7 @@ By default, the Docker command line stores its configuration files in a
 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.
 
@@ -111,12 +111,12 @@ variable. Command line options override environment variables and environment
 variables override properties you specify in a `config.json` file.
 
 
-#### Change the `.docker` directory
+### 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 runs the `docker ps` command using a
+variable. The example below overrides the `docker ps` command using a
 `config.json` file located in the `~/testconfigs/` directory.
 
 ```bash
@@ -132,7 +132,7 @@ directory to be `HOME/newdir/.docker`.
 echo export DOCKER_CONFIG=$HOME/newdir/.docker > ~/.profile
 ```
 
-#### `config.json` properties
+### `config.json` properties
 
 The `config.json` file stores a JSON encoding of several properties:
 

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.