Intro description of a volume does not appear to align with later text

[Kelso-stryd]

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

Information is incorrect

Description

"By contrast, when you use a volume, a new directory is created within Docker's storage directory on the host machine, and Docker manages that directory's contents."

Makes it sound like the link between the inside of a container and a volume is not native and bidirectional, but managed by docker, which would imply docker is doing some copying as needed to keep things consistent, and that the contents can diverge.

Later on the page

"To create a bind mount, you can use either the --mount or --volume flag."
and
"In general, --mount is preferred. The main difference is that the --mount flag is more explicit and supports all the available options.

If you use --volume to bind-mount a file or directory that does not yet exist on the Docker host, Docker automatically creates the directory on the host for you. It's always created as a directory."

Implies --volume is effectively an alias to --mount with limited functionality, but it will create a directory for you within the container when a mount is established.

Location

https://docs.docker.com/engine/storage/bind-mounts/

Suggestion

I'm more inclined to believe the later text, but the intro language should be corrected to better reflect what's actually going on.

[dvdksn]

Agent Triage Result: OPEN

This is a valid documentation clarity issue. The introductory paragraph in the bind mounts documentation contrasts bind mounts with volumes, but the language "Docker manages that directory's contents" could be misinterpreted as Docker doing active copying/syncing rather than native filesystem operations.

The issue will be addressed by clarifying the language to better explain that volumes use native filesystem operations, not copying/syncing mechanisms.

Analysis:

• File: content/manuals/engine/storage/bind-mounts.md
• Issue: Confusing language in the intro paragraph about how volumes work
• Fix: Clarify that volumes use direct filesystem access, not copying

A task has been created to fix this issue.