oc CMD --help output unreadable and confusing

[jmrodri]

When using the --help option on with oc and any of the subcommands, the output is very hard to read. It is difficult to discern the options from parts of the paragraph text. This is different from many other command line tools where the options are clearly laid out.

Version

$ oc version
oc v3.6.170
kubernetes v1.6.1+5115d708d7
features: Basic-Auth GSSAPI Kerberos SPNEGO

Server https://172.17.0.1:8443
kubernetes v1.6.1+5115d708d7

Steps To Reproduce

1. oc get --help or oc process --help, all subcommands are similar.
2. observe the confusing list of options.

Current Result

Notice how the options are mushed together it's hard to discern if --output-version is its own option to oc process or part of the -o, --output option.

$ oc get --help
Display one or many resources 

Possible resources include builds, buildConfigs, services, pods, etc. To see a
list of common resources, use 'oc get'. Some resources may omit advanced details
that you can see with '-o wide'.  If you want an even more detailed view, use
'oc describe'.

Usage:
  oc get
[(-o|--output=)json|yaml|wide|custom-columns=...|custom-columns-file=...|go-template=...|go-template-file=...|jsonpath=...|jsonpath-file=...]
(TYPE [NAME | -l label] | TYPE/NAME ...) [flags] [options]

Examples:
  # List all pods in ps output format.
  oc get pods
  
  # List a single replication controller with specified ID in ps output format.
  oc get rc redis
  
  # List all pods and show more details about them.
  oc get -o wide pods
  
  # List a single pod in JSON output format.
  oc get -o json pod redis-pod
  
  # Return only the status value of the specified pod.
  oc get -o template pod redis-pod --template={{.currentState.status}}

Options:
      --all-namespaces=false: If present, list the requested object(s) across
all namespaces. Namespace in current context is ignored even if specified with
--namespace.
      --allow-missing-template-keys=true: If true, ignore any errors in
templates when a field or map key is missing in the template. Only applies to
golang and jsonpath output formats.
      --export=false: If true, use 'export' for the resources.  Exported
resources are stripped of cluster-specific information.
  -f, --filename=[]: Filename, directory, or URL to files identifying the
resource to get from a server.
      --ignore-not-found=false: Treat "resource not found" as a successful
retrieval.
      --include-extended-apis=true: If true, include definitions of new APIs via
calls to the API server. [default true]
  -L, --label-columns=[]: Accepts a comma separated list of labels that are
going to be presented as columns. Names are case-sensitive. You can also use
multiple flag options like -L label1 -L label2...
      --no-headers=false: When using the default or custom-column output format,
don't print headers (default print headers).
  -o, --output='': Output format. One of:
json|yaml|wide|name|custom-columns=...|custom-columns-file=...|go-template=...|go-template-file=...|jsonpath=...|jsonpath-file=...
See custom columns
[http://kubernetes.io/docs/user-guide/kubectl-overview/#custom-columns], golang
template [http://golang.org/pkg/text/template/#pkg-overview] and jsonpath
template [http://kubernetes.io/docs/user-guide/jsonpath].
      --raw='': Raw URI to request from the server.  Uses the transport
specified by the kubeconfig file.
  -R, --recursive=false: Process the directory used in -f, --filename
recursively. Useful when you want to manage related manifests organized within
the same directory.
  -l, --selector='': Selector (label query) to filter on, supports '=', '==',
and '!='.
  -a, --show-all=true: When printing, show all resources (false means hide
terminated pods.)
      --show-kind=false: If present, list the resource type for the requested
object(s).
      --show-labels=false: When printing, show all labels as the last column
(default hide labels column)
      --sort-by='': If non-empty, sort list types using this field
specification.  The field specification is expressed as a JSONPath expression
(e.g. '{.metadata.name}'). The field in the API resource specified by this
JSONPath expression must be an integer or a string.
      --template='': Template string or path to template file to use when
-o=go-template, -o=go-template-file. The template format is golang templates
[http://golang.org/pkg/text/template/#pkg-overview].
  -w, --watch=false: After listing/getting the requested object, watch for
changes.
      --watch-only=false: Watch for changes to the requested object(s), without
listing/getting first.

Use "oc options" for a list of global command-line options (applies to all
commands).

$ oc process --help
Process template into a list of resources specified in filename or stdin 

Templates allow parameterization of resources prior to being sent to the server
for creation or update. Templates have "parameters", which may either be
generated on creation or set by the user, as well as metadata describing the
template. 

The output of the process command is always a list of one or more resources. You
may pipe the output to the create command over STDIN (using the '-f -' option)
or redirect it to a file. 

Process resolves the template on the server, but you may pass --local to
parameterize the template locally. When running locally be aware that the
version of your client tools will determine what template transformations are
supported, rather than the server.

Usage:
  oc process (TEMPLATE | -f FILENAME) [-p=KEY=VALUE] [options]

Examples:
  # Convert template.json file into resource list and pass to create
  oc process -f template.json | oc create -f -
  
  # Process a file locally instead of contacting the server
  oc process -f template.json --local -o yaml
  
  # Process template while passing a user-defined label
  oc process -f template.json -l name=mytemplate
  
  # Convert stored template into resource list
  oc process foo
  
  # Convert stored template into resource list by setting/overriding parameter
values
  oc process foo PARM1=VALUE1 PARM2=VALUE2
  
  # Convert template stored in different namespace into a resource list
  oc process openshift//foo
  
  # Convert template.json into resource list
  cat template.json | oc process -f -

Options:
  -f, --filename='': Filename or URL to file to read a template
  -l, --labels='': Label to set in all resources for this template
      --local=false: If true process the template locally instead of contacting
the server.
  -o, --output='json': Output format. One of:
describe|json|yaml|name|go-template=...|go-template-file=...|jsonpath=...|jsonpath-file=...
      --output-version='': Output the formatted object with the given version
(default api-version).
  -p, --param=[]: Specify a key-value pair (eg. -p FOO=BAR) to set/override a
parameter value in the template.
      --param-file=[]: File containing template parameter values to set/override
in the template.
      --parameters=false: If true, do not process but only print available
parameters
      --raw=false: If true, output the processed template instead of the
template's objects. Implied by -o describe
  -t, --template='': Template string or path to template file to use when
-o=go-template, -o=go-templatefile.  The template format is golang templates
[http://golang.org/pkg/text/template/#pkg-overview]

Use "oc options" for a list of global command-line options (applies to all
commands).

Expected Result

Here are the expected formatting for oc process --help. Notice how the options are aligned and the description is clearly set apart. Options that require a specific set of input are denoted at the bottom like FORMAT

$ oc process --help
Process template into a list of resources specified in filename or stdin

Templates allow parameterization of resources prior to being sent to the server
for creation or update. Templates have "parameters", which may either be
generated on creation or set by the user, as well as metadata describing the
template.

The output of the process command is always a list of one or more resources. You
may pipe the output to the create command over STDIN (using the '-f -' option)
or redirect it to a file.

Process resolves the template on the server, but you may pass --local to
parameterize the template locally. When running locally be aware that the
version of your client tools will determine what template transformations are
supported, rather than the server.

Usage:
  oc process (TEMPLATE | -f FILENAME) [-p=KEY=VALUE] [options]

Examples:
  # Convert template.json file into resource list and pass to create
  oc process -f template.json | oc create -f -

  # Process a file locally instead of contacting the server
  oc process -f template.json --local -o yaml

  # Process template while passing a user-defined label
  oc process -f template.json -l name=mytemplate

  # Convert stored template into resource list
  oc process foo

  # Convert stored template into resource list by setting/overriding parameter
values
  oc process foo PARM1=VALUE1 PARM2=VALUE2

  # Convert template stored in different namespace into a resource list
  oc process openshift//foo

  # Convert template.json into resource list
  cat template.json | oc process -f -

Options:
  -f, --filename=''         Filename or URL to file to read a template
  -l, --labels=''           Label to set in all resources for this template
      --local=false         If true process the template locally instead of contacting the server.
  -o, --output=FORMAT       Output format. See FORMAT below.
      --output-version=''   Output the formatted object with the given version (default api-version).
  -p, --param=[]            A key-value pair (eg. -p FOO=BAR) to set/override a parameter
                            value in the template.
      --param-file=[]       File containing template parameter values to set/override in
                            the template.
      --parameters=false    If true, do not process but only print available parameters
      --raw=false           If true, output the processed template instead of the
                            template's objects. Implied by -o describe
  -t, --template=GOTEMPLATE Template string or path to template file to use when
                            -o=go-template, -o=go-templatefile.

The FORMAT argument is a string. Formats are: describe|json|yaml|name|go-template=...|go-template-file=...|jsonpath=...|jsonpath-file=...
The GOTEMPLATE a golang template [http://golang.org/pkg/text/template/#pkg-overview]

Use "oc options" for a list of global command-line options (applies to all
commands).

Additional Information

Here are 2 other examples: ls --help and docker build --help

$ ls --help
Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.

Mandatory arguments to long options are mandatory for short options too.
  -a, --all                  do not ignore entries starting with .
  -A, --almost-all           do not list implied . and ..
      --author               with -l, print the author of each file
  -b, --escape               print C-style escapes for nongraphic characters
      --block-size=SIZE      scale sizes by SIZE before printing them; e.g.,
                               '--block-size=M' prints sizes in units of
                               1,048,576 bytes; see SIZE format below
  -B, --ignore-backups       do not list implied entries ending with ~
  -c                         with -lt: sort by, and show, ctime (time of last
                               modification of file status information);
                               with -l: show ctime and sort by name;
                               otherwise: sort by ctime, newest first
  -C                         list entries by columns
      --color[=WHEN]         colorize the output; WHEN can be 'always' (default
                               if omitted), 'auto', or 'never'; more info below
...

The SIZE argument is an integer and optional unit (example: 10K is 10*1024).
Units are K,M,G,T,P,E,Z,Y (powers of 1024) or KB,MB,... (powers of 1000).

Using color to distinguish file types is disabled both by default and
...

docker build has a lovely and clean list of parameters. Easy to understand what they do.

$ docker build --help

Usage:	docker build [OPTIONS] PATH | URL | -

Build an image from a Dockerfile

Options:
      --build-arg list             Set build-time variables (default [])
      --cache-from stringSlice     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
      --cpu-quota int              Limit the CPU CFS (Completely Fair Scheduler) quota
  -c, --cpu-shares int             CPU shares (relative weight)
      --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')
      --force-rm                   Always remove intermediate containers
      --help                       Print usage
      --isolation string           Container isolation technology
      --label list                 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
      --network string             Set the networking mode for the RUN instructions during build (default "default")
      --no-cache                   Do not use cache when building the image
      --pull                       Always attempt to pull a newer version of the image
  -q, --quiet                      Suppress the build output and print image ID on success
      --rm                         Remove intermediate containers after a successful build (default true)
      --security-opt stringSlice   Security options
      --shm-size string            Size of /dev/shm, default value is 64MB
  -t, --tag list                   Name and optionally a tag in the 'name:tag' format (default [])
      --ulimit ulimit              Ulimit options (default [])
  -v, --volume list                Set build-time bind mounts (default [])

[smarterclayton]

Cobra needs to better handle wrapping at terminal width boundaries.

[openshift-bot]

Issues go stale after 90d of inactivity.

Mark the issue as fresh by commenting /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
Exclude this issue from closing by commenting /lifecycle frozen.

If this issue is safe to close now please do so with /close.

/lifecycle stale

[openshift-bot]

Stale issues rot after 30d of inactivity.

Mark the issue as fresh by commenting /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.
Exclude this issue from closing by commenting /lifecycle frozen.

If this issue is safe to close now please do so with /close.

/lifecycle rotten
/remove-lifecycle stale

[openshift-bot]

Rotten issues close after 30d of inactivity.

Reopen the issue by commenting /reopen.
Mark the issue as fresh by commenting /remove-lifecycle rotten.
Exclude this issue from closing again by commenting /lifecycle frozen.

/close

[lousyd]

/reopen ... This is frustrating. Also, many other programs whose maintainers have had time to get this right put "Examples" at the end. Maybe writing some man pages for oc would be an easy way to fix this, a la man git, man git-fetch, etc.