# `Stevedore.Mutate`
[🔗](https://github.com/oshlabs/stevedore/blob/v0.2.0/lib/stevedore/mutate.ex#L1)

Rewrite an assembled `Stevedore.Image` — config, annotations, tag, base, or layer set — without
re-pulling layers where possible. Every mutation recomputes the dependent digests through
`Stevedore.Image.assemble/3`; bytes that don't change keep their digests.

Spec: crane `mutate`/`rebase`/`flatten` semantics
(<https://github.com/google/go-containerregistry/tree/main/cmd/crane>) and OCI image-spec
`config.md`/`layer.md`.

# `annotations`

```elixir
@spec annotations(Stevedore.Image.t(), map()) :: Stevedore.Image.t()
```

Merges `annotations` into the manifest's annotations. Config and layers are untouched.

# `config`

```elixir
@spec config(
  Stevedore.Image.t(),
  map() | (Stevedore.Config.t() -&gt; Stevedore.Config.t())
) ::
  Stevedore.Image.t()
```

Rewrites the runtime config. `changes` is a map of `:entrypoint`/`:cmd`/`:env`/`:user`/
`:working_dir`/`:labels` (labels are merged, the rest replaced) or a `(Config.t -> Config.t)`
function. Layers are untouched.

# `flatten`

```elixir
@spec flatten(
  Stevedore.Image.t(),
  keyword()
) :: {:ok, Stevedore.Image.t()} | {:error, term()}
```

Flattens all layers into a single layer, applying whiteouts (`.wh.<name>` deletions and
`.wh..wh..opq` opaque dirs) so the result is the effective filesystem. The runtime config is
preserved.

# `rebase`

```elixir
@spec rebase(Stevedore.Image.t(), Stevedore.Image.t(), Stevedore.Image.t()) ::
  {:ok, Stevedore.Image.t()} | {:error, :base_mismatch}
```

Rebases `image` from `old_base` onto `new_base`: the bottom layers matching `old_base` are
swapped for `new_base`'s layers, keeping the application layers on top. Fails with
`:base_mismatch` if `image` doesn't actually start with `old_base`'s layers.

# `retag`

```elixir
@spec retag(Stevedore.Image.t(), String.t()) :: Stevedore.Image.t()
```

Sets the tag the image will be written under by a subsequent copy.

---

*Consult [api-reference.md](api-reference.md) for complete listing*