man pages: docker differences

[edsantiago]

Per request from @rhatdan I ran the man-page xref script against moby-engine. Here are the results, comparing to main @ 72d13c5:

# PODMAN=/usr/bin/docker hack/xref-helpmsgs-manpages 2>&1 | grep -v 'but not --help'

• 'docker --help' lists '--config', which is not in docs/source/markdown/podman.1.md #Hidden
• 'docker --help' lists '--context', which is not in docs/source/markdown/podman.1.md #Hidden
• 'docker --help' lists '--debug', which is not in docs/source/markdown/podman.1.md # Hidden
• 'docker --help' lists '--host', which is not in docs/source/markdown/podman.1.md # Hidden
• 'docker --help' lists '--tls', which is not in docs/source/markdown/podman.1.md
• 'docker --help' lists '--tlscacert', which is not in docs/source/markdown/podman.1.md
• 'docker --help' lists '--tlscert', which is not in docs/source/markdown/podman.1.md
• 'docker --help' lists '--tlskey', which is not in docs/source/markdown/podman.1.md
• 'docker --help' lists '--tlsverify', which is not in docs/source/markdown/podman.1.md
• 'docker --help' lists '-D', which is not in docs/source/markdown/podman.1.md
• 'docker --help' lists '-H', which is not in docs/source/markdown/podman.1.md # Hidden
• [N/A] 'docker --help' lists '-l', which is not in docs/source/markdown/podman.1.md # Can't Support
• 'docker cp --help' lists '--follow-link', which is not in docs/source/markdown/podman-cp.1.md
• 'docker cp --help' lists '-L', which is not in docs/source/markdown/podman-cp.1.md
• 'docker create --help' lists '--dns-option', which is not in docs/source/markdown/podman-create.1.md
• 'docker create --help' lists '--domainname', which is not in docs/source/markdown/podman-create.1.md
• 'docker create --help' lists '--gpus', which is not in docs/source/markdown/podman-create.1.md # Hidden
• 'docker create --help' lists '--isolation', which is not in docs/source/markdown/podman-create.1.md
• 'docker create --help' lists '--kernel-memory', which is not in docs/source/markdown/podman-create.1.md #Hidden
• [N/A] 'docker create --help' lists '--link', which is not in docs/source/markdown/podman-create.1.md # Won't Support
• 'docker create --help' lists '--link-local-ip', which is not in docs/source/markdown/podman-create.1.md
• 'docker create --help' lists '--runtime', which is not in docs/source/markdown/podman-create.1.md # Only supported before command
• 'docker create --help' lists '--storage-opt', which is not in docs/source/markdown/podman-create.1.md # Only supported before command
• 'docker create --help' lists '--volume-driver', which is not in docs/source/markdown/podman-create.1.md
• 'docker create --help' lists '-c', which is not in docs/source/markdown/podman-create.1.md
• 'docker events --help' lists '-f', which is not in docs/source/markdown/podman-events.1.md
• 'docker import --help' lists '--platform', which is not in docs/source/markdown/podman-import.1.md
• 'docker logs --help' lists '--details', which is not in docs/source/markdown/podman-logs.1.md #Hidden
• 'docker pull --help' lists '-a', which is not in docs/source/markdown/podman-pull.1.md
• 'docker push --help' lists '--all-tags', which is not in docs/source/markdown/podman-push.1.md
• 'docker push --help' lists '-a', which is not in docs/source/markdown/podman-push.1.md
• [N/A] 'docker rm --help' lists '--link', which is not in docs/source/markdown/podman-rm.1.md # Won't Support
• 'docker rmi --help' lists '--no-prune', which is not in docs/source/markdown/podman-rmi.1.md
• 'docker run --help' lists '--dns-option', which is not in docs/source/markdown/podman-run.1.md # Hidden
• 'docker run --help' lists '--domainname', which is not in docs/source/markdown/podman-run.1.md
• 'docker run --help' lists '--gpus', which is not in docs/source/markdown/podman-run.1.md # Hidden
• [N/A ] 'docker run --help' lists '--isolation', which is not in docs/source/markdown/podman-run.1.md # Only used for Windows Containers which Podman does not support.
• 'docker run --help' lists '--kernel-memory', which is not in docs/source/markdown/podman-run.1.md #Hidden
• [N/A] 'docker run --help' lists '--link', which is not in docs/source/markdown/podman-run.1.md # Won't Support
• 'docker run --help' lists '--link-local-ip', which is not in docs/source/markdown/podman-run.1.md
• 'docker run --help' lists '--runtime', which is not in docs/source/markdown/podman-run.1.md # Only supported before command
• 'docker run --help' lists '--storage-opt', which is not in docs/source/markdown/podman-run.1.md # Only supported before command
• 'docker run --help' lists '--volume-driver', which is not in docs/source/markdown/podman-run.1.md
• 'docker run --help' lists '-c', which is not in docs/source/markdown/podman-run.1.md
• 'docker stats --help' lists '--no-trunc', which is not in docs/source/markdown/podman-stats.1.md
• 'docker --help' lists 'update', which is not in docs/source/markdown/podman.1.md
• 'docker version --help' lists '--kubeconfig', which is not in docs/source/markdown/podman-version.1.md
• docker manifest create --insecure #Hidden
• docker manifest create -a
• docker manifest inspect --insecure #hidden
• docker manifest inspect --verbose #hidden
• [N/A] docker manifest inspect -v : Conflicts with podman -v option
• docker manifest push --insecure #hidden
• docker manifest push --purge
• docker manifest push -p
• docker network connect --driver-opt
• docker network connect --link
• docker network connect --link-local-ip
• docker network create --attachable
• docker network create --aux-address
• docker network create --config-from
• docker network create --config-only
• docker network create --ingress
• docker network create --ipam-opt
• docker network create --scope
• docker network inspect --verbose
• docker network inspect -v
• docker secret create --label
• docker secret create --template-driver
• docker secret create -d
• docker secret create -l
• docker secret inspect --pretty
• docker secret inspect -f
• docker secret ls --quiet
• docker secret ls -q
  (The reason for the grep is that podman has options like -a, -l everywhere, and podman build and run have oodles of options that docker doesn't have. The purpose of this exercise was to find options that docker lists in its --help that are not documented in podman man pages).

[Luap99]

'docker create --help' lists '--gpus', which is not in docs/source/markdown/podman-create.1.md

Podman supports this as NOOP and hides it. AFAIK we always support gpus?

'docker create --help' lists '--dns-option', which is not in docs/source/markdown/podman-create.1.md

We have --dns-opt, interesting that nobody noticed this yet.

'docker create --help' lists '--domainname', which is not in docs/source/markdown/podman-create.1.md

No idea what this is but looks related to --hostname.

'docker create --help' lists '--kernel-memory', which is not in docs/source/markdown/podman-create.1.md

AFAIK this is deprecated but still supported by podman.

'docker create --help' lists '--link', which is not in docs/source/markdown/podman-create.1.md

This is deprecated for a long time in docker so podman never supported it.

'docker create --help' lists '--link-local-ip', which is not in docs/source/markdown/podman-create.1.md

No clue about this but this sounds scary to me.

'docker create --help' lists '--runtime', which is not in docs/source/markdown/podman-create.1.md
'docker create --help' lists '--storage-opt', which is not in docs/source/markdown/podman-create.1.md

I think the podman --runtime and --storage-opt are global flags so it should also work with podman rcreate/run.

---

I did not looked at everything but this is definitely an interesting find. At least some of them are easy enough to fix.

[rhatdan]

Great work @edsantiago

[rhatdan]

@vrothberg @ashley-cui @cdoern @baude Intern heaven above...

[vrothberg]

🤣

To synchronize work, please drop a comment when starting to fix a flag. First come, first serve, but this way we can avoid duplicate work.

[mheon]

To add a bit more to what @Luap99 did...

'docker create --help' lists '--runtime', which is not in docs/source/markdown/podman-create.1.md
This is a global flag in Podman, not a flag to an individual command.

'docker create --help' lists '-c', which is not in docs/source/markdown/podman-create.1.md
I think this is an alias for an existing command - maybe --cpus or --cpu-shares?

'docker create --help' lists '--isolation', which is not in docs/source/markdown/podman-create.1.md
This is specific to Windows containers

[jakecorrenti]

If these are low enough priority, I would like to pick away at these after hours

[jakecorrenti]

I can start off later today with docker pull --help' lists '-a', which is not in docs/source/markdown/podman-pull.1.md and add the short option for podman pull --all-tags

[ashley-cui]

@karthikelango137, If you're looking for work to do :)

[edsantiago]

Footnote: should anyone wish to run the script themselves, the following diff is necessary because of slightly different --help output:

index 7c07a4f01..c3edac148 100755                                                                                                                               
--- a/hack/xref-helpmsgs-manpages
+++ b/hack/xref-helpmsgs-manpages
@@ -230,8 +230,8 @@ sub podman_help {                                                                                          
         #       ....
         #
         # Start by identifying the section we're in...
-        if ($line =~ /^Available\s+(Commands):/) {
-            $section = lc $1;
+        if ($line =~ /^(Available\s+)?(Commands):/) {
+            $section = lc $2;
         }
         elsif ($line =~ /^(Options):/) {
             $section = lc $1;

[edsantiago]

'docker create --help' lists '-c', which is not in docs/source/markdown/podman-create.1.md
I think this is an alias for an existing command - maybe --cpus or --cpu-shares?

Belated followup: @mheon this was addressed in #14916 just now (yesterday/today). Presumably if I rerun the script right now (which I'm way too lazy to do), the above warning will be gone.

[rhatdan]

Added a checklist of the ones that are either done or intentionally not done.

[byarbrough]

I will grab docker push --help' lists '--all-tags

[karthikelango137]

I will take 'docker rmi --help' lists '--no-prune', which is not in docs/source/markdown/podman-rmi.1.md

[rhatdan]

Awesome.
I opened a PR on podman --host | -H == podman --connection.

[github-actions]

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

[rhatdan]

Other cases we have added to make third party tools that are executing podman as an alias of Docker to work, even if the option is a noop.

[byarbrough]

#14949 closed due to difficulties in containers/common#1099
That opens push --all-tags back up for somebody.

[edsantiago]

Did you mean to close this? Today's run shows the following differences:

• docker --config #hidden
• docker --context #hidden
• docker --debug #hidden
• docker --host #hidden
• docker --tls
• docker --tlscacert
• docker --tlscert
• docker --tlskey
• docker --tlsverify
• docker -D
• docker -H #hidden
• docker -l
• docker cp --follow-link
• docker cp -L
• docker create --domainname
• docker create --gpus #hidden
• docker create --isolation
• docker create --kernel-memory
• docker create --link
• docker create --link-local-ip
• docker create --runtime
• docker create --storage-opt
• docker create --volume-driver
• docker import --platform
• docker logs --details
• docker push --all-tags
• docker push -a
• docker rm --link
• docker run --domainname
• docker run --gpus
• docker run --isolation
• docker run --kernel-memory
• docker run --link
• docker run --link-local-ip
• docker run --runtime
• docker run --storage-opt
• docker run --volume-driver
• docker update --kernel-memory
• docker update --pids-limit
• docker update --restart
• docker version --kubeconfig

This is the updated command line; script diffs from earlier comment still necessary:

$ PODMAN=/usr/bin/docker hack/xref-helpmsgs-manpages 2>&1 |\
      grep -v 'but not --help' |\
      sed -e 's/^xref-helpmsgs-manpages: .podman / - [ ] docker /' \
          -e 's/ --help. lists ./ /' -e 's/., which.*$//

[rhatdan]

NO I Did not, we might need to fix our script a little to handle the hidden options.

'docker --help' lists '--debug', which is not in docs/source/markdown/podman.1.md # Hidden
'docker --help' lists '--host', which is not in docs/source/markdown/podman.1.md # Hidden
'docker --help' lists '-H', which is not in docs/source/markdown/podman.1.md # Hidden
'docker create --help' lists '--gpus', which is not in docs/source/markdown/podman-create.1.md # Hidden
'docker create --help' lists '--kernel-memory', which is not in docs/source/markdown/podman-create.1.md #Hidden
'docker logs --help' lists '--details', which is not in docs/source/markdown/podman-logs.1.md #Hidden
'docker run --help' lists '--dns-option', which is not in docs/source/markdown/podman-run.1.md # Hidden
'docker run --help' lists '--gpus', which is not in docs/source/markdown/podman-run.1.md # Hidden
'docker run --help' lists '--kernel-memory', which is not in docs/source/markdown/podman-run.1.md #Hidden
docker manifest create --insecure #Hidden
docker manifest inspect --insecure #hidden
docker manifest inspect --verbose #hidden

[edsantiago]

The hidden options are, by definition, not listed in the man page.

I'm acting on the assumption that we're almost done with these, and (fingers crossed) won't need to perform this exercise again. If we do need to repeat this, I guess I'll need to define and maintain a hardcoded list of exceptions. I will defer that problem for the day it's needed 😉

[rhatdan]

Your updated lists seems to be missing some of the original ones that are still not fixed.

[rhatdan]

Any ways I did not intend to close this and will work off the original list.
It might be useful to recreate this list every time Docker releases.

[edsantiago]

Closing in favor of #16543