From c86790ce58ed0d6b6145bcfa842e4dd06eb7eafa Mon Sep 17 00:00:00 2001 From: Nicolas De Loof Date: Wed, 28 Oct 2026 15:52:55 +0100 Subject: [PATCH] docs(api): document the zero values, replica selection and the meaning of All An options struct left at its zero value does not always behave like the matching command run without flags, because the CLI fills in some defaults before calling the API (Inherit is the sharpest case: its zero value is the opposite of the CLI default). Index 0 and All also mean different things depending on the operation. Describe them in a package comment, and on the fields they concern. No code change. Signed-off-by: Nicolas De Loof --- pkg/api/api.go | 27 ++++++++++++----- pkg/api/doc.go | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 101 insertions(+), 8 deletions(-) create mode 100644 pkg/api/doc.go diff --git a/pkg/api/api.go b/pkg/api/api.go index a37c0cfec..03cc5cda7 100644 --- a/pkg/api/api.go +++ b/pkg/api/api.go @@ -348,11 +348,17 @@ type CreateOptions struct { RemoveOrphans bool // Ignore legacy containers for services that are not defined in the project IgnoreOrphans bool - // Recreate define the strategy to apply on existing containers + // Recreate define the strategy to apply on existing containers: one of + // RecreateDiverged (the default, also used for ""), RecreateForce or + // RecreateNever. Recreate string - // RecreateDependencies define the strategy to apply on dependencies services + // RecreateDependencies define the strategy to apply on dependencies + // services, with the same values as Recreate. RecreateDependencies string - // Inherit reuse anonymous volumes from previous container + // Inherit reuse anonymous volumes from previous container. Beware that + // the zero value (false) recreates the anonymous volumes of the containers + // that get recreated, like `up --renew-anon-volumes` does for them: set it + // to true to get what the CLI does by default. Inherit bool // Timeout set delay to wait for container to gracefully stop before sending SIGKILL Timeout *time.Duration @@ -643,12 +649,16 @@ func (e Event) String() string { // ListOptions group options of the ls API type ListOptions struct { + // All takes stopped containers into account, so that a project whose + // containers are all stopped is listed All bool } // PsOptions group options of the Ps API type PsOptions struct { - Project *types.Project + Project *types.Project + // All includes the stopped containers and the one-off containers, which + // are both left out by default All bool Services []string } @@ -657,10 +667,11 @@ type PsOptions struct { type CopyOptions struct { Source string Destination string - All bool - Index int - FollowLink bool - CopyUIDGID bool + // All includes the one-off containers of the service + All bool + Index int + FollowLink bool + CopyUIDGID bool } // PortPublisher hold status about published port diff --git a/pkg/api/doc.go b/pkg/api/doc.go new file mode 100644 index 000000000..65f3ae04a --- /dev/null +++ b/pkg/api/doc.go @@ -0,0 +1,82 @@ +/* + Copyright 2020 Docker Compose CLI authors + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +// Package api is the contract between the Compose engine and the programs +// that drive it: the compose CLI, and any third-party software using Compose +// as a library (see [Compose]). +// +// # Zero values +// +// An option struct left at its zero value does NOT always behave like the +// matching `docker compose` command run without flags: the CLI fills in some +// defaults before calling the API. The fields where the difference matters +// are listed here; each one is also documented on the field itself. +// +// - [CreateOptions].Inherit: false recreates the anonymous volumes of +// recreated containers, as `up --renew-anon-volumes` does for them (the +// flag also forces the recreation of every container). The CLI default +// is to retrieve their data from the previous container (Inherit: true). +// - [CreateOptions].Recreate and RecreateDependencies: the empty string +// means [RecreateDiverged], and so does any value that is not one of the +// Recreate* constants. +// - [CreateOptions].RemoveOrphans and IgnoreOrphans: when both are false, +// orphan containers are kept and a warning is logged. IgnoreOrphans +// silences that warning, RemoveOrphans removes the containers. +// - Timeout, on every options struct that has one: nil leaves the choice to +// the engine, which applies the stop timeout of the container (the +// service's stop_grace_period) or its own default. +// - [StartOptions].WaitTimeout: 0 means no time limit on dependency waits. +// - [StartOptions].Attach: nil selects the detached mode of Up, a non-nil +// consumer selects the interactive session. See [UpOptions.Validate] for +// the options that only make sense in one of the two modes. +// - Project, on the options of operations that take a project name: for +// Start, Stop, Restart, Kill and Down, nil means the project is rebuilt +// from the labels of its containers. Pause and Logs only use it to narrow +// the services; Remove does too, and forwards it to Stop when Stop is set +// (nil then means the same rebuild). Ps and Attach ignore it. +// - Services, when empty: every service of the project, subject to what the +// field documents (in some options it is not a filter). +// - [DownOptions].Images: the zero value, [ImagePruneNone], keeps every image. +// +// # Replica selection +// +// The Index field of the options of exec, port, export, commit, attach, logs +// and cp selects a replica by its container number, starting at 1. Index 0 +// means "no particular replica", and what that gives depends on the +// operation: +// +// - exec, port, export, commit and attach act on one container: the one +// with the lowest number, one-off containers coming last; +// - logs reads the containers of every selected service, one-off containers +// excluded; +// - cp copies from the first container of the service, or to every +// container of the service when copying to it. One-off containers are +// excluded unless All is set, and All only applies when Index is 0: a +// given replica is looked up among the regular containers. +// +// # The word All +// +// The boolean All field has a different meaning in each options struct, and +// is always documented there: +// +// - [ListOptions]: takes stopped containers into account, so that a +// project whose containers are all stopped is listed; +// - [PsOptions]: includes the stopped containers and the one-off ones; +// - [KillOptions]: also targets the containers that are not running (the +// one-off ones are targeted either way); +// - [CopyOptions]: includes the one-off containers of the service; +// - [ProjectLoadOptions]: includes the resources no service uses. +package api