Skip to main content
Version: Next

Image

The Image type provides methods for reading files from a remote OCI image without downloading the entire blob.

Obtaining an Image​

Images are created via Client.OpenImage:

img, err := client.OpenImage(ctx, "ghcr.io/org/config:v1")
if err != nil {
    return err
}
defer img.Close()

Always call Close() when done to release resources.

Methods​

List​

func (img *Image) List() ([]FileEntry, error)

Returns all files in the image.

Returns:

TypeDescription
[]FileEntrySlice of file entries
errorError if listing fails

Example:

entries, err := img.List()
if err != nil {
    return err
}

for _, entry := range entries {
    fmt.Printf("%s: %d bytes\n", entry.Path(), entry.Size())
}

Open​

func (img *Image) Open(path string) (io.ReadCloser, error)

Opens a specific file for reading.

Parameters:

NameTypeDescription
pathstringFile path within the image

Returns:

TypeDescription
io.ReadCloserReader for file contents
errorError if file not found or read fails

Example:

rc, err := img.Open("config.yaml")
if err != nil {
    return err
}
defer rc.Close()

content, err := io.ReadAll(rc)

Walk​

func (img *Image) Walk(fn fs.WalkDirFunc) error

Walks the file tree, calling fn for each file or directory.

Parameters:

NameTypeDescription
fnfs.WalkDirFuncCallback function

Returns:

TypeDescription
errorError from callback or walk failure

Example:

err := img.Walk(func(path string, d fs.DirEntry, err error) error {
    if err != nil {
        return err
    }
    if !d.IsDir() {
        info, _ := d.Info()
        fmt.Printf("%s: %d bytes\n", path, info.Size())
    }
    return nil
})

Close​

func (img *Image) Close() error

Releases resources associated with the image.

Returns:

TypeDescription
errorError if close fails

Example:

defer img.Close()

FileEntry​

Files returned by List() implement fs.DirEntry:

type FileEntry struct {
    // ...
}

func (f FileEntry) Name() string      // Base name
func (f FileEntry) Path() string      // Full path
func (f FileEntry) Size() int64       // Size in bytes
func (f FileEntry) Mode() fs.FileMode // File mode
func (f FileEntry) IsDir() bool       // Always false for files
func (f FileEntry) Type() fs.FileMode // File type bits
func (f FileEntry) Info() (fs.FileInfo, error)

Example:

entries, _ := img.List()
for _, e := range entries {
    fmt.Printf("%s: %d bytes, mode %o\n", e.Path(), e.Size(), e.Mode())
}

Thread Safety​

The Image type is safe for concurrent use. Multiple goroutines can call List(), Open(), and Walk() simultaneously.

See Also​