From 77fa05fdc0b88f31b1d34b61fdc1c399293c7bf6 Mon Sep 17 00:00:00 2001 From: Ashutosh Jadhav Date: Fri, 17 Jul 2026 20:59:33 +0530 Subject: [PATCH] Document the --volume three-part form and mount option behavior The --volume flag accepts an undocumented third colon-separated component containing comma-separated mount options (host-path:container-path:options), but neither the CLI help text nor the docs mention it. Document all three accepted formats in the flag help, the command reference, and the how-to guide, including a note that for host directory mounts only the ro option is currently guaranteed to take effect and that other options are silently ignored unless combined with ro. Fixes #1940 Co-Authored-By: Claude Fable 5 --- .../Services/ContainerAPIService/Client/Flags.swift | 6 +++++- docs/command-reference.md | 4 ++-- docs/how-to.md | 10 ++++++++++ 3 files changed, 17 insertions(+), 3 deletions(-) diff --git a/Sources/Services/ContainerAPIService/Client/Flags.swift b/Sources/Services/ContainerAPIService/Client/Flags.swift index d26eddd75..a7dd67b76 100644 --- a/Sources/Services/ContainerAPIService/Client/Flags.swift +++ b/Sources/Services/ContainerAPIService/Client/Flags.swift @@ -344,7 +344,11 @@ public struct Flags { ) public var virtualization: Bool = false - @Option(name: [.customLong("volume"), .short], help: "Bind mount a volume into the container") + @Option( + name: [.customLong("volume"), .short], + help: + "Bind mount a volume into the container. Formats: container-path (anonymous volume), name:container-path[:options], or host-path:container-path[:options], where options is a comma-separated list of mount options (e.g. ro)" + ) public var volumes: [String] = [] public func validate() throws { diff --git a/docs/command-reference.md b/docs/command-reference.md index c7d854806..34849e43c 100644 --- a/docs/command-reference.md +++ b/docs/command-reference.md @@ -72,7 +72,7 @@ container run [] [ ...] * `--ssh`: Forward SSH agent socket to container * `--shm-size `: Size of `/dev/shm` (e.g. 64M, 1G) * `--tmpfs `: Add a tmpfs mount to the container at the given path -* `-v, --volume `: Bind mount a volume into the container +* `-v, --volume `: Bind mount a volume into the container. Formats: `container-path` (anonymous volume), `name:container-path[:options]`, or `host-path:container-path[:options]`, where `options` is a comma-separated list of mount options (e.g. `ro`) * `--virtualization`: Expose virtualization capabilities to the container (requires host and guest support) **Registry Options** @@ -245,7 +245,7 @@ container create [] [ ...] * `--ssh`: Forward SSH agent socket to container * `--shm-size `: Size of `/dev/shm` (e.g. 64M, 1G) * `--tmpfs `: Add a tmpfs mount to the container at the given path -* `-v, --volume `: Bind mount a volume into the container +* `-v, --volume `: Bind mount a volume into the container. Formats: `container-path` (anonymous volume), `name:container-path[:options]`, or `host-path:container-path[:options]`, where `options` is a comma-separated list of mount options (e.g. `ro`) * `--virtualization`: Expose virtualization capabilities to the container (requires host and guest support) **Registry Options** diff --git a/docs/how-to.md b/docs/how-to.md index 62a883963..9ebf7bb29 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -51,6 +51,16 @@ total 4 The argument to `--volume` in the example consists of the full pathname for the host folder and the full pathname for the mount point in the container, separated by a colon. +You can append a third colon-separated component containing a comma-separated list of mount options. For example, use `ro` to make the mount read-only in the container: + +
+% container run --volume ${HOME}/Desktop/assets:/content/assets:ro docker.io/python:alpine touch /content/assets/test
+touch: /content/assets/test: Read-only file system
+
+ +> [!NOTE] +> For host directory mounts, only the `ro` option is currently guaranteed to take effect. Other mount options, such as `nosuid`, are applied only when combined with `ro`; without `ro`, they are silently ignored. + The `--mount` option uses a comma-separated `key=value` syntax to achieve the same result: