From a7650310469abcd3a7cf977ac3dbb73901768223 Mon Sep 17 00:00:00 2001
From: Dean Chen <862469039@qq.com>
Date: Tue, 11 Aug 2026 14:02:04 +0500
Subject: [PATCH] docs(cp): clarify -a sets ownership to the container user

Default docker cp keeps source uid/gid. -a/--archive remaps
ownership to the container's user instead of "preserving all
uid/gid information" as the old wording suggested.

Fixes #6870

Signed-off-by: Dean Chen <862469039@qq.com>
---
 cli/command/container/cp.go                | 2 +-
 contrib/completion/fish/docker.fish        | 2 +-
 docs/reference/commandline/container_cp.md | 2 +-
 docs/reference/commandline/cp.md           | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/cli/command/container/cp.go b/cli/command/container/cp.go
index fbce9df646e5..6963be5f66bf 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 symlinks in SRC_PATH")
-	flags.BoolVarP(&opts.copyUIDGID, "archive", "a", false, "Archive mode (copy all uid/gid information)")
+	flags.BoolVarP(&opts.copyUIDGID, "archive", "a", false, "Set file ownership to the container user (default preserves source uid/gid)")
 	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 bf1dd38b3b0c..225154fec920 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 'Set file ownership to the container user (default preserves source uid/gid)'
 complete -c docker -A -f -n '__fish_seen_subcommand_from cp' -s L -l follow-link -d 'Always follow symlinks 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 8d8958bb37b7..132e4061b2ee 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` |         | Set file ownership to the container user (default preserves source uid/gid)                                                                  |
 | `-L`, `--follow-link` | `bool` |         | Always follow symlinks in SRC_PATH                                                                           |
 | `-q`, `--quiet`       | `bool` |         | Suppress progress output during copy. Progress output is automatically suppressed if no terminal is attached |
 
diff --git a/docs/reference/commandline/cp.md b/docs/reference/commandline/cp.md
index 085f089e133b..648a6628ac31 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` |         | Set file ownership to the container user (default preserves source uid/gid)                                                                  |
 | `-L`, `--follow-link` | `bool` |         | Always follow symlinks in SRC_PATH                                                                           |
 | `-q`, `--quiet`       | `bool` |         | Suppress progress output during copy. Progress output is automatically suppressed if no terminal is attached |