Skip to content

docs: Add --format flag examples to commands in man pages #26825

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

Merged
merged 1 commit into from
Aug 18, 2025
Merged

docs: Add --format flag examples to commands in man pages #26825

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
38 changes: 38 additions & 0 deletions docs/source/markdown/podman-farm-list.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,45 @@ Name Connections Default ReadWrite
farm1 [f38 f37] false true
farm2 [f37] true true
```
Show farms in JSON format:
```
$ podman farm list --format json
[
{
"Name": "farm1",
"Connections": [
"f38",
"f37"
],
"Default": false,
"ReadWrite": true
},
{
"Name": "farm2",
"Connections": [
"f37"
],
"Default": true,
"ReadWrite": true
}
]
```

Show only farm names:
```
$ podman farm list --format "{{.Name}}"
farm1
farm2
```

Show detailed farm information:
```
$ podman farm list --format "Farm: {{.Name}} (Default: {{.Default}}, ReadWrite: {{.ReadWrite}})\nConnections: {{.Connections}}"
Farm: farm1 (Default: false, ReadWrite: true)
Connections: [f38 f37]
Farm: farm2 (Default: true, ReadWrite: true)
Connections: [f37]
```
## SEE ALSO
**[podman(1)](podman.1.md)**, **[podman-farm(1)](podman-farm.1.md)**

Expand Down
67 changes: 67 additions & 0 deletions docs/source/markdown/podman-machine-inspect.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,73 @@ Print usage statement.
Inspect the specified Podman machine.
```
$ podman machine inspect podman-machine-default
[
{
"ConfigDir": {
"Path": "/Users/jacksparrow/.config/containers/podman/machine/applehv"
},
"ConnectionInfo": {
"PodmanSocket": {
"Path": "/var/folders/9r/n3056v597wv2cq8s2j80bdnw0000gn/T/podman/podman-machine-default-api.sock"
},
"PodmanPipe": null
},
"Created": "2025-02-11T14:12:48.231836+05:30",
"LastUp": "2025-08-12T19:31:19.391294+05:30",
"Name": "podman-machine-default",
"Resources": {
"CPUs": 6,
"DiskSize": 100,
"Memory": 6144,
"USBs": []
},
"SSHConfig": {
"IdentityPath": "/Users/jacksparrow/.local/share/containers/podman/machine/machine",
"Port": 53298,
"RemoteUsername": "core"
},
"State": "running",
"UserModeNetworking": true,
"Rootful": false,
"Rosetta": true
}
]
```

Show machine name and state:
```
$ podman machine inspect --format "{{.Name}}\t{{.State}}"
podman-machine-default running
```

Show machine resource information:
```
$ podman machine inspect --format "Machine: {{.Name}}\nCPUs: {{.Resources.CPUs}}\nMemory: {{.Resources.Memory}} bytes\nDisk: {{.Resources.DiskSize}} bytes"
Machine: podman-machine-default
CPUs: 6
Memory: 6144 bytes
Disk: 100 bytes
```

Show machine configuration details:
```
$ podman machine inspect --format "{{.Name}}: {{.State}} (Rootful: {{.Rootful}}, User Networking: {{.UserModeNetworking}})"
podman-machine-default: running (Rootful: false, User Networking: true)
```

Show machine uptime information:
```
$ podman machine inspect --format "Created: {{.Created}}\nLast Up: {{.LastUp}}\nState: {{.State}}"
Created: 2025-02-11 14:12:48.231836 +0000 UTC
Last Up: 2025-08-12 19:31:19.391294 +0000 UTC
State: running
```

Show connection information:
```
$ podman machine inspect --format "Socket: {{.ConnectionInfo.PodmanSocket}}\nConfig Dir: {{.ConfigDir}}"
Socket: {/var/folders/9r/n3056v597wv2cq8s2j80bdnw0000gn/T/podman/podman-machine-default-api.sock <nil>}
Config Dir: {/Users/jacksparrow/.config/containers/podman/machine/applehv <nil>}
```

## SEE ALSO
Expand Down
31 changes: 30 additions & 1 deletion docs/source/markdown/podman-pod-inspect.1.md.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ Valid placeholders for the Go template are listed below:

Inspect specified pod:
```
# podman pod inspect foobar
$ podman pod inspect foobar
[
{
"Id": "3513ca70583dd7ef2bac83331350f6b6c47d7b4e526c908e49d89ebf720e4693",
Expand Down Expand Up @@ -91,6 +91,35 @@ Inspect specified pod:
}
]
```
Show only pod name and state:
```
$ podman pod inspect --format "{{.Name}}\t{{.State}}" mypod
mypod Running
```

Show pod ID and number of containers:
```
$ podman pod inspect mypod --format "Pod {{.Name}} ({{.ID}}) has {{.NumContainers}} containers"
Pod mypod (605f5f776e101a6e0ad11ea802cae25eabf299da77122f2963fa65dc6ccf6717) has 2 containers
```
Show pod creation time and shared namespaces:
```
$ podman pod inspect mypod --format "Created: {{.Created}}\nShared: {{.SharedNamespaces}}"
Created: 2025-08-14 21:16:05.861363099 +0000 UTC
Shared: [net uts ipc]
```

Show pod resource limits:
```
$ podman pod inspect --format "Memory: {{.MemoryLimit}}, CPU Period: {{.CPUPeriod}}, CPU Quota: {{.CPUQuota}}" mypod
Memory: 1073741824, CPU Period: 100000, CPU Quota: 50000
```

Show container IDs within the pod:
```
$ podman pod inspect --format "{{range .Containers}}{{.Id}}: {{.State}} {{end}}" mypod
e907f7902decca9d6b600b4d3cca9541d9b89dd726b2af7ad2eba05d2a97083f: running c5a53050a31aed71c55cb6a31b9564c69a1009f77750f3f0e8093bd98fcd8918: running
```

## SEE ALSO
**[podman(1)](podman.1.md)**, **[podman-pod(1)](podman-pod.1.md)**, **[podman-inspect(1)](podman-inspect.1.md)**
Expand Down
44 changes: 44 additions & 0 deletions docs/source/markdown/podman-system-connection-list.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,50 @@ Name URI Identity Defau
deva ssh://root@example.com:/run/podman/podman.sock ~/.ssh/id_rsa true true
devb ssh://user@example.com:/run/user/1000/podman/podman.sock ~/.ssh/id_rsa false true
```
Show connections in JSON format:
```
$ podman system connection list --format json
[
{
"Name": "podman-machine-default",
"URI": "ssh://core@127.0.0.1:53298/run/user/501/podman/podman.sock",
"Identity": "/Users/ragm/.local/share/containers/podman/machine/machine",
"IsMachine": true,
"Default": true,
"ReadWrite": true
},
{
"Name": "podman-machine-default-root",
"URI": "ssh://root@127.0.0.1:53298/run/podman/podman.sock",
"Identity": "/Users/ragm/.local/share/containers/podman/machine/machine",
"IsMachine": true,
"Default": false,
"ReadWrite": true
}
]
```
Show connection names and URIs:
```
$ podman system connection list --format "{{.Name}}\t{{.URI}}"
podman-machine-default ssh://core@127.0.0.1:53298/run/user/501/podman/podman.sock
podman-machine-default-root ssh://root@127.0.0.1:53298/run/podman/podman.sock
```
Show all connection details in a comprehensive format:
```
$ podman system connection list --format "Name: {{.Name}}\nURI: {{.URI}}\nIdentity: {{.Identity}}\nDefault: {{.Default}}\nReadWrite: {{.ReadWrite}}\n---"
Name: podman-machine-default
URI: ssh://core@127.0.0.1:53298/run/user/501/podman/podman.sock
Identity: /Users/ragm/.local/share/containers/podman/machine/machine
Default: true
ReadWrite: true
---
Name: podman-machine-default-root
URI: ssh://root@127.0.0.1:53298/run/podman/podman.sock
Identity: /Users/ragm/.local/share/containers/podman/machine/machine
Default: false
ReadWrite: true
---
```
## SEE ALSO
**[podman(1)](podman.1.md)**, **[podman-system(1)](podman-system.1.md)**, **[podman-system-connection(1)](podman-system-connection.1.md)**

Expand Down
22 changes: 22 additions & 0 deletions docs/source/markdown/podman-system-df.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,12 +66,34 @@ Local Volumes space usage:

VOLUME NAME LINKS SIZE
data 1 0B
```

Show only the total count for each type:
```
$ podman system df --format "{{.Type}}\t{{.Total}}"
Images 1
Containers 5
Local Volumes 1
```
Show disk usage in JSON format:
```
$ podman system df --format json
[
{"Type":"Images","Total":12,"Active":3,"RawSize":13491151377,"RawReclaimable":922956674,"TotalCount":12,"Size":"13.49GB","Reclaimable":"923MB (7%)"},
{"Type":"Containers","Total":4,"Active":0,"RawSize":209266,"RawReclaimable":209266,"TotalCount":4,"Size":"209.3kB","Reclaimable":"209.3kB (100%)"},
{"Type":"Local Volumes","Total":6,"Active":1,"RawSize":796638905,"RawReclaimable":47800633,"TotalCount":6,"Size":"796.6MB","Reclaimable":"47.8MB (6%)"}
]
```
Show type and size in a custom format:
```
$ podman system df --format "{{.Type}}: {{.Size}} ({{.Reclaimable}} reclaimable)"

Images: 13.49GB (923MB (7%) reclaimable)
Containers: 209.3kB (209.3kB (100%) reclaimable)
Local Volumes: 796.6MB (47.8MB (6%) reclaimable)
```


## SEE ALSO
**[podman(1)](podman.1.md)**, **[podman-system(1)](podman-system.1.md)**

Expand Down