Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mohithshuka wants to merge 4 commits into
base: master
Choose a base branch
from
+43 −4
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0015f6c
docs: add deprecation notice for --kernel-memory flag
mohithshuka Apr 9, 2026
cbeeefe
fix(volume/prune): document label!= filter in --filter flag description
mohithshuka Apr 11, 2026
397a379
formatter: suppress duplicate IPv6 wildcard port in docker ps output
mohithshuka Apr 12, 2026
044dea2
fix(cp): clarify --archive flag only applies when copying to container
mohithshuka Apr 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion cli/command/container/cp.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 (preserve uid/gid from source when copying to container)")
Copy link

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Suppress progress output during copy. Progress output is automatically suppressed if no terminal is attached")
return cmd
}
Expand Down
32 changes: 31 additions & 1 deletion cli/command/formatter/container.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -364,6 +364,24 @@ func DisplayablePorts(ports []container.PortSummary) string {
var result []string
var hostMappings []string
var groupMapKeys []string

// 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
Comment on lines +368 to +372
Copy link

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
type mappingKey struct {
hostPort uint16
privatePort uint16
proto string
}
ipv4Bindings := make(map[mappingKey]bool)
for _, port := range ports {
if port.IP.String() == "0.0.0.0" && port.PublicPort != 0 {
ipv4Bindings[mappingKey{port.PublicPort, port.PrivatePort, port.Type}] = true
}
}

sort.Slice(ports, func(i, j int) bool {
return comparePorts(ports[i], ports[j])
})
Expand All @@ -373,6 +391,18 @@ func DisplayablePorts(ports []container.PortSummary) string {
portKey := port.Type
if port.IP.IsValid() {
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
}
}
Comment on lines 393 to +405
Copy link

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
hAddrPort := net.JoinHostPort(port.IP.String(), strconv.Itoa(int(port.PublicPort)))
hostMappings = append(hostMappings, fmt.Sprintf("%s->%d/%s", hAddrPort, port.PrivatePort, port.Type))
continue
Expand Down Expand Up @@ -435,4 +465,4 @@ func comparePorts(i, j container.PortSummary) bool {
}

return i.Type < j.Type
}
}
2 changes: 1 addition & 1 deletion cli/command/volume/prune.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ func newPruneCommand(dockerCLI command.Cli) *cobra.Command {
flags.BoolVarP(&options.all, "all", "a", false, "Remove all unused volumes, not just anonymous ones")
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>")`)
Copy link

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.

return cmd
}
Expand Down
11 changes: 10 additions & 1 deletion docs/reference/run.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -334,7 +334,7 @@ container:
| `-m`, `--memory=""` | Memory limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. Minimum is 6M. |
| `--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. |
Copy link

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
| `-c`, `--cpu-shares=0` | CPU shares (relative weight) |
| `--cpus=0.000` | Number of CPUs. Number is a fractional number. 0.000 means no limit. |
| `--cpu-period=0` | Limit the CPU CFS (Completely Fair Scheduler) period |
Expand Down Expand Up @@ -502,6 +502,15 @@ less likely to be killed, and positive scores more likely.

### Kernel memory constraints

> **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
Comment on lines +505 to +509
Copy link

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
> v1.42 and later ignores this option when set. Do not use `--kernel-memory` in
> new configurations. For more details, see the
> [Deprecated features](https://docs.docker.com/engine/deprecated/) page.

Kernel memory is fundamentally different than user memory as kernel memory can't
be swapped out. The inability to swap makes it possible for the container to
block system services by consuming too much kernel memory. Kernel memory includes：
Expand Down
Loading