From d6cc8d29ab538a9f1cccc61e79b1691d916e3261 Mon Sep 17 00:00:00 2001 From: Dean Chen <862469039@qq.com> Date: Thu, 30 Jul 2026 18:39:51 +0500 Subject: [PATCH] docs: clarify docker system df --format placeholders Document summary-row fields (including Build Cache) and call out that image/container style placeholders like .ID are not valid for the non-verbose formatter. Fixes #3749 Signed-off-by: Dean Chen <862469039@qq.com> --- docs/reference/commandline/system_df.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/reference/commandline/system_df.md b/docs/reference/commandline/system_df.md index 1bb561b0a398..fb81f76b2e25 100644 --- a/docs/reference/commandline/system_df.md +++ b/docs/reference/commandline/system_df.md @@ -76,18 +76,24 @@ in systems where performance is critical. ### Format the output (--format) -The formatting option (`--format`) pretty prints the disk usage output -using a Go template. +The formatting option (`--format`) pretty prints the **summary** disk usage +output using a Go template. Each summary line (Images, Containers, Local +Volumes, and Build Cache) is rendered once with the same template. Valid placeholders for the Go template are listed below: -| Placeholder | Description | -|----------------|--------------------------------------------| -| `.Type` | `Images`, `Containers` and `Local Volumes` | -| `.TotalCount` | Total number of items | -| `.Active` | Number of active items | -| `.Size` | Available size | -| `.Reclaimable` | Reclaimable size | +| Placeholder | Description | +|----------------|-----------------------------------------------------------------------------| +| `.Type` | Resource kind: `Images`, `Containers`, `Local Volumes`, or `Build Cache` | +| `.TotalCount` | Total number of items of that type | +| `.Active` | Number of active items | +| `.Size` | Total size | +| `.Reclaimable` | Size that can be reclaimed (may include a percentage) | + +These placeholders describe the **summary** rows only. Fields such as +`.ID`, `.Repository`, or `.Names` are not valid here (those apply to +commands like `docker image ls` or to `docker system df --verbose`, +which does not use `--format`). When using the `--format` option, the `system df` command outputs the data exactly as the template declares or, when using the