Skip to content

Add syntax and examples to the description text of some complex options #3417

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gibson042 wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Add syntax and examples to the description text of some complex options #3417

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
917ad65
Add format and/or examples for some complex options
gibson042 Feb 1, 2022
5f750ba
Update reference docs
gibson042 Feb 1, 2022
31688d1
Document special values for --restart
gibson042 Feb 1, 2022
4b32883
Normalize the representation of string and number argument values
gibson042 Feb 1, 2022
262a771
Update reference docs
gibson042 Feb 1, 2022
3f807a4
Include the long form of options in dedicated section headings
gibson042 Feb 1, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions cli/command/container/opts.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ func addFlags(flags *pflag.FlagSet) *containerOptions {
flags.VarP(&copts.attach, "attach", "a", "Attach to STDIN, STDOUT or STDERR")
flags.Var(&copts.deviceCgroupRules, "device-cgroup-rule", "Add a rule to the cgroup allowed devices list")
flags.Var(&copts.devices, "device", "Add a host device to the container")
flags.Var(&copts.gpus, "gpus", "GPU devices to add to the container ('all' to pass all GPUs)")
flags.Var(&copts.gpus, "gpus", `GPU devices to add to the container ("all" to pass all GPUs)`)
flags.SetAnnotation("gpus", "version", []string{"1.40"})
flags.VarP(&copts.env, "env", "e", "Set environment variables")
flags.Var(&copts.envFile, "env-file", "Read in a file of environment variables")
Expand All @@ -181,7 +181,7 @@ func addFlags(flags *pflag.FlagSet) *containerOptions {
flags.VarP(&copts.labels, "label", "l", "Set meta data on a container")
flags.Var(&copts.labelsFile, "label-file", "Read in a line delimited file of labels")
flags.BoolVar(&copts.readonlyRootfs, "read-only", false, "Mount the container's root filesystem as read only")
flags.StringVar(&copts.restartPolicy, "restart", "no", "Restart policy to apply when a container exits")
flags.StringVar(&copts.restartPolicy, "restart", "no", `Restart policy to apply when a container exits ("no"|"on-failure[:max-retry]"|"always"|"unless-stopped")`)
flags.StringVar(&copts.stopSignal, "stop-signal", "", "Signal to stop the container")
flags.IntVar(&copts.stopTimeout, "stop-timeout", 0, "Timeout (in seconds) to stop a container")
flags.SetAnnotation("stop-timeout", "version", []string{"1.25"})
Expand Down Expand Up @@ -220,7 +220,7 @@ func addFlags(flags *pflag.FlagSet) *containerOptions {
flags.Var(&copts.links, "link", "Add link to another container")
flags.Var(&copts.linkLocalIPs, "link-local-ip", "Container IPv4/IPv6 link-local addresses")
flags.StringVar(&copts.macAddress, "mac-address", "", "Container MAC address (e.g., 92:d0:c6:0a:29:33)")
flags.VarP(&copts.publish, "publish", "p", "Publish a container's port(s) to the host")
flags.VarP(&copts.publish, "publish", "p", "Publish a container's port(s) to the host (format: <host address>:[<host port>]:<container port> or [<host port>:]<container port>)")
flags.BoolVarP(&copts.publishAll, "publish-all", "P", false, "Publish all exposed ports to random ports")
// We allow for both "--net" and "--network", although the latter is the recommended way.
flags.Var(&copts.netMode, "net", "Connect a container to a network")
Expand All @@ -238,8 +238,8 @@ func addFlags(flags *pflag.FlagSet) *containerOptions {
flags.Var(&copts.storageOpt, "storage-opt", "Storage driver options for the container")
flags.Var(&copts.tmpfs, "tmpfs", "Mount a tmpfs directory")
flags.Var(&copts.volumesFrom, "volumes-from", "Mount volumes from the specified container(s)")
flags.VarP(&copts.volumes, "volume", "v", "Bind mount a volume")
flags.Var(&copts.mounts, "mount", "Attach a filesystem mount to the container")
flags.VarP(&copts.volumes, "volume", "v", "Bind mount a volume (format: [<volume name|absolute host path>:]<absolute container path>[:<options>])")
flags.Var(&copts.mounts, "mount", `Attach a filesystem mount to the container (e.g., "type=volume,target=/mnt/persistent" or "type=bind,ro,src=/var/run/docker.sock,dst=/run/host-docker.sock")`)

// Health-checking
flags.StringVar(&copts.healthCmd, "health-cmd", "", "Command to run to check health")
Expand Down Expand Up @@ -280,7 +280,7 @@ func addFlags(flags *pflag.FlagSet) *containerOptions {
flags.Var(&copts.kernelMemory, "kernel-memory", "Kernel memory limit")
flags.VarP(&copts.memory, "memory", "m", "Memory limit")
flags.Var(&copts.memoryReservation, "memory-reservation", "Memory soft limit")
flags.Var(&copts.memorySwap, "memory-swap", "Swap limit equal to memory plus swap: '-1' to enable unlimited swap")
flags.Var(&copts.memorySwap, "memory-swap", "Swap limit equal to memory plus swap: -1 to enable unlimited swap")
flags.Int64Var(&copts.swappiness, "memory-swappiness", -1, "Tune container memory swappiness (0 to 100)")
flags.BoolVar(&copts.oomKillDisable, "oom-kill-disable", false, "Disable OOM Killer")
flags.IntVar(&copts.oomScoreAdj, "oom-score-adj", 0, "Tune host's OOM preferences (-1000 to 1000)")
Expand Down
2 changes: 1 addition & 1 deletion cli/command/container/update.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ func NewUpdateCommand(dockerCli command.Cli) *cobra.Command {
flags.Int64VarP(&options.cpuShares, "cpu-shares", "c", 0, "CPU shares (relative weight)")
flags.VarP(&options.memory, "memory", "m", "Memory limit")
flags.Var(&options.memoryReservation, "memory-reservation", "Memory soft limit")
flags.Var(&options.memorySwap, "memory-swap", "Swap limit equal to memory plus swap: '-1' to enable unlimited swap")
flags.Var(&options.memorySwap, "memory-swap", "Swap limit equal to memory plus swap: -1 to enable unlimited swap")
flags.Var(&options.kernelMemory, "kernel-memory", "Kernel memory limit")
flags.StringVar(&options.restartPolicy, "restart", "", "Restart policy to apply when a container exits")
flags.Int64Var(&options.pidsLimit, "pids-limit", 0, "Tune container pids limit (set -1 for unlimited)")
Expand Down
6 changes: 3 additions & 3 deletions cli/command/image/build.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,12 +110,12 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {

flags := cmd.Flags()

flags.VarP(&options.tags, "tag", "t", "Name and optionally a tag in the 'name:tag' format")
flags.VarP(&options.tags, "tag", "t", `Name and optionally a tag in the "name:tag" format`)
flags.Var(&options.buildArgs, "build-arg", "Set build-time variables")
flags.Var(options.ulimits, "ulimit", "Ulimit options")
flags.StringVarP(&options.dockerfileName, "file", "f", "", "Name of the Dockerfile (Default is 'PATH/Dockerfile')")
flags.StringVarP(&options.dockerfileName, "file", "f", "", `Name of the Dockerfile (Default is "PATH/Dockerfile")`)
flags.VarP(&options.memory, "memory", "m", "Memory limit")
flags.Var(&options.memorySwap, "memory-swap", "Swap limit equal to memory plus swap: '-1' to enable unlimited swap")
flags.Var(&options.memorySwap, "memory-swap", "Swap limit equal to memory plus swap: -1 to enable unlimited swap")
flags.Var(&options.shmSize, "shm-size", "Size of /dev/shm")
flags.Int64VarP(&options.cpuShares, "cpu-shares", "c", 0, "CPU shares (relative weight)")
flags.Int64Var(&options.cpuPeriod, "cpu-period", 0, "Limit the CPU CFS (Completely Fair Scheduler) period")
Expand Down
40 changes: 14 additions & 26 deletions docs/reference/commandline/build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ Usage: docker build [OPTIONS] PATH | URL | -
Build an image from a Dockerfile

Options:
--add-host value Add a custom host-to-IP mapping (host:ip) (default [])
--build-arg value Set build-time variables (default [])
--cache-from value Images to consider as cache sources (default [])
--add-host list Add a custom host-to-IP mapping (host:ip)
--build-arg list Set build-time variables
--cache-from strings Images to consider as cache sources
--cgroup-parent string Optional parent cgroup for the container
--compress Compress the build context using gzip
--cpu-period int Limit the CPU CFS (Completely Fair Scheduler) period
Expand All @@ -23,38 +23,26 @@ Options:
--cpuset-cpus string CPUs in which to allow execution (0-3, 0,1)
--cpuset-mems string MEMs in which to allow execution (0-3, 0,1)
--disable-content-trust Skip image verification (default true)
-f, --file string Name of the Dockerfile (Default is 'PATH/Dockerfile')
-f, --file string Name of the Dockerfile (Default is "PATH/Dockerfile")
--force-rm Always remove intermediate containers
--help Print usage
--iidfile string Write the image ID to the file
--isolation string Container isolation technology
--label value Set metadata for an image (default [])
-m, --memory string Memory limit
--memory-swap string Swap limit equal to memory plus swap: '-1' to enable unlimited swap
--label list Set metadata for an image
-m, --memory bytes Memory limit
--memory-swap bytes Swap limit equal to memory plus swap: -1 to enable unlimited swap
--network string Set the networking mode for the RUN instructions during build
'bridge': use default Docker bridge
'none': no networking
'container:<name|id>': reuse another container's network stack
'host': use the Docker host network stack
'<network-name>|<network-id>': connect to a user-defined network
(default "default")
--no-cache Do not use cache when building the image
-o, --output Output destination (format: type=local,dest=path)
--platform string Set platform if server is multi-platform capable
--pull Always attempt to pull a newer version of the image
--progress Set type of progress output (only if BuildKit enabled) (auto, plain, tty).
Use plain to show container output
-q, --quiet Suppress the build output and print image ID on success
--rm Remove intermediate containers after a successful build (default true)
--secret Secret file to expose to the build (only if BuildKit enabled): id=mysecret,src=/local/secret"
--security-opt value Security Options (default [])
--rm Remove intermediate containers after a successful build
(default true)
--security-opt strings Security options
--shm-size bytes Size of /dev/shm
The format is `<number><unit>`. `number` must be greater than `0`.
Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes),
or `g` (gigabytes). If you omit the unit, the system uses bytes.
--squash Squash newly built layers into a single new layer (**Experimental Only**)
--ssh SSH agent socket or keys to expose to the build (only if BuildKit enabled) (format: default|<id>[=<socket>|<key>[,<key>]])
-t, --tag value Name and optionally a tag in the 'name:tag' format (default [])
-t, --tag list Name and optionally a tag in the "name:tag" format
--target string Set the target build stage to build.
--ulimit value Ulimit options (default [])
--ulimit ulimit Ulimit options (default [])
```

## Description
Expand Down
Loading