Skip to content

docs: update docker cp --archive flag description to match source #6939

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 5 commits into
base: master
Choose a base branch
from
Open

docs: update docker cp --archive flag description to match source #6939

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 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
e2abd26
docs: update docker cp --archive flag description to match source
mohithshuka Apr 18, 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)")
flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Suppress progress output during copy. Progress output is automatically suppressed if no terminal is attached")
Comment on lines 161 to 163
Copy link

Copilot AI Apr 18, 2026

Choose a reason for hiding this comment

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

The PR description says the generated docs were updated to match the existing flag description in cli/command/container/cp.go, but this PR also changes the flag description string in cp.go. Please update the PR description (or split commits) so it’s clear whether the source-of-truth changed vs. docs-only regeneration.

Copilot uses AI. Check for mistakes.
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 18, 2026

Choose a reason for hiding this comment

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

PR metadata/title indicate this is a docs-only update for docker cp --archive, but this diff also changes CLI behavior (DisplayablePorts output) and other unrelated flag/help text. Please either split these unrelated changes into separate PRs or update the PR title/description to reflect the additional behavior changes so reviewers can assess them appropriately.

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 {
Copy link

Copilot AI Apr 18, 2026

Choose a reason for hiding this comment

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

port.IP.String() == "0.0.0.0" is a fragile way to detect the IPv4 wildcard. Since port.IP is a netip.Addr, prefer checking via address properties (e.g., port.IP.Is4() && port.IP.IsUnspecified()) to avoid string-based logic and to keep the intent clear.

Suggested change
if port.IP.String() == "0.0.0.0" && port.PublicPort != 0 {
if port.IP.Is4() && port.IP.IsUnspecified() && port.PublicPort != 0 {

Copilot uses AI. Check for mistakes.
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 18, 2026

Choose a reason for hiding this comment

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

New behavior to suppress IPv6 wildcard bindings when an IPv4 wildcard exists isn’t covered by existing TestDisplayablePorts cases. Please add a test case exercising a dual-stack wildcard publish (e.g., 0.0.0.0:8080->80/tcp plus :::8080->80/tcp, and also consider -p 80:80 where PublicPort == PrivatePort) to prevent regressions.

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 choosing the output format so it also
// suppresses dual-stack wildcard publishes where
// PublicPort == PrivatePort (for example: -p 80:80).
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>")`)

return cmd
}
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/commandline/container_cp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 (preserve uid/gid from source when copying to container) |
| `-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 |

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/commandline/cp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 (preserve uid/gid from source when copying to container) |
| `-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 |

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. |
| `-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
> 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