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.