[Docs]: Please include trivial example for use of Format String

[stellarpower]

Feature request description

Please could the man pages for commands that include a format option include a very brief example of how these templates work? A single one-line "e.g. --format='{{.Name}}:{{.Tag}}'" in this section of the manual would do IMO. Options discussed below.

Not being a go user, the format {{.Tag}} is not obvious to me (looking like a half mix of JSON and liquid tags and with LeadingCamelCase - so a few things that I wouldn;t try off the top of my head all together), and as I have a really large graphroot on this machine, I wasted some amount of time sitting waiting for it to run, only having the string '.Tag' printed out to me many times!

Suggest potential solution

Options:

Man page sections on format flags:

• have a quick example above or below the table of all supported template tags, or
• link through to a more detailed page describing how the format argument works.

Have you considered any alternatives?

No response

Additional context

No response

[stellarpower]

Related: #17472

[rhatdan]

Interested in opening a PR with this change? We have examples in these man pages correct?

[Luap99]

Yes AFAIK we have examples at the bottom on most pages and also --help, but I agree that some docs actually describing how templates work would help, possibly just linking to the go docs, https://pkg.go.dev/text/template

Also FYI you use shell completion in templates to retrieve the names:

podman images --format {{.[TAB]
{{.Containers}}    {{.CreatedSince}}  {{.Digest}}        {{.ID}}            {{.IsReadOnly}}    {{.ParentId}}      {{.Repository}}    {{.Size}}          
{{.Created}}       {{.CreatedTime}}   {{.History}}       {{.ImageSummary.   {{.Labels.         {{.ReadOnly}}      {{.RepoTags}}      {{.Tag}}           
{{.CreatedAt}}     {{.Dangling}}      {{.Id}}            {{.IsDangling}}    {{.Names}}         {{.RepoDigests}}   {{.SharedSize}}    {{.VirtualSize}} 

[stellarpower]

Thanks, yeah, only after opening this I saw it staring me in the face when I did podman images --help. Sure it's all in there, but being generally familiar with podman, the first place I would go to is the section documenting the particular flag (i.e. --format). I also ignored the overall help as it's a flag that applies across multiple commands, so was expecting it to be documented somewhere common or, expanded on in the options. The table is listed there and that's great, so I believe a quick example there just for reference on how it's used, and/or a full page on how it works with more sexy stuff you can do would be sensible. The --format flag is also where google landed me, multiple times, so in the end I had to search for how to do it in Docker to find some tutorial that worked it out. From memory this has happened a couple of times, hence opening this if others could benefit too.

Also interesting on the tab-completion. Although I'm on fish/nushell and don't get this (or any other tab completions usually, they tend to do more harm than good I find!) on either of those.

Conceptually happy to open a PR, except I'm super busy at the moment and am not really finding time ot follow up on anything am afraid ;)

[Luap99]

Tab completion should work on bash, zsh, fish and powershell assuming you have loaded the completion scripts, we use https://github.com/spf13/cobra to generate them. I tried it with fish and it seems to escape the closing brackets so it is not fully usable but still show the names:

podman images --format {{.Containers\}\} 
{{.Containers}}    {{.Created}}   {{.ID}}           {{.IsReadOnly}}  {{.ReadOnly}}     {{.SharedSize}} 
{{.CreatedAt}}     {{.Dangling}}  {{.Id}}           {{.Labels.       {{.RepoDigests}}  {{.Size}}       
{{.CreatedSince}}  {{.Digest}}    {{.ImageSummary.  {{.Names}}       {{.Repository}}   {{.Tag}}        
{{.CreatedTime}}   {{.History}}   {{.IsDangling}}   {{.ParentId}}    {{.RepoTags}}     {{.VirtualSize}}

So this is likely something that we should report to the cobra project.

[stellarpower]

I wasn't getting anything but files in the PWD, but possibly my fish is not set up properly or a bit old. So I think that is a good idea.

[ibotty]

The completion only triggers with podman images for me, not with podman inspect. Is that expected?

[Luap99]

Yes I excluded podman inspect because it accepts many different types (container, image, pod, network, volume) so it is not clear what to complete for this command.
podman container inspect or podman image inspect should work

[github-actions]

A friendly reminder that this issue had no activity for 30 days.

[rhatdan]

We believe this works in the current code base, closing. reopen if I am mistaken.