slug

README

go-slug

Package go-slug offers functions for packing and unpacking Terraform Enterprise compatible slugs. Slugs are gzip compressed tar files containing Terraform configuration files.

Installation

Installation can be done with a normal go get:

go get -u github.com/hashicorp/go-slug

Documentation

For the complete usage of go-slug, see the full package docs.

Example

Packing or unpacking a slug is pretty straight forward as shown in the following example:

package main

import (
	"bytes"
	"io/ioutil"
	"log"
	"os"

	slug "github.com/hashicorp/go-slug"
)

func main() {
	// First create a buffer for storing the slug.
	buf := bytes.NewBuffer(nil)

	// Then call the Pack function with a directory path containing the
	// configuration files and an io.Writer to write the slug to.
	if _, err := slug.Pack("testdata/archive-dir", buf, false); err != nil {
		log.Fatal(err)
	}

	// Create a directory to unpack the slug contents into.
	dst, err := ioutil.TempDir("", "slug")
	if err != nil {
		log.Fatal(err)
	}
	defer os.RemoveAll(dst)

	// Unpacking a slug is done by calling the Unpack function with an
	// io.Reader to read the slug from and a directory path of an existing
	// directory to store the unpacked configuration files.
	if err := slug.Unpack(buf, dst); err != nil {
		log.Fatal(err)
	}
}

Issues and Contributing

If you find an issue with this package, please report an issue. If you'd like, we welcome any contributions. Fork this repository and submit a pull request.

Documentation

Index

• func Unpack(r io.Reader, dst string) error
• type IllegalSlugError
  • func (e *IllegalSlugError) Error() string
  • func (e *IllegalSlugError) Unwrap() error
• type Meta
  • func Pack(src string, w io.Writer, dereference bool) (*Meta, error)
• type Packer
  • func NewPacker(options ...PackerOption) (*Packer, error)
  • func (p *Packer) Pack(src string, w io.Writer) (*Meta, error)
• type PackerOption
  • func ApplyTerraformIgnore() PackerOption
  • func DereferenceSymlinks() PackerOption

Functions

func Unpack

func Unpack(r io.Reader, dst string) error

Unpack is used to read and extract the contents of a slug to the dst directory. Symlinks within the slug are supported, provided their targets are relative and point to paths within the destination directory.

Types

type IllegalSlugError

type IllegalSlugError struct {
	Err error
}

IllegalSlugError indicates the provided slug (io.Writer for Pack, io.Reader for Unpack) violates a rule about its contents. For example, an absolute or external symlink. It implements the error interface.

func (*IllegalSlugError) Error

func (e *IllegalSlugError) Error() string

func (*IllegalSlugError) Unwrap

func (e *IllegalSlugError) Unwrap() error

Unwrap returns the underlying issue with the provided Slug into the error chain.

type Meta

type Meta struct {
	// The list of files contained in the slug.
	Files []string

	// Total size of the slug in bytes.
	Size int64
}

Meta provides detailed information about a slug.

func Pack

func Pack(src string, w io.Writer, dereference bool) (*Meta, error)

Pack at the package level is used to maintain compatibility with existing code that relies on this function signature. New options related to packing slugs should be added to the Packer struct instead.

type Packer

type Packer struct {
	// contains filtered or unexported fields
}

Packer holds options for the Pack function.

func NewPacker

func NewPacker(options ...PackerOption) (*Packer, error)

NewPacker is a constructor for Packer.

func (*Packer) Pack

func (p *Packer) Pack(src string, w io.Writer) (*Meta, error)

Pack creates a slug from a src directory, and writes the new slug to w. Returns metadata about the slug and any errors.

When dereference is set to true, symlinks with a target outside of the src directory will be dereferenced. When dereference is set to false symlinks with a target outside the src directory are omitted from the slug.

type PackerOption

type PackerOption func(*Packer) error

PackerOption is a functional option that can configure non-default Packers.

func ApplyTerraformIgnore

func ApplyTerraformIgnore() PackerOption

ApplyTerraformIgnore is a PackerOption that will apply the .terraformignore rules and skip packing files it specifies.

func DereferenceSymlinks

func DereferenceSymlinks() PackerOption

DereferenceSymlinks is a PackerOption that will allow symlinks that reference a target outside of the src directory.