dog

README

Dog

Dog is a command line application that executes automated tasks. It works in a similar way as GNU Make but it is a more generic task runner, not a build tool. Dog's default script syntax is sh but most interpreted languages like BASH, Python or Ruby can also be used.

Using Dog

List all tasks in current project

dog

Execute a task

dog taskname

Execute a task, printing elapsed time and exit status

dog -i taskname

What is a Dogfile?

Dogfile is a specification that uses YAML to describe the tasks related to a project. We think that the Spec will be finished (no further breaking changes) by the v1.0.0 version of Dog.

• Read Dog's own Dogfile.yml
• Read the Dogfile Spec

Installing Dog

If you are using macOS you can install Dog using brew:

brew tap dogtools/dog
brew install dog

If you have your golang environment set up, you can use:

go get -u github.com/dogtools/dog

Other tools

Tools that use the Dogfile Specification are called dogtools. Dog is the first dogtool but there are other things that can be implemented in the future: web and desktop UIs, chat bot interfaces, plugins for text editors and IDEs, tools to export Dogfiles to other formats, HTTP API interfaces, even implementations of the cli in other languages!

The root directory of this repository contains the dog package that can be used to create dogtools in Go.

import "github.com/dogtools/dog"

Check the examples/ directory to see how it works.

Contributing

If you want to help, take a look at the open bugs, the list of all issues and our Code of Conduct.

Documentation

Index

• Variables
• func DeprecationWarnings(w io.Writer)
• func FindDogfiles(p string) ([]string, error)
• type Dogfile
  • func (d *Dogfile) Parse(p []byte) error
  • func (d *Dogfile) ParseFromDisk(dir string) error
  • func (d *Dogfile) Validate() error
• type Task
  • func (t *Task) Validate() error
• type TaskChain
  • func (taskChain *TaskChain) Generate(d Dogfile, task string) error
  • func (taskChain *TaskChain) Run(stdout, stderr io.Writer) error

Variables

var DefaultRunner string

DefaultRunner defines the runner to use in case the task does not specify it.

The value is automatically assigned based on the operating system when the package initializes.

var ErrCycleInTaskChain = errors.New("TaskChain includes a cycle of tasks")

ErrCycleInTaskChain means that there is a loop in the path of tasks execution.

var ErrMalformedStringArray = errors.New("Malformed strings array")

ErrMalformedStringArray means that a task have a value of pre, post or env that can't be parsed as an array of strings.

var ErrNoDogfile = errors.New("No dogfile found")

ErrNoDogfile means that the application is unable to find a Dogfile in the specified directory.

var ProvideExtraInfo bool

ProvideExtraInfo specifies if dog needs to provide execution info (duration, exit status) after task execution.

Functions

func DeprecationWarnings

func DeprecationWarnings(w io.Writer)

DeprecationWarnings writes deprecation warnings if they have been found on parse time.

Call it with os.Stderr as a parameter to print warnings to STDERR.

func FindDogfiles

func FindDogfiles(p string) ([]string, error)

FindDogfiles finds Dogfiles in disk for a given path.

It traverses directories until it finds one containing Dogfiles. If such a directory is found, the function returns the full path for each valid Dogfile in that directory.

Types

type Dogfile

type Dogfile struct {

	// Tasks is used to map task objects by their name.
	Tasks map[string]*Task

	// Path is an optional field that stores the directory
	// where the Dogfile is found.
	Path string

	// Files is an optional field that stores the full path
	// of each Dogfile used to define the Dogfile object.
	Files []string
}

Dogfile contains tasks defined in the Dogfile format.

func (*Dogfile) Parse

func (d *Dogfile) Parse(p []byte) error

Parse accepts a slice of bytes and parses it following the Dogfile Spec.

func (*Dogfile) ParseFromDisk

func (d *Dogfile) ParseFromDisk(dir string) error

ParseFromDisk finds a Dogfile in disk and parses it.

func (*Dogfile) Validate

func (d *Dogfile) Validate() error

Validate checks that all tasks in a Dogfile are valid.

type Task

type Task struct {
	// Name of the task.
	Name string

	// Description of the task.
	Description string

	// The code that will be executed.
	Code string

	// Defaults to operating system main shell.
	Runner string

	// Pre-hooks execute other tasks before starting the current one.
	Pre []string

	// Post-hooks are analog to pre-hooks but they are executed after
	// current task finishes its execution.
	Post []string

	// Default values for environment variables can be provided in the Dogfile.
	// They can be modified at execution time.
	Env []string

	// Sets the working directory for the task. Relative paths are
	// considered relative to the location of the Dogfile.
	Workdir string
}

Task represents a task described in the Dogfile format.

func (*Task) Validate

func (t *Task) Validate() error

Validate runs a series of validations against a task.

It checks if it has a non standard name and also if the resulting task chain have undesired cycles.

type TaskChain

type TaskChain struct {
	Tasks []*Task
}

TaskChain contains one or more tasks to be executed in order.

func (*TaskChain) Generate

func (taskChain *TaskChain) Generate(d Dogfile, task string) error

Generate creates the TaskChain for a specific task.

func (*TaskChain) Run

func (taskChain *TaskChain) Run(stdout, stderr io.Writer) error

Run handles the execution of all tasks in the TaskChain.