Skip to content

Fix incorrect documentation for docker cp -a flag#6895

Open
zozo123 wants to merge 1 commit intodocker:masterfrom
zozo123:fix/cp-archive-flag-docs
Open

Fix incorrect documentation for docker cp -a flag#6895
zozo123 wants to merge 1 commit intodocker:masterfrom
zozo123:fix/cp-archive-flag-docs

Conversation

@zozo123
Copy link
Copy Markdown

@zozo123 zozo123 commented Mar 31, 2026

Summary

  • Fixed the -a (--archive) flag description for docker cp which incorrectly stated "Archive mode (copy all uid/gid information)"
  • Updated the extended documentation in container_cp.md which incorrectly described the default and -a behaviors
  • Updated fish shell completions to match

Problem

The documentation claimed -a means "copy all uid/gid information", implying it preserves original uid/gid. In practice:

  • Without -a (default): docker cp already preserves ownership (uid/gid) from the source
  • With -a: ownership is changed to match the container user (as configured with --user)

The old docs described the opposite of what actually happens. See also moby/moby#34096 for the related behavior discussion.

Changes

File Change
cli/command/container/cp.go Updated Go flag description string
docs/reference/commandline/cp.md Updated options table description
docs/reference/commandline/container_cp.md Updated options table + extended description paragraph
contrib/completion/fish/docker.fish Updated fish shell completion description

Test plan

  • Verified all instances of old text are replaced (grep returns no matches for "copy all uid/gid information")
  • Reviewed diff to confirm only documentation strings changed, no logic changes
  • Documentation-only change; no functional tests affected

Closes #6870

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 docker#6870.

Updated the flag description in the Go source, markdown docs, and fish
shell completions to accurately reflect the behavior.

Closes docker#6870
@zozo123 zozo123 requested review from a team and thaJeztah as code owners March 31, 2026 05:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docker cp -a docs incorrect

1 participant