docker / docker/cli

Implement or add documentation about `docker system df --format`

Open
#3,749 5 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

kind/docs kind/enhancement
Dominant language
Go
Stars
6.1k
Forks
2.2k
Avg merge
1d 15h
Merged PRs (30d)
43

Description

Description

docker system df --help shows that there is a --format option:

$ docker system df --help

Usage:  docker system df [OPTIONS]

Show docker disk usage

Options:
      --format string   Pretty-print images using a Go template
  -v, --verbose         Show detailed information on space usage

There is no documentation about how to use this option though, and snips copied from the source code also do not work.

Reproduce
  1. run docker system df --format='{{.ID}}'
  2. Observe the following error: Template parsing error: template: :1:2: executing "" at <.ID>: can't evaluate field ID in type *formatter.diskUsageImagesContext
  3. Try any other template string you can find or come up with, and observe a similar error.
Expected behavior

It is expected that options shown in the help text will work.

It is expected that when a format string is available, the variables that can be interpolated into that format string are described in documentation, and/or listed in the man page or other official documentation. EG: man stat, man date

Extra credit for having useful examples in documentation. EG in both of the above links.

docker version
Client:
 Version:           20.10.3
 API version:       1.41
 Go version:        go1.13.5
 Git commit:        48d30b5b32
 Built:             Sun Apr 24 16:58:20 2022
 OS/Arch:           linux/amd64
 Context:           default
 Experimental:      true

Server:
 Engine:
  Version:          20.10.3
  API version:      1.41 (minimum version 1.12)
  Go version:       go1.13.5
  Git commit:       46229ca1d8
  Built:            Sun Apr 24 17:35:06 2022
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.4.13
  GitCommit:        9cc61520f4cd876b86e77edfeb88fbcd536d1f9d
 runc:
  Version:          1.0.3
  GitCommit:        f46b6ba2c9314cfc8caae24a32ec5fe9ef1059fe
 docker-init:
  Version:          0.19.0
  GitCommit:        fec3683b971d9c3ef73f284f176672c44b448662
docker info
Client:
 Context:    default
 Debug Mode: false

Server:
 Containers: 137
  Running: 108
  Paused: 0
  Stopped: 29
 Images: 343
 Server Version: 20.10.3
 Storage Driver: overlay2
  Backing Filesystem: extfs
  Supports d_type: true
  Native Overlay Diff: true
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 Cgroup Version: 1
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local logentries splunk syslog
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 io.containerd.runtime.v1.linux runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 9cc61520f4cd876b86e77edfeb88fbcd536d1f9d
 runc version: f46b6ba2c9314cfc8caae24a32ec5fe9ef1059fe
 init version: fec3683b971d9c3ef73f284f176672c44b448662 (expected: de40ad007797e0dcd8b7126f27bb87401d224240)
 Security Options:
  apparmor
  seccomp
   Profile: default
 Kernel Version: 5.4.188+
 Operating System: Container-Optimized OS from Google
 OSType: linux
 Architecture: x86_64
 CPUs: 32
 Total Memory: 117.9GiB
 Name: gke-prod-cluster-terraform-2020043023-58a857b0-5rnc
 ID: 3E22:KMVD:SETY:3MQU:QZA7:OIFU:SS54:RLIT:B4SV:UTNT:VE66:4SGN
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 Registry: https://index.docker.io/v1/
 Labels:
 Experimental: false
 Insecure Registries:
  10.0.0.0/8
  127.0.0.0/8
 Registry Mirrors:
  https://mirror.gcr.io/
 Live Restore Enabled: true

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by running the reported docker system df --format='{{.ID}}' reproduction, then inspect cli/command/formatter/disk_usage.go, the source location named in the issue. Done means the advertised format option works and its supported variables and useful examples are documented in official Docker CLI documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, go
Domain
cli, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.