fix(cp): clarify --archive flag description by mohithshuka · Pull Request #6937 · docker/cli

mohithshuka · 2026-04-17T14:55:15Z

Description

Fixes the misleading description of the --archive / -a flag in docker cp.

Fixes #6870

What was wrong

The previous description:

Archive mode (copy all uid/gid information)

This was vague and inaccurate — it didn't clarify:

That it preserves uid/gid from the source (not just "copies")
That it only takes effect when copying TO a container

What changed

Updated the flag description in cli/command/container/cp.go:

Before:

After:

Testing

Read the updated flag description with docker cp --help
Verified against the existing behavior documented in container_cp.md

Fixes #24643 --kernel-memory was deprecated in v20.10 and removed in v23.0. Add deprecation callouts to both the options table and the Kernel memory constraints section of the run reference page.

The --filter flag for 'docker volume prune' previously only showed 'label=<label>' as an example, not mentioning the negation form 'label!=<label>', even though it is valid and supported by the daemon. Fixes docker#6918 Signed-off-by: mohithshuka <153504854+mohithshuka@users.noreply.github.com>

When a port is bound on both 0.0.0.0 and ::, hide the IPv6 entry and show only the IPv4 entry to reduce noise in docker ps output. Before: 0.0.0.0:8080->80/tcp, :::8080->80/tcp After: 0.0.0.0:8080->80/tcp Fixes docker#6869

The --archive (-a) flag description was misleading. Updated to clarify that it preserves uid/gid from the source, and that it only takes effect when copying files TO a container (not from). Fixes docker#6870

Copilot

Pull request overview

Updates user-facing CLI/docs text and output formatting to reduce confusion: clarifies docker cp --archive behavior, documents --kernel-memory deprecation/removal, expands volume prune filter examples, and tweaks docker ps port display to avoid duplicate wildcard bindings.

Changes:

Clarify docker cp -a/--archive help text to specify it preserves uid/gid from the source when copying to a container.
Document --kernel-memory as deprecated/removed and add a deprecation callout in docker run reference docs.
Suppress duplicate IPv6 wildcard (::) port mappings in docker ps output when an IPv4 wildcard mapping already exists.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
docs/reference/run.md	Marks `--kernel-memory` as deprecated/removed and adds a deprecation notice in the kernel memory section.
cli/command/volume/prune.go	Expands the `--filter` help example to include `label!=...`.
cli/command/formatter/container.go	Adds logic to suppress duplicate `::` wildcard mappings when `0.0.0.0` is present.
cli/command/container/cp.go	Updates `--archive` flag description for `docker cp`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-17T14:59:58Z

 			if port.PublicPort != current {
+				// Suppress the IPv6 wildcard entry when an IPv4 wildcard
+				// entry already covers the same (hostPort, privatePort, proto)
+				// tuple. This merges:
+				//   0.0.0.0:8080->80/tcp, :::8080->80/tcp
+				// into the cleaner:
+				//   0.0.0.0:8080->80/tcp
+				if port.IP.Is6() && !port.IP.Is4In6() && port.IP.IsUnspecified() {
+					key := mappingKey{port.PublicPort, port.PrivatePort, port.Type}
+					if ipv4Bindings[key] {
+						continue
+					}
+				}


The IPv6-wildcard suppression only runs in the port.PublicPort != port.PrivatePort branch. If the host and container ports are the same (e.g. -p 80:80), docker ps output can still include both 0.0.0.0:80->80/tcp and [::]:80->80/tcp because those entries follow the grouping path. Consider applying the same suppression when building grouped entries (i.e., before using portKey = port.IP.String() + "/" + port.Type).

Suggested change

if port.PublicPort != current {

// Suppress the IPv6 wildcard entry when an IPv4 wildcard

// entry already covers the same (hostPort, privatePort, proto)

// tuple. This merges:

// 0.0.0.0:8080->80/tcp, :::8080->80/tcp

// into the cleaner:

// 0.0.0.0:8080->80/tcp

if port.IP.Is6() && !port.IP.Is4In6() && port.IP.IsUnspecified() {

key := mappingKey{port.PublicPort, port.PrivatePort, port.Type}

if ipv4Bindings[key] {

continue

}

}

// Suppress the IPv6 wildcard entry when an IPv4 wildcard

// entry already covers the same (hostPort, privatePort, proto)

// tuple. This merges:

// 0.0.0.0:8080->80/tcp, :::8080->80/tcp

// into the cleaner:

// 0.0.0.0:8080->80/tcp

//

// Apply this before both formatting branches so grouped entries

// for equal host/container ports (for example -p 80:80) also

// suppress the redundant IPv6 wildcard binding.

if port.IP.Is6() && !port.IP.Is4In6() && port.IP.IsUnspecified() {

key := mappingKey{port.PublicPort, port.PrivatePort, port.Type}

if ipv4Bindings[key] {

continue

}

}

if port.PublicPort != current {

Copilot · 2026-04-17T14:59:59Z

+	// Pre-pass: record which (hostPort, privatePort, proto) tuples have an
+	// IPv4 wildcard (0.0.0.0) binding. Used below to suppress the matching
+	// IPv6 wildcard (::) entry, avoiding duplicate output such as:
+	//   0.0.0.0:8080->80/tcp, :::8080->80/tcp
+	// See: https://github.com/docker/cli/issues/6869


DisplayablePorts formatting behavior changed to suppress certain IPv6 wildcard entries, but there’s no corresponding unit test coverage for the mixed 0.0.0.0 + :: cases (including both hostPort!=containerPort and hostPort==containerPort). Adding test cases in cli/command/formatter/container_test.go would prevent regressions in this output formatting.

Copilot · 2026-04-17T14:59:59Z

 | `--memory-swap=""`         | Total memory limit (memory + swap, format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`.                                                                                                                                                  |
 | `--memory-reservation=""`  | Memory soft limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`.                                                                                                                                                                  |
-| `--kernel-memory=""`       | Kernel memory limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. Minimum is 4M.                                                                                                                                                 |
+| `--kernel-memory=""`       | **Deprecated**: Kernel memory limit. Deprecated in Docker v20.10, and removed in Docker v23.0. This option is ignored when set.                                                                                                                                                          |


The table entry says --kernel-memory was removed in Docker v23.0 but also says the option is ignored when set. Since the CLI still defines the flag (deprecated stub) and the Engine ignores it, consider rewording to clarify it was removed from / no longer supported by the Engine (and ignored), rather than implying the flag itself no longer exists.

Suggested change

| `--kernel-memory=""` | **Deprecated**: Kernel memory limit. Deprecated in Docker v20.10, and removed in Docker v23.0. This option is ignored when set. |

| `--kernel-memory=""` | **Deprecated**: Kernel memory limit. Deprecated in Docker v20.10, no longer supported by the Engine since Docker v23.0, and ignored when set. |

Copilot · 2026-04-17T14:59:59Z

+> **Deprecated**
+>
+> The `--kernel-memory` option was deprecated in Docker v20.10 and removed in
+> Docker v23.0. The Linux kernel deprecated `kmem.limit_in_bytes` in kernel
+> v5.4, and OCI runtimes such as runc no longer support this option. Docker API


After adding the deprecation notice, the rest of this section still describes --kernel-memory constraints and includes usage examples as if the limit is functional. Given the Engine ignores this option, consider either removing/updating the subsequent explanation/examples or clearly marking them as historical/unsupported to avoid misleading readers.

Copilot · 2026-04-17T14:59:59Z

 	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 (preserve uid/gid from source when copying to container)")


The CLI help-string for --archive was updated, but the generated command reference docs (docs/reference/commandline/cp.md and docs/reference/commandline/container_cp.md) still contain the old description. If those docs are expected to match the CLI help output, they should be regenerated/updated as part of this change so the documentation fix is complete.

Copilot · 2026-04-17T15:00:00Z

 	flags.SetAnnotation("all", "version", []string{"1.42"})
 	flags.BoolVarP(&options.force, "force", "f", false, "Do not prompt for confirmation")
-	flags.Var(&options.filter, "filter", `Provide filter values (e.g. "label=<label>")`)
+	flags.Var(&options.filter, "filter", `Provide filter values (e.g. "label=<label>" or "label!=<label>")`)


PR title/description focus on docker cp --archive help text, but this PR also changes docker run kernel-memory documentation, volume prune filter help, and docker ps port-formatting logic. Please update the PR description/title to reflect the additional scope, or split these unrelated changes into separate PRs to make review/revert safer.

mohithshuka added 4 commits April 9, 2026 17:45

docs: add deprecation notice for --kernel-memory flag

0015f6c

Fixes #24643 --kernel-memory was deprecated in v20.10 and removed in v23.0. Add deprecation callouts to both the options table and the Kernel memory constraints section of the run reference page.

fix(cp): clarify --archive flag only applies when copying to container

044dea2

The --archive (-a) flag description was misleading. Updated to clarify that it preserves uid/gid from the source, and that it only takes effect when copying files TO a container (not from). Fixes docker#6870

mohithshuka requested review from a team and thaJeztah as code owners April 17, 2026 14:55

Copilot AI review requested due to automatic review settings April 17, 2026 14:55

Copilot started reviewing on behalf of mohithshuka April 17, 2026 14:55 View session

Copilot AI reviewed Apr 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(cp): clarify --archive flag description#6937

fix(cp): clarify --archive flag description#6937
mohithshuka wants to merge 4 commits intodocker:masterfrom
mohithshuka:fix/docker-cp-a-docs

mohithshuka commented Apr 17, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 17, 2026

Uh oh!

Copilot AI Apr 17, 2026

Uh oh!

Copilot AI Apr 17, 2026

Uh oh!

Copilot AI Apr 17, 2026

Uh oh!

Copilot AI Apr 17, 2026

Uh oh!

Copilot AI Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	\| `--kernel-memory=""` \| Deprecated: Kernel memory limit. Deprecated in Docker v20.10, and removed in Docker v23.0. This option is ignored when set. \|
	\| `--kernel-memory=""` \| Deprecated: Kernel memory limit. Deprecated in Docker v20.10, no longer supported by the Engine since Docker v23.0, and ignored when set. \|

Conversation

mohithshuka commented Apr 17, 2026

Description

What was wrong

What changed

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants