A Bind Mount Hides Existing Container Files; It Does Not Merge with Them

Many people mistakenly believe that a container's bind mount merges the host and container directories together. This is not the case. When a bind mount is applied, it simply replaces the container directory's view for the duration of the mount. For example, if an image contains files like "/app/config/default.yaml" and "/app/config/schema.json", and the container is started with a host directory mounted at "/app/config", the container will only see the file "/app/config/production.yaml" if "/srv/config" contains only that file.

The original "/app/config/default.yaml" and "/app/config/schema.json" files are not deleted, copied, or overwritten. They simply become hidden beneath the bind mount. This behavior stems from the way Linux handles mount semantics, not from any special merge algorithm in containers. A bind mount essentially attaches one filesystem tree at a mount point.

When looking beneath that point, the path finder goes through the mounted tree first, rendering the underlying image layer's directory entries unreachable through their original paths. This explains why applications run fine when launched directly from their image but fail after a configuration directory is mounted. The operator may think they are overriding a file, but mounting the directory actually hides every image-provided file under that path.

Unlike image layers, which can contribute files to the container's root filesystem, a bind mount is added afterward at a specific path. It does not merge with the directory underneath to form a union layer. If the goal is to replace only one file, mounting the file directly rather than its parent directory is recommended. Alternatively, configuration defaults can be placed outside the mount point and copied into a writable directory before starting the application.

The exact design approach depends on whether the configuration should be immutable, generated, or persistent. When the container is stopped and removed, the mount relationship is also terminated, but the original image files remain intact. A new container started without the bind mount will see the original files again. The accurate statement is that a bind mount does not merge host and container directory contents.

Instead, it makes the mounted source the visible filesystem tree at the destination, obscuring whatever was previously visible there.