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

Jump to bottom
Merged
merged 1 commit into from
Aug 18, 2025
Merged

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

merged 1 commit into from
Aug 18, 2025

Conversation

@Raghul-M
Copy link
Contributor

@Raghul-M Raghul-M commented Aug 14, 2025 •
edited
Loading 

NONE

Does this PR introduce a user-facing change?

Fixes : #26353

Add comprehensive --format flag examples to man pages

This PR addresses issue #26353 by adding missing --format flag examples 
to the following man pages:

- podman-system-df.1.md
- podman-system-connection-list.1.md  
- podman-pod-inspect.1.md.in
- podman-machine-inspect.1.md
- podman-farm-list.1.md

Each man page now includes practical examples showing:
- JSON format output (--format json)
- Go template usage with single fields
- Multi-field Go templates with custom formatting
- Conditional templates and advanced usage

These examples provide users with copy-paste ready templates for common
formatting use cases and demonstrate the full capabilities of the --format
flag for each command.

Fixes : https://github.com/containers/podman/issues/26353

Signed-off-by: Raghul-M <raghul.m1430@gmail.com>

@Raghul-M
Copy link
Contributor Author

@Luap99 Can you Please Review and Approve it

@Raghul-M
Copy link
Contributor Author

@baude can you also review it

Honny1
Honny1 reviewed Aug 15, 2025
View reviewed changes
Copy link
Member

@Honny1 Honny1 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Once the CI tests pass. I have a suggestion on how to fix the issue.

docs/source/markdown/podman-machine-inspect.1.md Outdated
Show machine uptime information:
```
$ podman machine inspect --format "Created: {{.Created}}\nLast Up: {{.LastUp}}\nState: {{.State}}"
Created: 2025-02-11 14:12:48.231836 +0530 IST
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spell check is flagging IST. When I tried UTC instead, it worked. I'm not sure if there's a way to handle IST.

Suggested change
Created: 2025-02-11 14:12:48.231836 +0530 IST
Created: 2025-02-11 14:12:48.231836 +0530 UCT

Copy link
Contributor Author

@Raghul-M Raghul-M Aug 15, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah I changed to UTC

docs/source/markdown/podman-machine-inspect.1.md Outdated
```
$ podman machine inspect --format "Created: {{.Created}}\nLast Up: {{.LastUp}}\nState: {{.State}}"
Created: 2025-02-11 14:12:48.231836 +0530 IST
Last Up: 2025-08-12 19:31:19.391294 +0530 IST
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Last Up: 2025-08-12 19:31:19.391294 +0530 IST
Last Up: 2025-08-12 19:31:19.391294 +0530 UCT

@packit-as-a-service
Copy link

[NON-BLOCKING] Packit jobs failed. @containers/packit-build please check. Everyone else, feel free to ignore.

1 similar comment
@packit-as-a-service
Copy link

[NON-BLOCKING] Packit jobs failed. @containers/packit-build please check. Everyone else, feel free to ignore.

@Raghul-M
Copy link
Contributor Author

/assign @Luap99

Luap99
Luap99 requested changes Aug 15, 2025
View reviewed changes
Copy link
Member

@Luap99 Luap99 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, can you squash your commits into one please.
Also it would be great if you can add Fixes: #26353 into the commit message as well not just the PR description.

docs/source/markdown/podman-machine-inspect.1.md Outdated
Comment on lines 106 to 107
Created: 2025-02-11 14:12:48.231836 +0530 UTC
Last Up: 2025-08-12 19:31:19.391294 +0530 UTC
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

UTC makes no sense with the +0530 time offset. it would also need to show +0000 for actual UTC time.

docs/source/markdown/podman-pod-inspect.1.md.in Outdated
Show pod creation time and shared namespaces:
```
$ podman pod inspect mypod --format "Created: {{.Created}}\nShared: {{.SharedNamespaces}}"
Created: 2025-08-14 21:16:05.861363099 +0530 UTC
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same thing here

@Honny1
Copy link
Member

Honny1 commented Aug 15, 2025

Please also update the PR description with the following. I'm not sure if the entire PR description should be included in the release notes.

```release-note
NONE
```

@Raghul-M
Fixes: containers#26353
46ee62c 
Signed-off-by: Raghul-M <raghul.m1430@gmail.com>
@Raghul-M
Copy link
Contributor Author

Thanks, can you squash your commits into one please. Also it would be great if you can add Fixes: #26353 into the commit message as well not just the PR description.

Done

@Raghul-M
Copy link
Contributor Author

@Luap99 can you approve and merge this PR

Luap99
Luap99 approved these changes Aug 18, 2025
View reviewed changes
Copy link
Member

@Luap99 Luap99 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/lgtm

Thanks

@openshift-ci openshift-ci bot added the lgtm Indicates that a PR is ready to be merged. label Aug 18, 2025
@openshift-ci
Copy link
Contributor

openshift-ci bot commented Aug 18, 2025

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: Honny1, Luap99, Raghul-M

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@openshift-ci openshift-ci bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Aug 18, 2025
@openshift-merge-bot openshift-merge-bot bot merged commit e8a40a3 into containers:main Aug 18, 2025
38 of 40 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Honny1 Honny1 Honny1 approved these changes

@Luap99 Luap99 Luap99 approved these changes

Assignees

@Luap99 Luap99

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. lgtm Indicates that a PR is ready to be merged. release-note-none

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Manpages: Missing examples for the --format flag

3 participants

@Raghul-M @Honny1 @Luap99