From 2d7373ad9200ed3d3295e6c558dae7f273597ce9 Mon Sep 17 00:00:00 2001 From: Yossi Eliaz Date: Tue, 31 Mar 2026 08:42:14 +0300 Subject: [PATCH] Fix incorrect documentation for `docker cp -a` flag The `-a` (`--archive`) flag description claimed "Archive mode (copy all uid/gid information)" which is misleading. In practice: - Without `-a` (default): `docker cp` preserves ownership (uid/gid) from the source - With `-a`: ownership is set to match the container user (as configured with `--user`) The old documentation described the opposite of the actual behavior, as reported in #6870. Updated the flag description in the Go source, markdown docs, and fish shell completions to accurately reflect the behavior. Closes #6870 --- cli/command/container/cp.go | 2 +- contrib/completion/fish/docker.fish | 2 +- docs/reference/commandline/container_cp.md | 12 +++++------- docs/reference/commandline/cp.md | 2 +- 4 files changed, 8 insertions(+), 10 deletions(-) diff --git a/cli/command/container/cp.go b/cli/command/container/cp.go index 8193e8b04fe2..be76848346ea 100644 --- a/cli/command/container/cp.go +++ b/cli/command/container/cp.go @@ -159,7 +159,7 @@ container source to stdout.`, flags := cmd.Flags() flags.BoolVarP(&opts.followLink, "follow-link", "L", false, "Always follow symbol link in SRC_PATH") - flags.BoolVarP(&opts.copyUIDGID, "archive", "a", false, "Archive mode (copy all uid/gid information)") + flags.BoolVarP(&opts.copyUIDGID, "archive", "a", false, "Archive mode (set ownership to match the container user)") flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Suppress progress output during copy. Progress output is automatically suppressed if no terminal is attached") return cmd } diff --git a/contrib/completion/fish/docker.fish b/contrib/completion/fish/docker.fish index 8a127cf9a7fe..9f446cd90b1d 100644 --- a/contrib/completion/fish/docker.fish +++ b/contrib/completion/fish/docker.fish @@ -169,7 +169,7 @@ complete -c docker -A -f -n '__fish_seen_subcommand_from commit' -a '(__fish_pri # cp complete -c docker -f -n '__fish_docker_no_subcommand' -a cp -d "Copy files/folders between a container and the local filesystem" -complete -c docker -A -f -n '__fish_seen_subcommand_from cp' -s a -l archive -d 'Archive mode (copy all uid/gid information)' +complete -c docker -A -f -n '__fish_seen_subcommand_from cp' -s a -l archive -d 'Archive mode (set ownership to match the container user)' complete -c docker -A -f -n '__fish_seen_subcommand_from cp' -s L -l follow-link -d 'Always follow symbol link in SRC_PATH' complete -c docker -A -f -n '__fish_seen_subcommand_from cp' -l help -d 'Print usage' diff --git a/docs/reference/commandline/container_cp.md b/docs/reference/commandline/container_cp.md index 9a6166625988..2552222c806f 100644 --- a/docs/reference/commandline/container_cp.md +++ b/docs/reference/commandline/container_cp.md @@ -16,7 +16,7 @@ container source to stdout. | Name | Type | Default | Description | |:----------------------|:-------|:--------|:-------------------------------------------------------------------------------------------------------------| -| `-a`, `--archive` | `bool` | | Archive mode (copy all uid/gid information) | +| `-a`, `--archive` | `bool` | | Archive mode (set ownership to match the container user) | | `-L`, `--follow-link` | `bool` | | Always follow symbol link in SRC_PATH | | `-q`, `--quiet` | `bool` | | Suppress progress output during copy. Progress output is automatically suppressed if no terminal is attached | @@ -41,12 +41,10 @@ relative paths as relative to the current working directory where `docker cp` is run. The `cp` command behaves like the Unix `cp -a` command in that directories are -copied recursively with permissions preserved if possible. Ownership is set to -the user and primary group at the destination. For example, files copied to a -container are created with `UID:GID` of the root user. Files copied to the local -machine are created with the `UID:GID` of the user which invoked the `docker cp` -command. However, if you specify the `-a` option, `docker cp` sets the ownership -to the user and primary group at the source. +copied recursively with permissions preserved if possible. By default, ownership +(uid/gid) of the copied files is preserved from the source. If you specify the +`-a` option, `docker cp` sets the ownership to match the user and primary group +of the container (as configured with `--user`). If you specify the `-L` option, `docker cp` follows any symbolic link in the `SRC_PATH`. `docker cp` doesn't create parent directories for `DEST_PATH` if they don't exist. diff --git a/docs/reference/commandline/cp.md b/docs/reference/commandline/cp.md index ded96d696643..df7257d6445e 100644 --- a/docs/reference/commandline/cp.md +++ b/docs/reference/commandline/cp.md @@ -16,7 +16,7 @@ container source to stdout. | Name | Type | Default | Description | |:----------------------|:-------|:--------|:-------------------------------------------------------------------------------------------------------------| -| `-a`, `--archive` | `bool` | | Archive mode (copy all uid/gid information) | +| `-a`, `--archive` | `bool` | | Archive mode (set ownership to match the container user) | | `-L`, `--follow-link` | `bool` | | Always follow symbol link in SRC_PATH | | `-q`, `--quiet` | `bool` | | Suppress progress output during copy. Progress output is automatically suppressed if no terminal is attached |