Document volume mounts of source directories do NOT get created

We differ from Docker, in that we do not create the source directory
in a --volume mount if it does not exists.  We return an error.

We do not believe that a `typo` from the user should cause a directory
to be created and silently ignored by Podman.

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

Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>

2 files changed, 33 insertions, 24 deletions

diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
index f280087c2..ab390447e 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -1021,18 +1021,21 @@ The _options_ is a comma delimited list and can be:
 The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume
 will be mounted into the container at this directory.
 
-Volumes may specify a source as well, as either a directory on the host or the
-name of a named volume. If no source is given, the volume will be created as an
-anonymous named volume with a randomly generated name, and will be removed when
+Volumes may specify a source as well, as either a directory on the host
+or the name of a named volume. If no source is given, the volume will be created as an
+anonymously named volume with a randomly generated name, and will be removed when
 the container is removed via the `--rm` flag or `podman rm --volumes`.
 
 If a volume source is specified, it must be a path on the host or the name of a
 named volume. Host paths are allowed to be absolute or relative; relative paths
-are resolved relative to the directory Podman is run in. Any source that does
-not begin with a `.` or `/` will be treated as the name of a named volume.
-If a volume with that name does not exist, it will be created. Volumes created
-with names are not anonymous. They are not removed by the `--rm` option and the
-`podman rm --volumes` command.
+are resolved relative to the directory Podman is run in. If the source does not
+exist, Podman will return an error. Users must pre-create the source files or
+directories.
+
+Any source that does not begin with a `.` or `/` will be treated as the name of
+a named volume. If a volume with that name does not exist, it will be created.
+Volumes created with names are not anonymous, and they are not removed by the `--rm`
+option and the `podman rm --volumes` command.
 
 You can specify multiple  **-v** options to mount one or more volumes into a
 container.
@@ -1069,7 +1072,7 @@ upper. Modifications to the mount point are destroyed when the container
 finishes executing, similar to a tmpfs mount point being unmounted.
 
   Subsequent executions of the container will see the original source directory
-content, any changes from previous container executions no longer exists.
+content, any changes from previous container executions no longer exist.
 
   One use case of the overlay mount is sharing the package cache from the
 host into the container to allow speeding up builds.
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index d65d5d26f..13b586e17 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -1054,11 +1054,11 @@ Set the UTS namespace mode for the container. The following values are supported
 - **ns:[path]**: run the container in the given existing UTS namespace.
 - **container:[container]**: join the UTS namespace of the specified container.
 
-#### **--volume**, **-v**[=[[_source-volume_|_host-dir_:]_container-dir_[:_options_]]]
+#### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*]
 
-Create a bind mount. If you specify _/host-dir_:_/container-dir_, Podman
-bind mounts _host-dir_ in the host to _container-dir_ in the Podman
-container. Similarly, _source-volume_:_/container-dir_ will mount the volume
+Create a bind mount. If you specify _/HOST-DIR_:_/CONTAINER-DIR_, Podman
+bind mounts _host-dir_ in the host to _CONTAINER-DIR_ in the Podman
+container. Similarly, _SOURCE-VOLUME_:_/CONTAINER-DIR_ will mount the volume
 in the host to the container. If no such named volume exists, Podman will
 create one.
 
@@ -1073,24 +1073,30 @@ The _options_ is a comma delimited list and can be: <sup>[[1]](#Footnote1)</sup>
 * [**no**]**suid**
 * [**O**]
 
-The _container-dir_ must be an absolute path.
+The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume
+will be mounted into the container at this directory.
 
-Volumes may specify a source as well, as either a directory on the host or the
-name of a named volume. If no source is given, the volume will be created as an
-anonymous named volume with a randomly generated name, and will be removed when
-the container is removed via the **--rm** flag or **podman rm --volumes**.
+Volumes may specify a source as well, as either a directory on the host
+or the name of a named volume. If no source is given, the volume will be created as an
+anonymously named volume with a randomly generated name, and will be removed when
+the container is removed via the `--rm` flag or `podman rm --volumes`.
 
 If a volume source is specified, it must be a path on the host or the name of a
 named volume. Host paths are allowed to be absolute or relative; relative paths
-are resolved relative to the directory Podman is run in. Any source that does
-not begin with a **.** or **/** will be treated as the name of a named volume.
-If a volume with that name does not exist, it will be created. Volumes created
-with names are not anonymous and are not removed by **--rm** and
-**podman rm --volumes**.
+are resolved relative to the directory Podman is run in. If the source does not
+exist, Podman will return an error. Users must pre-create the source files or
+directories.
+
+Any source that does not begin with a `.` or `/` will be treated as the name of
+a named volume. If a volume with that name does not exist, it will be created.
+Volumes created with names are not anonymous, and they are not removed by the `--rm`
+option and the `podman rm --volumes` command.
 
 You can specify multiple **-v** options to mount one or more volumes into a
 container.
 
+  `Write Protected Volume Mounts`
+
 You can add **:ro** or **:rw** option to mount a volume in read-only or
 read-write mode, respectively. By default, the volumes are mounted read-write.
 
@@ -1119,7 +1125,7 @@ upper. Modifications to the mount point are destroyed when the container
 finishes executing, similar to a tmpfs mount point being unmounted.
 
   Subsequent executions of the container will see the original source directory
-content, any changes from previous container executions no longer exists.
+content, any changes from previous container executions no longer exist.
 
   One use case of the overlay mount is sharing the package cache from the
 host into the container to allow speeding up builds.