Work with the Host Filesystem

Introduction

This guide explains how to work with the host filesystem using the Dagger Go SDK. You will learn how to:

Set the working directory on the host
List host directory entries with include/exclude filters
Mount a host directory in a container
Export a directory from a container to the host

Requirements

This guide assumes that:

You have a Go development environment with Go 1.15 or later. If not, download and install Go.
You have Docker installed and running on the host system. If not, install Docker.
You have a Go module with the Dagger Go SDK installed. If not, install the Dagger Go SDK.

Set the host working directory

The easiest way to set the working directory on the host for your Go CI pipeline is at the time of client instantiation, with the client's WithWorkdir() option.

The following example shows how to set the host working directory:

package main

import (
    "context"
    "log"

    "dagger.io/dagger"
)

func main() {
    ctx := context.Background()

    client, err := dagger.Connect(ctx, dagger.WithWorkdir("."))
    if err != nil {
        log.Println(err)
        return
    }

    defer client.Close()
}

List directory contents

The Host type provides information about the host's execution environment. Its Directory() method accepts a path and returns a reference to the corresponding host directory as a Directory struct. There's also a shortcut Workdir() method, which returns a reference to the current working directory on the host. Entries in the directory can be obtained via the Directory.Entries() function.

The following example shows how to list the contents of the host working directory:

package main

import (
    "context"
    "fmt"
    "log"

    "dagger.io/dagger"
)

func main() {
    ctx := context.Background()

    client, err := dagger.Connect(ctx, dagger.WithWorkdir("."))
    if err != nil {
        log.Println(err)
        return
    }
    defer client.Close()

    entries, err := client.Host().Directory(".").Entries(ctx)
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(entries)
}

List directory contents with filters

It's possible to restrict a Directory to a subset of directory entries, by specifying a list of filename patterns to include or exclude.

The following example shows how to obtain a reference to the host working directory containing only *.rar files:

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "path/filepath"

    "dagger.io/dagger"
)

func main() {
    dir := os.TempDir()
    os.WriteFile(filepath.Join(dir, "foo.txt"), []byte("1"), 0600)
    os.WriteFile(filepath.Join(dir, "bar.txt"), []byte("2"), 0600)
    os.WriteFile(filepath.Join(dir, "baz.rar"), []byte("3"), 0600)

    ctx := context.Background()

    client, err := dagger.Connect(ctx, dagger.WithWorkdir(dir))
    if err != nil {
        log.Println(err)
        return
    }
    defer client.Close()

    entries, err := client.Host().Directory(".", dagger.HostDirectoryOpts{
        Include: []string{"*.rar"},
    }).Entries(ctx)
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(entries)
}

The following example shows how to obtain a reference to the host working directory containing all files except *.txt files:

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "path/filepath"

    "dagger.io/dagger"
)

func main() {
    dir := os.TempDir()
    os.WriteFile(filepath.Join(dir, "foo.txt"), []byte("1"), 0600)
    os.WriteFile(filepath.Join(dir, "bar.txt"), []byte("2"), 0600)
    os.WriteFile(filepath.Join(dir, "baz.rar"), []byte("3"), 0600)

    ctx := context.Background()

    client, err := dagger.Connect(ctx, dagger.WithWorkdir(dir))
    if err != nil {
        log.Println(err)
        return
    }
    defer client.Close()

    entries, err := client.Host().Directory(".", dagger.HostDirectoryOpts{
        Exclude: []string{"*.txt"},
    }).Entries(ctx)
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(entries)
}

The Exclude pattern overrides the Include pattern, but not vice-versa. The following example demonstrates by obtaining a reference to the host working directory containing all files except *.rar files:

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "path/filepath"

    "dagger.io/dagger"
)

func main() {
    dir := os.TempDir()
    os.WriteFile(filepath.Join(dir, "foo.txt"), []byte("1"), 0600)
    os.WriteFile(filepath.Join(dir, "bar.txt"), []byte("2"), 0600)
    os.WriteFile(filepath.Join(dir, "baz.rar"), []byte("3"), 0600)

    ctx := context.Background()

    client, err := dagger.Connect(ctx, dagger.WithWorkdir(dir))
    if err != nil {
        log.Println(err)
        return
    }
    defer client.Close()

    entries, err := client.Host().Directory(".", dagger.HostDirectoryOpts{
        Include: []string{"*.*"},
        Exclude: []string{"*.rar"},
    }).Entries(ctx)
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(entries)
}

Mount a host directory in a container

A common operation when working with containers is to mount a host directory to a path in the container and then perform operations on it. This can be done using the Container.WithMountedDirectory() method, which accepts the mount point in the container and the Directory to be mounted as arguments.

The following example shows how to mount a host directory in a container at the /host container path and then execute a command in the container referencing the mounted directory:

package main

import (
    "context"
    "fmt"
    "log"

    "dagger.io/dagger"
)

func main() {
    ctx := context.Background()

    client, err := dagger.Connect(ctx, dagger.WithWorkdir("."))
    if err != nil {
        log.Println(err)
        return
    }
    defer client.Close()

    contents, err := client.Container().
        From("alpine:latest").
        WithMountedDirectory("/host", client.Host().Directory(".")).
        WithExec([]string{"ls", "/host"}).
        Stdout(ctx)
    if err != nil {
        log.Println(err)
        return
    }

    fmt.Println(contents)
}

Export a directory from a container to the host

A directory can be exported to a different path using the Directory.Export() method. The destination path is supplied to the method as an argument.

The following example creates a file in a container's /tmp directory and then exports the contents of that directory to the host's temporary directory:

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "path/filepath"

    "dagger.io/dagger"
)

func main() {
    hostdir := os.TempDir()

    ctx := context.Background()

    client, err := dagger.Connect(ctx)
    if err != nil {
        log.Println(err)
        return
    }
    defer client.Close()

    _, err = client.Container().From("alpine:latest").
        WithWorkdir("/tmp").
        WithExec([]string{"wget", "https://dagger.io"}).
        Directory(".").
        Export(ctx, hostdir)
    if err != nil {
        log.Println(err)
        return
    }
    contents, err := os.ReadFile(filepath.Join(hostdir, "index.html"))
    if err != nil {
        log.Println(err)
        return
    }
    fmt.Println(string(contents))
}

Conclusion

This guide introduced you to the functions available in the Dagger Go SDK to work with the host filesystem. It provided explanations and code samples demonstrating how to set the host working directory, read directory contents (with and without pathname filters), mount a host directory in a container and export a directory from a container to the host.

Use the SDK Reference to learn more about the Dagger Go SDK.

Work with the Host Filesystem

Introduction​

Requirements​

Set the host working directory​

List directory contents​

List directory contents with filters​

Mount a host directory in a container​

Export a directory from a container to the host​

Conclusion​