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