README.md

Documentation: github.com/google/go-containerregistry/pkg/v1/mutate

     1# `mutate`
     2
     3[![GoDoc](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/mutate?status.svg)](https://godoc.org/github.com/google/go-containerregistry/pkg/v1/mutate)
     4
     5The `v1.Image`, `v1.ImageIndex`, and `v1.Layer` interfaces provide only
     6accessor methods, so they are essentially immutable. If you want to change
     7something about them, you need to produce a new instance of that interface.
     8
     9A common use case for this library is to read an image from somewhere (a source),
    10change something about it, and write the image somewhere else (a sink).
    11
    12Graphically, this looks something like:
    13
    14<p align="center">
    15  <img src="/images/mutate.dot.svg" />
    16</p>
    17
    18## Mutations
    19
    20This is obviously not a comprehensive set of useful transformations (PRs welcome!),
    21but a rough summary of what the `mutate` package currently does:
    22
    23### `Config` and `ConfigFile`
    24
    25These allow you to change the [image configuration](https://github.com/opencontainers/image-spec/blob/master/config.md#properties),
    26e.g. to change the entrypoint, environment, author, etc.
    27
    28### `Time`, `Canonical`, and `CreatedAt`
    29
    30These are useful in the context of [reproducible builds](https://reproducible-builds.org/),
    31where you may want to strip timestamps and other non-reproducible information.
    32
    33### `Append`, `AppendLayers`, and `AppendManifests`
    34
    35These functions allow the extension of a `v1.Image` or `v1.ImageIndex` with
    36new layers or manifests.
    37
    38For constructing an image `FROM scratch`, see the [`empty`](/pkg/v1/empty) package.
    39
    40### `MediaType` and `IndexMediaType`
    41
    42Sometimes, it is necessary to change the media type of an image or index,
    43e.g. to appease a registry with strict validation of images (_looking at you, GCR_).
    44
    45### `Rebase`
    46
    47Rebase has [its own README](/cmd/crane/rebase.md).
    48
    49This is the underlying implementation of [`crane rebase`](https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_rebase.md).
    50
    51### `Extract`
    52
    53Extract will flatten an image filesystem into a single tar stream,
    54respecting whiteout files.
    55
    56This is the underlying implementation of [`crane export`](https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_export.md).
View as plain text