Clarify order of -v x:y volume mount flag

[mdavis-xyz]

Problem description

I want to mount folder x on my laptop to folder y inside my container. It is not clear from the documentation whether I need docker run -v x:y or -v y:x.

e.g. the first example is

-v `pwd`:`pwd`

That's symetrical, so doesn't show which way around the flag use is. (Adding a new first example with hard-coded paths would also probably be more clear than calling a nested shell command.)

The documentation should state which way around the order of the -v flag is.

It's also not clear to me whether omitting a colon is allowed. One example uses just -v /icanwrite, which looks like it mounts the same path on host and container. But if that is allowed syntax, why is the first example

-v `pwd`:`pwd`

instead of just

-v `pwd` 

Problem location

https://docs.docker.com/engine/reference/commandline/run/#mount-volume--v---read-only

Project version(s) affected

All?

Suggestions for a fix

The -p flag has the same potential ambiguity as -v, which is addressed by the first example and first sentence.

 docker run -p 127.0.0.1:80:8080/tcp ubuntu bash

This binds port 8080 of the container to TCP port 80 on 127.0.0.1 of the host machine.

The docs for -v should be similar.

So I think the first paragraph of this section should be:

The -v flag is used to share files or folders between the host and container.

docker  run  -v /path/on/host:/path/inside/container -w `pwd` -i -t  ubuntu pwd

This mounts /path/on/host on the host to /path/inside/container inside the container. The arguments can be either directories or files.

docker  run  -v /a:/b -v /c.txt:/d.txt -w `pwd` -i -t  ubuntu pwd

This mounts multiple folders and files from the host to the container.

And simplify what was the first example, which will become the second example, to be just

-v `pwd`