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

Author: zozo123

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
 }

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'
 

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.

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 |