dog

README

Dog

Dog is a command line application that executes automated tasks.

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 specification will be finished (no further breaking changes) by the v1.0.0 version of Dog.

• Read Dog's own dog.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 FindDogfiles(p string) ([]string, error)
• type Dogtasks
  • func Parse(p []byte) (dtasks Dogtasks, err error)
  • func ParseFromDisk(dir string) (dtasks Dogtasks, err error)
  • func (dtasks *Dogtasks) Validate() error
• type Task
• type TaskChain
  • func NewTaskChain(dtasks Dogtasks, task string) (taskChain TaskChain, err error)
  • func (taskChain *TaskChain) Run(stdout, stderr io.Writer) error

Variables

var DefaultRunner = "sh"

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

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 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 Dogtasks

type Dogtasks 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 Dogtasks object.
	Files []string
}

Dogtasks is a collection of tasks with optional metadata from the runtime.

func Parse

func Parse(p []byte) (dtasks Dogtasks, err error)

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

func ParseFromDisk

func ParseFromDisk(dir string) (dtasks Dogtasks, err error)

ParseFromDisk finds a Dogfile in disk and parses it.

func (*Dogtasks) Validate

func (dtasks *Dogtasks) Validate() error

Validate checks that all tasks in a Dogfile are valid.

It checks if any task has a non standard name and also if the resulting task chain of each of them have an undesired cycle.

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

	// Register stores the output of the task so it can be accessed by
	// other tasks in the task chain.
	//
	// When present, a new environment variable is injected in future
	// task chain runners using the register name as key and the output
	// as value.
	Register string
}

Task represents a task described in the Dogfile format.

type TaskChain

type TaskChain struct {
	Tasks []Task
}

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

func NewTaskChain

func NewTaskChain(dtasks Dogtasks, task string) (taskChain TaskChain, err error)

NewTaskChain creates the task chain for a specific dogfile and task.

func (*TaskChain) Run

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

Run handles the execution of all tasks in the TaskChain.