docs: clarify that ENTRYPOINT discards an inherited CMD

[basisworks]

Closes the documentation half of moby/moby#35027 (open since 2017, no replies).

The gap

The reference already carries a short note under Understand how CMD and ENTRYPOINT interact:

If CMD is defined from the base image, setting ENTRYPOINT will reset CMD to an empty value. In this scenario, CMD must be defined in the current image to have a value.

That's correct but under-specified, and it lives at the bottom of a section a reader only reaches if they already suspect the interaction exists. Two things it doesn't say:

1. The rule is scoped to the build stage, not the image — "current image" is ambiguous in a multi-stage file.
2. Order doesn't matter. A CMD in the same stage survives whether it is written before or after ENTRYPOINT. Readers reasonably assume ENTRYPOINT after CMD would clobber it.

Neither the ENTRYPOINT section nor the CMD section mentions the behavior at all, so the most common way to hit it — adding a wrapper entrypoint to a base image that only sets CMD, like nginx — gives you an image that exits immediately with no obvious cause.

Behavior verified against the source

dispatchEntrypoint in frontend/dockerfile/dockerfile2llb/convert.go:

d.image.Config.Entrypoint = args
if !d.cmd.IsSet {
    d.image.Config.Cmd = nil
}

d.cmd.IsSet is set by MarkUsed from validateUsedOnce at the top of dispatchCmd, and dispatchState is per-stage. So:

• CMD then ENTRYPOINT → IsSet is true, CMD is preserved.
• ENTRYPOINT then CMD → CMD is cleared, then immediately reset by the CMD instruction.

Both orders keep a stage-local CMD; only an inherited one is dropped. The classic builder in moby/moby (daemon/builder/dockerfile/dispatchers.go) does the same thing via d.state.cmdSet, so the documented rule holds for both.

Changes

• Expanded the note to state the stage scoping and the order-independence.
• Added the wrapper-script example that motivates the rule, with the fix.
• Added one line under ENTRYPOINT pointing at the interaction section.

Docs only — no code or behavior change.

[dvdksn]

Suggested change

	Setting `ENTRYPOINT` also discards any `CMD` inherited from the base image,
	unless the same build stage defines its own `CMD`. For more information, see
	Setting `ENTRYPOINT` also discards any `CMD` inherited from the base image.
	For more information, see

[dvdksn]

I'd rather drop this since it's irrelevant.

Suggested change

	> have one. The order of the two instructions doesn't matter: a `CMD` in the
	> same stage is kept whether it appears before or after `ENTRYPOINT`.
	> have one.

[dvdksn]

I think this is too specific for the Dockerfile reference. The note above already documents the general behavior. This turns that into troubleshooting for one particular wrapper-script pattern.

Can we remove this example and the inspection command, and keep the concise explanation of the inherited CMD behavior above? If this needs a worked example, a synthetic base image would demonstrate the rule more accurately, but I don’t think the reference needs that level of detail.