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.

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

Wrap CLI --help output to terminal width #28751

Merged
merged 2 commits into from Feb 4, 2017

Conversation

Projects
None yet
7 participants
@ijc
Contributor

ijc commented Nov 23, 2016

- What I did

Line wrapped the output of docker <foo> --help.

This should at least partially unblock issues such as #18797 and #18385 and I think several others by removing concerns about 80 column terminals etc.

- How I did it

spf13/pflag#105 contains the bulk of the functional changes by enhancing the pflag package with a new function to provide a wrapped version of the help for a FlagsSet. With that in place here we just adjust the templates used for --help to use the new function.

This temporarily vendors pflag from my fork until the fate of spf13/pflag#105 is known, we should hold off merging this PR until it is merged.

- How to verify it

Run docker <foo> --help (e.g. docker ps --help or docker run --help) from terminals of various widths (particularly ones narrower than 80 columns).

- Description for the changelog

Output of docker CLI --help is now wrapped to the terminal width.

- A picture of a cute animal (not mandatory but encouraged)
George Harrison, The Beatles

@thaJeztah

This comment has been minimized.

Show comment
Hide comment
@thaJeztah

thaJeztah Dec 27, 2016

Member

With this change; on a 80-chars console;

docker run --help

Usage:	docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

Run a command in a new container

Options:
      --add-host list                         Add a custom host-to-IP
                                              mapping (host:ip) (default [])
  -a, --attach list                           Attach to STDIN, STDOUT or
                                              STDERR (default [])
      --blkio-weight uint16                   Block IO (relative weight),
                                              between 10 and 1000, or 0
                                              to disable (default 0)
      --blkio-weight-device weighted-device   Block IO weight (relative
                                              device weight) (default [])
      --cap-add list                          Add Linux capabilities
                                              (default [])
      --cap-drop list                         Drop Linux capabilities
                                              (default [])
      --cgroup-parent string                  Optional parent cgroup for
                                              the container
      --cidfile string                        Write the container ID to
                                              the file
      --cpu-count int                         CPU count (Windows only)
      --cpu-percent int                       CPU percent (Windows only)
      --cpu-period int                        Limit CPU CFS (Completely
                                              Fair Scheduler) period
      --cpu-quota int                         Limit CPU CFS (Completely
                                              Fair Scheduler) quota
      --cpu-rt-period int                     Limit CPU real-time period
                                              in microseconds
      --cpu-rt-runtime int                    Limit CPU real-time runtime
                                              in microseconds
  -c, --cpu-shares int                        CPU shares (relative weight)
      --cpus decimal                          Number of CPUs (default 0.000)
      --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)
      --credentialspec string                 Credential spec for managed
                                              service account (Windows only)
  -d, --detach                                Run container in background
                                              and print container ID
      --detach-keys string                    Override the key sequence
                                              for detaching a container
      --device list                           Add a host device to the
                                              container (default [])
      --device-read-bps throttled-device      Limit read rate (bytes per
                                              second) from a device
                                              (default [])
      --device-read-iops throttled-device     Limit read rate (IO per
                                              second) from a device
                                              (default [])
      --device-write-bps throttled-device     Limit write rate (bytes per
                                              second) to a device (default [])
      --device-write-iops throttled-device    Limit write rate (IO per
                                              second) to a device (default [])
      --disable-content-trust                 Skip image verification
                                              (default true)
      --dns list                              Set custom DNS servers
                                              (default [])
      --dns-option list                       Set DNS options (default [])
      --dns-search list                       Set custom DNS search
                                              domains (default [])
      --entrypoint string                     Overwrite the default
                                              ENTRYPOINT of the image
  -e, --env list                              Set environment variables
                                              (default [])
      --env-file list                         Read in a file of
                                              environment variables
                                              (default [])
      --expose list                           Expose a port or a range of
                                              ports (default [])
      --group-add list                        Add additional groups to
                                              join (default [])
      --health-cmd string                     Command to run to check health
      --health-interval duration              Time between running the
                                              check (ns|us|ms|s|m|h)
                                              (default 0s)
      --health-retries int                    Consecutive failures needed
                                              to report unhealthy
      --health-timeout duration               Maximum time to allow one
                                              check to run
                                              (ns|us|ms|s|m|h) (default 0s)
      --help                                  Print usage
  -h, --hostname string                       Container host name
      --init                                  Run an init inside the
                                              container that forwards
                                              signals and reaps processes
      --init-path string                      Path to the docker-init binary
  -i, --interactive                           Keep STDIN open even if not
                                              attached
      --io-maxbandwidth string                Maximum IO bandwidth limit
                                              for the system drive
                                              (Windows only)
      --io-maxiops uint                       Maximum IOps limit for the
                                              system drive (Windows only)
      --ip string                             Container IPv4 address
                                              (e.g. 172.30.100.104)
      --ip6 string                            Container IPv6 address
                                              (e.g. 2001:db8::33)
      --ipc string                            IPC namespace to use
      --isolation string                      Container isolation technology
      --kernel-memory string                  Kernel memory limit
  -l, --label list                            Set meta data on a
                                              container (default [])
      --label-file list                       Read in a line delimited
                                              file of labels (default [])
      --link list                             Add link to another
                                              container (default [])
      --link-local-ip list                    Container IPv4/IPv6
                                              link-local addresses
                                              (default [])
      --log-driver string                     Logging driver for the container
      --log-opt list                          Log driver options (default [])
      --mac-address string                    Container MAC address (e.g.
                                              92:d0:c6:0a:29:33)
  -m, --memory string                         Memory limit
      --memory-reservation string             Memory soft limit
      --memory-swap string                    Swap limit equal to memory
                                              plus swap: '-1' to enable
                                              unlimited swap
      --memory-swappiness int                 Tune container memory
                                              swappiness (0 to 100)
                                              (default -1)
      --name string                           Assign a name to the container
      --network string                        Connect a container to a
                                              network (default "default")
      --network-alias list                    Add network-scoped alias
                                              for the container (default [])
      --no-healthcheck                        Disable any
                                              container-specified HEALTHCHECK
      --oom-kill-disable                      Disable OOM Killer
      --oom-score-adj int                     Tune host's OOM preferences
                                              (-1000 to 1000)
      --pid string                            PID namespace to use
      --pids-limit int                        Tune container pids limit
                                              (set -1 for unlimited)
      --privileged                            Give extended privileges to
                                              this container
  -p, --publish list                          Publish a container's
                                              port(s) to the host (default [])
  -P, --publish-all                           Publish all exposed ports
                                              to random ports
      --read-only                             Mount the container's root
                                              filesystem as read only
      --restart string                        Restart policy to apply
                                              when a container exits
                                              (default "no")
      --rm                                    Automatically remove the
                                              container when it exits
      --runtime string                        Runtime to use for this
                                              container
      --security-opt list                     Security Options (default [])
      --shm-size string                       Size of /dev/shm, default
                                              value is 64MB
      --sig-proxy                             Proxy received signals to
                                              the process (default true)
      --stop-signal string                    Signal to stop a container,
                                              SIGTERM by default (default
                                              "SIGTERM")
      --stop-timeout int                      Timeout (in seconds) to
                                              stop a container
      --storage-opt list                      Storage driver options for
                                              the container (default [])
      --sysctl map                            Sysctl options (default map[])
      --tmpfs list                            Mount a tmpfs directory
                                              (default [])
  -t, --tty                                   Allocate a pseudo-TTY
      --ulimit ulimit                         Ulimit options (default [])
  -u, --user string                           Username or UID (format:
                                              <name|uid>[:<group|gid>])
      --userns string                         User namespace to use
      --uts string                            UTS namespace to use
  -v, --volume list                           Bind mount a volume (default [])
      --volume-driver string                  Optional volume driver for
                                              the container
      --volumes-from list                     Mount volumes from the
                                              specified container(s)
                                              (default [])
  -w, --workdir string                        Working directory inside
                                              the container

And on a 60-chars console;

Usage:	docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

Run a command in a new container

Options:
      --add-host list
                Add a custom host-to-IP mapping
                (host:ip) (default [])
  -a, --attach list
                Attach to STDIN, STDOUT or STDERR
                (default [])
      --blkio-weight uint16
                Block IO (relative weight),
                between 10 and 1000, or 0 to
                disable (default 0)

And without this change;

Usage:	docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

Run a command in a new container

Options:
      --add-host list                         Add a custom host-to-IP mapping (h
ost:ip) (default [])
  -a, --attach list                           Attach to STDIN, STDOUT or STDERR
(default [])
      --blkio-weight uint16                   Block IO (relative weight), betwee
n 10 and 1000, or 0 to disable (default 0)
      --blkio-weight-device weighted-device   Block IO weight (relative device w
eight) (default [])
      --cap-add list                          Add Linux capabilities (default []
)
      --cap-drop list                         Drop Linux capabilities (default [
])
      --cgroup-parent string                  Optional parent cgroup for the con
tainer
      --cidfile string                        Write the container ID to the file
      --cpu-count int                         CPU count (Windows only)
      --cpu-percent int                       CPU percent (Windows only)
      --cpu-period int                        Limit CPU CFS (Completely Fair Sch
eduler) period
      --cpu-quota int                         Limit CPU CFS (Completely Fair Sch
eduler) quota
      --cpu-rt-period int                     Limit CPU real-time period in micr
oseconds
      --cpu-rt-runtime int                    Limit CPU real-time runtime in mic
roseconds
  -c, --cpu-shares int                        CPU shares (relative weight)
      --cpus decimal                          Number of CPUs (default 0.000)
      --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)
      --credentialspec string                 Credential spec for managed servic
e account (Windows only)
  -d, --detach                                Run container in background and pr
int container ID
      --detach-keys string                    Override the key sequence for deta
ching a container
      --device list                           Add a host device to the container
 (default [])
      --device-read-bps throttled-device      Limit read rate (bytes per second)
 from a device (default [])
      --device-read-iops throttled-device     Limit read rate (IO per second) fr
om a device (default [])
      --device-write-bps throttled-device     Limit write rate (bytes per second
) to a device (default [])
      --device-write-iops throttled-device    Limit write rate (IO per second) t
o a device (default [])
      --disable-content-trust                 Skip image verification (default t
rue)
      --dns list                              Set custom DNS servers (default []
)
      --dns-option list                       Set DNS options (default [])
      --dns-search list                       Set custom DNS search domains (def
ault [])
      --entrypoint string                     Overwrite the default ENTRYPOINT o
f the image
  -e, --env list                              Set environment variables (default
 [])
      --env-file list                         Read in a file of environment vari
ables (default [])
      --expose list                           Expose a port or a range of ports 
(default [])
      --group-add list                        Add additional groups to join (def
ault [])
      --health-cmd string                     Command to run to check health
      --health-interval duration              Time between running the check (ns
|us|ms|s|m|h) (default 0s)
      --health-retries int                    Consecutive failures needed to rep
ort unhealthy
      --health-timeout duration               Maximum time to allow one check to
 run (ns|us|ms|s|m|h) (default 0s)
      --help                                  Print usage
  -h, --hostname string                       Container host name
      --init                                  Run an init inside the container t
 hat forwards signals and reaps processes
      --init-path string                      Path to the docker-init binary
  -i, --interactive                           Keep STDIN open even if not attach
ed
      --io-maxbandwidth string                Maximum IO bandwidth limit for the
 system drive (Windows only)
      --io-maxiops uint                       Maximum IOps limit for the system 
drive (Windows only)
      --ip string                             Container IPv4 address (e.g. 172.3
0.100.104)
      --ip6 string                            Container IPv6 address (e.g. 2001:
db8::33)
      --ipc string                            IPC namespace to use
      --isolation string                      Container isolation technology
      --kernel-memory string                  Kernel memory limit
  -l, --label list                            Set meta data on a container (defa
ult [])
      --label-file list                       Read in a line delimited file of l
abels (default [])
      --link list                             Add link to another container (def
ault [])
      --link-local-ip list                    Container IPv4/IPv6 link-local add
resses (default [])
      --log-driver string                     Logging driver for the container
      --log-opt list                          Log driver options (default [])
      --mac-address string                    Container MAC address (e.g. 92:d0:
c6:0a:29:33)
  -m, --memory string                         Memory limit
      --memory-reservation string             Memory soft limit
      --memory-swap string                    Swap limit equal to memory plus sw
ap: '-1' to enable unlimited swap
      --memory-swappiness int                 Tune container memory swappiness (
0 to 100) (default -1)
      --name string                           Assign a name to the container
      --network string                        Connect a container to a network (
default "default")
      --network-alias list                    Add network-scoped alias for the c
ontainer (default [])
      --no-healthcheck                        Disable any container-specified HE
ALTHCHECK
      --oom-kill-disable                      Disable OOM Killer
      --oom-score-adj int                     Tune host's OOM preferences (-1000
 to 1000)
      --pid string                            PID namespace to use
      --pids-limit int                        Tune container pids limit (set -1 
for unlimited)
      --privileged                            Give extended privileges to this c
ontainer
  -p, --publish list                          Publish a container's port(s) to t
he host (default [])
  -P, --publish-all                           Publish all exposed ports to rando
m ports
      --read-only                             Mount the container's root filesys
tem as read only
      --restart string                        Restart policy to apply when a con
tainer exits (default "no")
      --rm                                    Automatically remove the container
 when it exits
      --runtime string                        Runtime to use for this container
      --security-opt list                     Security Options (default [])
      --shm-size string                       Size of /dev/shm, default value is
 64MB
      --sig-proxy                             Proxy received signals to the proc
ess (default true)
      --stop-signal string                    Signal to stop a container, SIGTER
M by default (default "SIGTERM")
      --stop-timeout int                      Timeout (in seconds) to stop a con
tainer
      --storage-opt list                      Storage driver options for the con
tainer (default [])
      --sysctl map                            Sysctl options (default map[])
      --tmpfs list                            Mount a tmpfs directory (default [
])
  -t, --tty                                   Allocate a pseudo-TTY
      --ulimit ulimit                         Ulimit options (default [])
  -u, --user string                           Username or UID (format: <name|uid
>[:<group|gid>])
      --userns string                         User namespace to use
      --uts string                            UTS namespace to use
  -v, --volume list                           Bind mount a volume (default [])
      --volume-driver string                  Optional volume driver for the con
tainer
      --volumes-from list                     Mount volumes from the specified c
ontainer(s) (default [])
  -w, --workdir string                        Working directory inside the conta
iner

Note that even with this change, "resizing" the console doesn't re-wrap the output, but at least it's useful when asking the CLI to print --help

I also noticed that 1.13 now outputs weighted-device and throttled-device for some values, which is really too wide, so we should fix that to the 1.12 output.

Member

thaJeztah commented Dec 27, 2016

With this change; on a 80-chars console;

docker run --help

Usage:	docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

Run a command in a new container

Options:
      --add-host list                         Add a custom host-to-IP
                                              mapping (host:ip) (default [])
  -a, --attach list                           Attach to STDIN, STDOUT or
                                              STDERR (default [])
      --blkio-weight uint16                   Block IO (relative weight),
                                              between 10 and 1000, or 0
                                              to disable (default 0)
      --blkio-weight-device weighted-device   Block IO weight (relative
                                              device weight) (default [])
      --cap-add list                          Add Linux capabilities
                                              (default [])
      --cap-drop list                         Drop Linux capabilities
                                              (default [])
      --cgroup-parent string                  Optional parent cgroup for
                                              the container
      --cidfile string                        Write the container ID to
                                              the file
      --cpu-count int                         CPU count (Windows only)
      --cpu-percent int                       CPU percent (Windows only)
      --cpu-period int                        Limit CPU CFS (Completely
                                              Fair Scheduler) period
      --cpu-quota int                         Limit CPU CFS (Completely
                                              Fair Scheduler) quota
      --cpu-rt-period int                     Limit CPU real-time period
                                              in microseconds
      --cpu-rt-runtime int                    Limit CPU real-time runtime
                                              in microseconds
  -c, --cpu-shares int                        CPU shares (relative weight)
      --cpus decimal                          Number of CPUs (default 0.000)
      --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)
      --credentialspec string                 Credential spec for managed
                                              service account (Windows only)
  -d, --detach                                Run container in background
                                              and print container ID
      --detach-keys string                    Override the key sequence
                                              for detaching a container
      --device list                           Add a host device to the
                                              container (default [])
      --device-read-bps throttled-device      Limit read rate (bytes per
                                              second) from a device
                                              (default [])
      --device-read-iops throttled-device     Limit read rate (IO per
                                              second) from a device
                                              (default [])
      --device-write-bps throttled-device     Limit write rate (bytes per
                                              second) to a device (default [])
      --device-write-iops throttled-device    Limit write rate (IO per
                                              second) to a device (default [])
      --disable-content-trust                 Skip image verification
                                              (default true)
      --dns list                              Set custom DNS servers
                                              (default [])
      --dns-option list                       Set DNS options (default [])
      --dns-search list                       Set custom DNS search
                                              domains (default [])
      --entrypoint string                     Overwrite the default
                                              ENTRYPOINT of the image
  -e, --env list                              Set environment variables
                                              (default [])
      --env-file list                         Read in a file of
                                              environment variables
                                              (default [])
      --expose list                           Expose a port or a range of
                                              ports (default [])
      --group-add list                        Add additional groups to
                                              join (default [])
      --health-cmd string                     Command to run to check health
      --health-interval duration              Time between running the
                                              check (ns|us|ms|s|m|h)
                                              (default 0s)
      --health-retries int                    Consecutive failures needed
                                              to report unhealthy
      --health-timeout duration               Maximum time to allow one
                                              check to run
                                              (ns|us|ms|s|m|h) (default 0s)
      --help                                  Print usage
  -h, --hostname string                       Container host name
      --init                                  Run an init inside the
                                              container that forwards
                                              signals and reaps processes
      --init-path string                      Path to the docker-init binary
  -i, --interactive                           Keep STDIN open even if not
                                              attached
      --io-maxbandwidth string                Maximum IO bandwidth limit
                                              for the system drive
                                              (Windows only)
      --io-maxiops uint                       Maximum IOps limit for the
                                              system drive (Windows only)
      --ip string                             Container IPv4 address
                                              (e.g. 172.30.100.104)
      --ip6 string                            Container IPv6 address
                                              (e.g. 2001:db8::33)
      --ipc string                            IPC namespace to use
      --isolation string                      Container isolation technology
      --kernel-memory string                  Kernel memory limit
  -l, --label list                            Set meta data on a
                                              container (default [])
      --label-file list                       Read in a line delimited
                                              file of labels (default [])
      --link list                             Add link to another
                                              container (default [])
      --link-local-ip list                    Container IPv4/IPv6
                                              link-local addresses
                                              (default [])
      --log-driver string                     Logging driver for the container
      --log-opt list                          Log driver options (default [])
      --mac-address string                    Container MAC address (e.g.
                                              92:d0:c6:0a:29:33)
  -m, --memory string                         Memory limit
      --memory-reservation string             Memory soft limit
      --memory-swap string                    Swap limit equal to memory
                                              plus swap: '-1' to enable
                                              unlimited swap
      --memory-swappiness int                 Tune container memory
                                              swappiness (0 to 100)
                                              (default -1)
      --name string                           Assign a name to the container
      --network string                        Connect a container to a
                                              network (default "default")
      --network-alias list                    Add network-scoped alias
                                              for the container (default [])
      --no-healthcheck                        Disable any
                                              container-specified HEALTHCHECK
      --oom-kill-disable                      Disable OOM Killer
      --oom-score-adj int                     Tune host's OOM preferences
                                              (-1000 to 1000)
      --pid string                            PID namespace to use
      --pids-limit int                        Tune container pids limit
                                              (set -1 for unlimited)
      --privileged                            Give extended privileges to
                                              this container
  -p, --publish list                          Publish a container's
                                              port(s) to the host (default [])
  -P, --publish-all                           Publish all exposed ports
                                              to random ports
      --read-only                             Mount the container's root
                                              filesystem as read only
      --restart string                        Restart policy to apply
                                              when a container exits
                                              (default "no")
      --rm                                    Automatically remove the
                                              container when it exits
      --runtime string                        Runtime to use for this
                                              container
      --security-opt list                     Security Options (default [])
      --shm-size string                       Size of /dev/shm, default
                                              value is 64MB
      --sig-proxy                             Proxy received signals to
                                              the process (default true)
      --stop-signal string                    Signal to stop a container,
                                              SIGTERM by default (default
                                              "SIGTERM")
      --stop-timeout int                      Timeout (in seconds) to
                                              stop a container
      --storage-opt list                      Storage driver options for
                                              the container (default [])
      --sysctl map                            Sysctl options (default map[])
      --tmpfs list                            Mount a tmpfs directory
                                              (default [])
  -t, --tty                                   Allocate a pseudo-TTY
      --ulimit ulimit                         Ulimit options (default [])
  -u, --user string                           Username or UID (format:
                                              <name|uid>[:<group|gid>])
      --userns string                         User namespace to use
      --uts string                            UTS namespace to use
  -v, --volume list                           Bind mount a volume (default [])
      --volume-driver string                  Optional volume driver for
                                              the container
      --volumes-from list                     Mount volumes from the
                                              specified container(s)
                                              (default [])
  -w, --workdir string                        Working directory inside
                                              the container

And on a 60-chars console;

Usage:	docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

Run a command in a new container

Options:
      --add-host list
                Add a custom host-to-IP mapping
                (host:ip) (default [])
  -a, --attach list
                Attach to STDIN, STDOUT or STDERR
                (default [])
      --blkio-weight uint16
                Block IO (relative weight),
                between 10 and 1000, or 0 to
                disable (default 0)

And without this change;

Usage:	docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

Run a command in a new container

Options:
      --add-host list                         Add a custom host-to-IP mapping (h
ost:ip) (default [])
  -a, --attach list                           Attach to STDIN, STDOUT or STDERR
(default [])
      --blkio-weight uint16                   Block IO (relative weight), betwee
n 10 and 1000, or 0 to disable (default 0)
      --blkio-weight-device weighted-device   Block IO weight (relative device w
eight) (default [])
      --cap-add list                          Add Linux capabilities (default []
)
      --cap-drop list                         Drop Linux capabilities (default [
])
      --cgroup-parent string                  Optional parent cgroup for the con
tainer
      --cidfile string                        Write the container ID to the file
      --cpu-count int                         CPU count (Windows only)
      --cpu-percent int                       CPU percent (Windows only)
      --cpu-period int                        Limit CPU CFS (Completely Fair Sch
eduler) period
      --cpu-quota int                         Limit CPU CFS (Completely Fair Sch
eduler) quota
      --cpu-rt-period int                     Limit CPU real-time period in micr
oseconds
      --cpu-rt-runtime int                    Limit CPU real-time runtime in mic
roseconds
  -c, --cpu-shares int                        CPU shares (relative weight)
      --cpus decimal                          Number of CPUs (default 0.000)
      --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)
      --credentialspec string                 Credential spec for managed servic
e account (Windows only)
  -d, --detach                                Run container in background and pr
int container ID
      --detach-keys string                    Override the key sequence for deta
ching a container
      --device list                           Add a host device to the container
 (default [])
      --device-read-bps throttled-device      Limit read rate (bytes per second)
 from a device (default [])
      --device-read-iops throttled-device     Limit read rate (IO per second) fr
om a device (default [])
      --device-write-bps throttled-device     Limit write rate (bytes per second
) to a device (default [])
      --device-write-iops throttled-device    Limit write rate (IO per second) t
o a device (default [])
      --disable-content-trust                 Skip image verification (default t
rue)
      --dns list                              Set custom DNS servers (default []
)
      --dns-option list                       Set DNS options (default [])
      --dns-search list                       Set custom DNS search domains (def
ault [])
      --entrypoint string                     Overwrite the default ENTRYPOINT o
f the image
  -e, --env list                              Set environment variables (default
 [])
      --env-file list                         Read in a file of environment vari
ables (default [])
      --expose list                           Expose a port or a range of ports 
(default [])
      --group-add list                        Add additional groups to join (def
ault [])
      --health-cmd string                     Command to run to check health
      --health-interval duration              Time between running the check (ns
|us|ms|s|m|h) (default 0s)
      --health-retries int                    Consecutive failures needed to rep
ort unhealthy
      --health-timeout duration               Maximum time to allow one check to
 run (ns|us|ms|s|m|h) (default 0s)
      --help                                  Print usage
  -h, --hostname string                       Container host name
      --init                                  Run an init inside the container t
 hat forwards signals and reaps processes
      --init-path string                      Path to the docker-init binary
  -i, --interactive                           Keep STDIN open even if not attach
ed
      --io-maxbandwidth string                Maximum IO bandwidth limit for the
 system drive (Windows only)
      --io-maxiops uint                       Maximum IOps limit for the system 
drive (Windows only)
      --ip string                             Container IPv4 address (e.g. 172.3
0.100.104)
      --ip6 string                            Container IPv6 address (e.g. 2001:
db8::33)
      --ipc string                            IPC namespace to use
      --isolation string                      Container isolation technology
      --kernel-memory string                  Kernel memory limit
  -l, --label list                            Set meta data on a container (defa
ult [])
      --label-file list                       Read in a line delimited file of l
abels (default [])
      --link list                             Add link to another container (def
ault [])
      --link-local-ip list                    Container IPv4/IPv6 link-local add
resses (default [])
      --log-driver string                     Logging driver for the container
      --log-opt list                          Log driver options (default [])
      --mac-address string                    Container MAC address (e.g. 92:d0:
c6:0a:29:33)
  -m, --memory string                         Memory limit
      --memory-reservation string             Memory soft limit
      --memory-swap string                    Swap limit equal to memory plus sw
ap: '-1' to enable unlimited swap
      --memory-swappiness int                 Tune container memory swappiness (
0 to 100) (default -1)
      --name string                           Assign a name to the container
      --network string                        Connect a container to a network (
default "default")
      --network-alias list                    Add network-scoped alias for the c
ontainer (default [])
      --no-healthcheck                        Disable any container-specified HE
ALTHCHECK
      --oom-kill-disable                      Disable OOM Killer
      --oom-score-adj int                     Tune host's OOM preferences (-1000
 to 1000)
      --pid string                            PID namespace to use
      --pids-limit int                        Tune container pids limit (set -1 
for unlimited)
      --privileged                            Give extended privileges to this c
ontainer
  -p, --publish list                          Publish a container's port(s) to t
he host (default [])
  -P, --publish-all                           Publish all exposed ports to rando
m ports
      --read-only                             Mount the container's root filesys
tem as read only
      --restart string                        Restart policy to apply when a con
tainer exits (default "no")
      --rm                                    Automatically remove the container
 when it exits
      --runtime string                        Runtime to use for this container
      --security-opt list                     Security Options (default [])
      --shm-size string                       Size of /dev/shm, default value is
 64MB
      --sig-proxy                             Proxy received signals to the proc
ess (default true)
      --stop-signal string                    Signal to stop a container, SIGTER
M by default (default "SIGTERM")
      --stop-timeout int                      Timeout (in seconds) to stop a con
tainer
      --storage-opt list                      Storage driver options for the con
tainer (default [])
      --sysctl map                            Sysctl options (default map[])
      --tmpfs list                            Mount a tmpfs directory (default [
])
  -t, --tty                                   Allocate a pseudo-TTY
      --ulimit ulimit                         Ulimit options (default [])
  -u, --user string                           Username or UID (format: <name|uid
>[:<group|gid>])
      --userns string                         User namespace to use
      --uts string                            UTS namespace to use
  -v, --volume list                           Bind mount a volume (default [])
      --volume-driver string                  Optional volume driver for the con
tainer
      --volumes-from list                     Mount volumes from the specified c
ontainer(s) (default [])
  -w, --workdir string                        Working directory inside the conta
iner

Note that even with this change, "resizing" the console doesn't re-wrap the output, but at least it's useful when asking the CLI to print --help

I also noticed that 1.13 now outputs weighted-device and throttled-device for some values, which is really too wide, so we should fix that to the 1.12 output.

@thaJeztah

This comment has been minimized.

Show comment
Hide comment
@thaJeztah

thaJeztah Dec 27, 2016

Member

I think this output is a lot more useful, so I'm moving it to code review

Member

thaJeztah commented Dec 27, 2016

I think this output is a lot more useful, so I'm moving it to code review

@thaJeztah

This comment has been minimized.

Show comment
Hide comment
@thaJeztah

thaJeztah Dec 27, 2016

Member

ping @dnephin PTAL as well, for the Cobra changes (we may have to include those in our fork?)

Member

thaJeztah commented Dec 27, 2016

ping @dnephin PTAL as well, for the Cobra changes (we may have to include those in our fork?)

@duglin

This comment has been minimized.

Show comment
Hide comment
@duglin

duglin Dec 27, 2016

Contributor

huge +1 to pretty output!

Contributor

duglin commented Dec 27, 2016

huge +1 to pretty output!

@@ -57,6 +59,14 @@ func operationSubCommands(cmd *cobra.Command) []*cobra.Command {
return cmds
}
func wrappedFlagUsages(cmd *cobra.Command) string {
width := 80

This comment has been minimized.

@duglin

duglin Dec 27, 2016

Contributor

I'm not an expert on terminal/curses stuff, but isn't there a way to query for the terminal width?

@duglin

duglin Dec 27, 2016

Contributor

I'm not an expert on terminal/curses stuff, but isn't there a way to query for the terminal width?

This comment has been minimized.

@dnephin

dnephin Dec 27, 2016

Member

Yes, that's what is being done below this line. 80 is just the default

@dnephin

dnephin Dec 27, 2016

Member

Yes, that's what is being done below this line. 80 is just the default

This comment has been minimized.

@duglin

duglin Dec 27, 2016

Contributor

ah, missed that - thanks!

@duglin

duglin Dec 27, 2016

Contributor

ah, missed that - thanks!

@dnephin

I'm not really a fan of this change. If you want to view help text without wrapping use --help | less and scroll over.

for the Cobra changes

There are no Cobra changes, just pflag, which we haven't forked until this PR.

Show outdated Hide outdated vendor.conf
Show outdated Hide outdated vendor/github.com/spf13/pflag/flag.go
@thaJeztah

This comment has been minimized.

Show comment
Hide comment
@thaJeztah

thaJeztah Dec 27, 2016

Member

@dnephin viewing with less does not solve the problem;

screen shot 2016-12-27 at 19 05 13

This PR would at least enable us to provide more information per flag, without it becoming an unreadable mess

Member

thaJeztah commented Dec 27, 2016

@dnephin viewing with less does not solve the problem;

screen shot 2016-12-27 at 19 05 13

This PR would at least enable us to provide more information per flag, without it becoming an unreadable mess

@duglin

This comment has been minimized.

Show comment
Hide comment
@duglin

duglin Dec 27, 2016

Contributor

Can we do the same for docker --help's list of commands too, I see this:

...
  rm          Remove one or more containers
  rmi         Remove one or more images
  run         Run a command in a new container
  save        Save one or more images to a tar archive (streamed to STDOUT by de
fault)
  search      Search the Docker Hub for images
  start       Start one or more stopped containers
  stats       Display a live stream of container(s) resource usage statistics
...
Contributor

duglin commented Dec 27, 2016

Can we do the same for docker --help's list of commands too, I see this:

...
  rm          Remove one or more containers
  rmi         Remove one or more images
  run         Run a command in a new container
  save        Save one or more images to a tar archive (streamed to STDOUT by de
fault)
  search      Search the Docker Hub for images
  start       Start one or more stopped containers
  stats       Display a live stream of container(s) resource usage statistics
...
@dnephin

This comment has been minimized.

Show comment
Hide comment
@dnephin

dnephin Dec 27, 2016

Member

@thaJeztah sorry, it's docker --help | less -S that fixes it.

Member

dnephin commented Dec 27, 2016

@thaJeztah sorry, it's docker --help | less -S that fixes it.

@duglin

This comment has been minimized.

Show comment
Hide comment
@duglin

duglin Dec 27, 2016

Contributor

well, less -S chops it, its not quite the same thing.

Contributor

duglin commented Dec 27, 2016

well, less -S chops it, its not quite the same thing.

@ijc

This comment has been minimized.

Show comment
Hide comment
@ijc

ijc Jan 5, 2017

Contributor

Note that even with this change, "resizing" the console doesn't re-wrap the output,

I'm not aware of any terminal and CLI app pairing which would correctly semantically (i.e. correctly indenting continuation lines as this PR does) re-wrap the output of an already completed command in the terminal scroll back. I think it simply isn't possible given how these things work (although I'd be happy to be proven wrong!)

I'll update spf13/pflag#105 to drop the commented out code and update this PR with the result.

I can have a look at docker --help's output too, but in a separate PR would be best I think.

Contributor

ijc commented Jan 5, 2017

Note that even with this change, "resizing" the console doesn't re-wrap the output,

I'm not aware of any terminal and CLI app pairing which would correctly semantically (i.e. correctly indenting continuation lines as this PR does) re-wrap the output of an already completed command in the terminal scroll back. I think it simply isn't possible given how these things work (although I'd be happy to be proven wrong!)

I'll update spf13/pflag#105 to drop the commented out code and update this PR with the result.

I can have a look at docker --help's output too, but in a separate PR would be best I think.

@ijc

This comment has been minimized.

Show comment
Hide comment
@ijc

ijc Jan 5, 2017

Contributor

If you want to view help text without wrapping use --help | less and scroll over.

@dnephin, I think the point is that people do want wrapping, but the naive approach taken by many (most?) terminal emulators (which is basically equivalent to blindly inserting a \n at the $COLUMNth column) produces an unreadable mess, firstly by wrapping the middle of words but also by starting the continuation at column zero which in the case of the indented definition list used in --help output looks doubly awful.

This PR improves this by wrapping in a way which understands that wrapping is best done on whitespace but also understands the flag name and its help text are distinct and tries to indent the wrapping of the latter in a sensible and readable way.

I think almost every CLI command I've ever come across does something like this (for the better IMHO) although most of them hardcode wrapping at 80 columns, I think, rather than trying to be more dynamic like I've done here.

Contributor

ijc commented Jan 5, 2017

If you want to view help text without wrapping use --help | less and scroll over.

@dnephin, I think the point is that people do want wrapping, but the naive approach taken by many (most?) terminal emulators (which is basically equivalent to blindly inserting a \n at the $COLUMNth column) produces an unreadable mess, firstly by wrapping the middle of words but also by starting the continuation at column zero which in the case of the indented definition list used in --help output looks doubly awful.

This PR improves this by wrapping in a way which understands that wrapping is best done on whitespace but also understands the flag name and its help text are distinct and tries to indent the wrapping of the latter in a sensible and readable way.

I think almost every CLI command I've ever come across does something like this (for the better IMHO) although most of them hardcode wrapping at 80 columns, I think, rather than trying to be more dynamic like I've done here.

@ijc

This comment has been minimized.

Show comment
Hide comment
@ijc

ijc Jan 5, 2017

Contributor

Updated spf13/pflag#105 to remove the commented code and pushed an updated vendoring here.

I'm considering whether I should rebase since this is an older PR. It looks like the merge is currently clean so unless one of the CI tests fails or someone asks me to do otherwise I'll probably not bother.

Contributor

ijc commented Jan 5, 2017

Updated spf13/pflag#105 to remove the commented code and pushed an updated vendoring here.

I'm considering whether I should rebase since this is an older PR. It looks like the merge is currently clean so unless one of the CI tests fails or someone asks me to do otherwise I'll probably not bother.

@ijc

This comment has been minimized.

Show comment
Hide comment
@ijc

ijc Jan 6, 2017

Contributor

CI failed, so rebased.

Contributor

ijc commented Jan 6, 2017

CI failed, so rebased.

@ijc

This comment has been minimized.

Show comment
Hide comment
@ijc

ijc Jan 9, 2017

Contributor

CI failures look to be real, both are:

14:22:58 ----------------------------------------------------------------------
14:22:58 FAIL: docker_cli_help_test.go:16: DockerSuite.TestHelpTextVerify
14:22:58 
14:22:58 docker_cli_help_test.go:139:
14:22:58     c.Fatal(err)
14:22:58 ... Error: Help for "network create" should not have a multi-line option

looks like a test depends on the specific output formatting. I'll take a look.

Contributor

ijc commented Jan 9, 2017

CI failures look to be real, both are:

14:22:58 ----------------------------------------------------------------------
14:22:58 FAIL: docker_cli_help_test.go:16: DockerSuite.TestHelpTextVerify
14:22:58 
14:22:58 docker_cli_help_test.go:139:
14:22:58     c.Fatal(err)
14:22:58 ... Error: Help for "network create" should not have a multi-line option

looks like a test depends on the specific output formatting. I'll take a look.

@ijc

This comment has been minimized.

Show comment
Hide comment
@ijc

ijc Jan 10, 2017

Contributor

I dropped the problematic test since this output is now expected to be wrapped (that's the point!).

That did lead me to 5595da2 which added the test and took me to #11134 and in particular #11134 (comment):

In a previous issue/PR we decided that the help text was getting messy and that all options should
be limited to just one line.

Unfortunately that's where the trail ends. It seems like the thinking has changed in the intervening and AIUI the short descriptions are proving to be too terse in practice (in particular we'd like to include longer lists of the possible values etc which would easily blow 80 columns). Hence wrapping is now desired.

Contributor

ijc commented Jan 10, 2017

I dropped the problematic test since this output is now expected to be wrapped (that's the point!).

That did lead me to 5595da2 which added the test and took me to #11134 and in particular #11134 (comment):

In a previous issue/PR we decided that the help text was getting messy and that all options should
be limited to just one line.

Unfortunately that's where the trail ends. It seems like the thinking has changed in the intervening and AIUI the short descriptions are proving to be too terse in practice (in particular we'd like to include longer lists of the possible values etc which would easily blow 80 columns). Hence wrapping is now desired.

@duglin

This comment has been minimized.

Show comment
Hide comment
@duglin

duglin Jan 12, 2017

Contributor

this LGTM if we can get the vendor dependencies onto their master branches. I don't like the idea of pointing to someone's personal branch.

Contributor

duglin commented Jan 12, 2017

this LGTM if we can get the vendor dependencies onto their master branches. I don't like the idea of pointing to someone's personal branch.

@LK4D4

This comment has been minimized.

Show comment
Hide comment
@LK4D4

LK4D4 Jan 27, 2017

Contributor

I've pinged upstream dep maintainer.

Contributor

LK4D4 commented Jan 27, 2017

I've pinged upstream dep maintainer.

@LK4D4

This comment has been minimized.

Show comment
Hide comment
@LK4D4

LK4D4 Jan 30, 2017

Contributor

@ijc change was merged into upstream

Contributor

LK4D4 commented Jan 30, 2017

@ijc change was merged into upstream

@vdemeester

This comment has been minimized.

Show comment
Hide comment
@vdemeester

vdemeester Jan 31, 2017

Member

@ijc25 as @LK4D4 it's merged upstream, could you update the vendor ? 👼

Member

vdemeester commented Jan 31, 2017

@ijc25 as @LK4D4 it's merged upstream, could you update the vendor ? 👼

@ijc

This comment has been minimized.

Show comment
Hide comment
@ijc

ijc Jan 31, 2017

Contributor

Done.

Contributor

ijc commented Jan 31, 2017

Done.

@LK4D4

This comment has been minimized.

Show comment
Hide comment
@LK4D4

LK4D4 Jan 31, 2017

Contributor

@ijc25 Looks like CI passes. I would love to have squashed commits before merge.

Contributor

LK4D4 commented Jan 31, 2017

@ijc25 Looks like CI passes. I would love to have squashed commits before merge.

@thaJeztah

This comment has been minimized.

Show comment
Hide comment
@thaJeztah

thaJeztah Feb 1, 2017

Member

Oh, when squashing, please keep the vendor commit separate

Member

thaJeztah commented Feb 1, 2017

Oh, when squashing, please keep the vendor commit separate

@ijc

This comment has been minimized.

Show comment
Hide comment
@ijc

ijc Feb 1, 2017

Contributor

@thaJeztah if I'm going to squash then I think it would make sense to squash Revendor github.com/spf13/pflag to 9ff6c6923cfffbcd502984b8e0c80539a94968b7 into Wrap output of docker cli --help and remove the This temporarily revendors github.com/spf13/pflag from my fork paragraph from the commit message (esp given my branch was rebased by spf13/pflag so it is not the same literal commit any longer). WDYT?

Or perhaps folks would prefer the revendoring to spf13/pflag#master to be in Revendor github.com/spf13/pflag to 5ccb023bc27df288a957c5e994cd44fd19619465 (with suitably updated commit message) instead?

Contributor

ijc commented Feb 1, 2017

@thaJeztah if I'm going to squash then I think it would make sense to squash Revendor github.com/spf13/pflag to 9ff6c6923cfffbcd502984b8e0c80539a94968b7 into Wrap output of docker cli --help and remove the This temporarily revendors github.com/spf13/pflag from my fork paragraph from the commit message (esp given my branch was rebased by spf13/pflag so it is not the same literal commit any longer). WDYT?

Or perhaps folks would prefer the revendoring to spf13/pflag#master to be in Revendor github.com/spf13/pflag to 5ccb023bc27df288a957c5e994cd44fd19619465 (with suitably updated commit message) instead?

@LK4D4

This comment has been minimized.

Show comment
Hide comment
@LK4D4

LK4D4 Feb 1, 2017

Contributor

@ijc25 I'd propose you to make git reset to commit before your commits and then create one commit with vendor.conf and vendor and second with your changes.

Contributor

LK4D4 commented Feb 1, 2017

@ijc25 I'd propose you to make git reset to commit before your commits and then create one commit with vendor.conf and vendor and second with your changes.

@ijc

This comment has been minimized.

Show comment
Hide comment
@ijc

ijc Feb 1, 2017

Contributor

Squash done, but now it looks like I need to rebase...

Contributor

ijc commented Feb 1, 2017

Squash done, but now it looks like I need to rebase...

ijc added some commits Feb 1, 2017

Revendor github.com/spf13/pflag to 9ff6c6923cfffbcd502984b8e0c80539a9…
…4968b7

$ git log --oneline dabebe21bf79..9ff6c6923cff
9ff6c69 Add FlagSet.FlagUsagesWrapped(cols) which wraps to the given column (#105)
a9a634f Add BoolSlice and UintSlice flag types. (#111)
a232f6d Merge pull request #102 from bogem/redundant
5126803 Merge pull request #110 from hardikbagdi/master
230dccf add badges to README.md
c431975 Merge pull request #107 from xilabao/add-user-supplied-func-when-parse
271ea0e Make command line parsing available outside pflag
25f8b5b Merge pull request #109 from SinghamXiao/master
1fcda0c too many arguments
5ccb023 Remove Go 1.5 from Travis
86d3545 Clean up code

I am interested in 9ff6c69 for a followup.

Signed-off-by: Ian Campbell <ian.campbell@docker.com>
Wrap output of docker cli --help
This should go some way to unblocking a solution to #18797, #18385 etc by
removing the current rather restrictive constraints on help text length.

Signed-off-by: Ian Campbell <ian.campbell@docker.com>
@ijc

This comment has been minimized.

Show comment
Hide comment
@ijc

ijc Feb 3, 2017

Contributor

Rebased.

Contributor

ijc commented Feb 3, 2017

Rebased.

@thaJeztah

still LGTM

@thaJeztah thaJeztah merged commit fac13e4 into moby:master Feb 4, 2017

5 checks passed

dco-signed All commits are signed
experimental Jenkins build Docker-PRs-experimental 30318 has succeeded
Details
janky Jenkins build Docker-PRs 38932 has succeeded
Details
vendor Jenkins build Docker-PRs-vendor 2852 has succeeded
Details
windowsRS1 Jenkins build Docker-PRs-WoW-RS1 9981 has succeeded
Details

@GordonTheTurtle GordonTheTurtle added this to the 1.14.0 milestone Feb 4, 2017

dnephin pushed a commit to dnephin/docker that referenced this pull request Apr 17, 2017

Merge pull request moby#28751 from ijc25/wrap-help-output
Wrap CLI --help output to terminal width
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment