shx

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 25, 2022 License: MIT Imports: 11 Imported by: 11

Documentation

Overview

Extend the github.com/magefile/mage/sh package with helper functions to run commands in a magefile.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Copy added in v0.5.0 

func Copy(src string, dest string, opts ...CopyOption) error

Copy a file or directory with the specified set of CopyOption. The source may use globbing, which is resolved with filepath.Glob. Notes:

  • Does not copy file owner/group.
Example 
package main

import (
	"github.com/carolynvs/magex/shx"
)

func main() {
	// Copy a file from the current directory into TEMP
	shx.Copy("a.txt", "/tmp")

	// Copy matching files in the current directory into TEMP
	shx.Copy("*.txt", "/tmp")

	// Overwrite a file
	shx.Copy("/tmp/a.txt", "/tmp/b.txt")

	// Copy the contents of a directory into TEMP
	// Do not overwrite existing files
	shx.Copy("a/*", "/tmp", shx.CopyNoOverwrite)

	// Recursively copy a directory into TEMP
	shx.Copy("a", "/tmp", shx.CopyRecursive)
}

Output:

func Move added in v0.9.0 

func Move(src string, dest string, opts ...MoveOption) error

Move a file or directory with the specified set of MoveOption. The source may use globbing, which is resolved with filepath.Glob.

Example 
package main

import (
	"github.com/carolynvs/magex/shx"
)

func main() {
	// Move a file from the current directory into TEMP
	shx.Move("a.txt", "/tmp")

	// Move matching files in the current directory into TEMP
	shx.Move("*.txt", "/tmp")

	// Overwrite a file
	shx.Move("/tmp/a.txt", "/tmp/b.txt")

	// Move the contents of a directory into TEMP
	// Do not overwrite existing files
	shx.Move("a/*", "/tmp", shx.MoveNoOverwrite)
}

Output:

func Output added in v0.4.0 

func Output(cmd string, args ...string) (string, error)

Output executes the prepared command, returning stdout.

Example 
package main

import (
	"log"

	"github.com/carolynvs/magex/shx"
)

func main() {
	// The output is printed only when mage -v is set
	output, err := shx.Output("go", "run", "echo.go", "hello world")
	if err != nil {
		log.Fatal(err)
	}

	if output != "hello world" {
		log.Fatal("expected to capture the output of the command")
	}

}

Output:

func OutputE 

func OutputE(cmd string, args ...string) (string, error)

OutputE is like Output, but it only writes the command's output to os.Stderr when it fails.

Example 
package main

import (
	"log"

	"github.com/carolynvs/magex/shx"
)

func main() {
	// Nothing should print when the command succeeds printed because the command passed
	output, err := shx.OutputE("go", "run", "echo.go", "hello world")
	if err != nil {
		log.Fatal(err)
	}

	if output != "hello world" {
		log.Fatal("expected to capture the output of the command")
	}

}

Output:

func OutputS 

func OutputS(cmd string, args ...string) (string, error)

Outputs is like Output, but nothing is written to stdout/stderr.

Example 
package main

import (
	"log"

	"github.com/carolynvs/magex/shx"
)

func main() {
	// Never write to stdout/stderr, just capture the output in a variable
	output, err := shx.OutputS("go", "run", "echo.go", "hello world")
	if err != nil {
		log.Fatal(err)
	}

	if output != "hello world" {
		log.Fatal(`expected to capture the output of the command`)
	}

}

Output:

func OutputV added in v0.4.0 

func OutputV(cmd string, args ...string) (string, error)

OutputV is like Output, but it always writes the command's stdout to os.Stdout.

Example 
package main

import (
	"log"

	"github.com/carolynvs/magex/shx"
)

func main() {
	// The output is printed every time
	output, err := shx.OutputV("go", "run", "echo.go", "hello world")
	if err != nil {
		log.Fatal(err)
	}

	if output != "hello world" {
		log.Fatal("expected to capture the output of the command")
	}

}

Output:

hello world

func RecordStderr added in v0.4.0 

func RecordStderr() *capture

RecordStderr records what is written to os.Stderr.

func RecordStdout added in v0.4.0 

func RecordStdout() *capture

RecordStdout records what is written to os.Stdout.

func Run added in v0.4.0 

func Run(cmd string, args ...string) error

Run the given command, directing stderr to this program's stderr and printing stdout to stdout if mage was run with -v.

Example 
package main

import (
	"log"

	"github.com/carolynvs/magex/shx"
)

func main() {
	// Only write to stdout when mage -v is set
	err := shx.RunS("go", "run", "echo.go", "hello world")
	if err != nil {
		log.Fatal(err)
	}

}

Output:

func RunE 

func RunE(cmd string, args ...string) error

RunE is like Run, but it only writes the command's output to os.Stderr when it fails.

Example 
package main

import (
	"log"

	"github.com/carolynvs/magex/shx"
)

func main() {
	// Only write to stderr when the command fails
	err := shx.RunE("go", "run")
	if err == nil {
		log.Fatal("expected the command to fail")
	}

}

Output:

func RunS 

func RunS(cmd string, args ...string) error

RunS is like Run, but the command output is not written to stdout/stderr.

Example 
package main

import (
	"log"

	"github.com/carolynvs/magex/shx"
)

func main() {
	// Do not write to stdout even when mage -v is set
	err := shx.RunS("go", "run", "echo.go", "hello world")
	if err != nil {
		log.Fatal(err)
	}

}

Output:

func RunV added in v0.4.0 

func RunV(cmd string, args ...string) error

RunV is like Run, but always writes the command's stdout to os.Stdout.

Example 
package main

import (
	"log"

	"github.com/carolynvs/magex/shx"
)

func main() {
	// Always print the output
	err := shx.RunV("go", "run", "echo.go", "hello world")
	if err != nil {
		log.Fatal(err)
	}

}

Output:

hello world

Types

type CommandBuilder added in v0.5.0 

type CommandBuilder struct {
	StopOnError bool
	Env         []string
	Dir         string
}

CommandBuilder creates PreparedCommand's with common configuration such as always stopping on errors, running a set of commands in a directory, or using a set of environment variables.

func (*CommandBuilder) Command added in v0.5.0 

func (b *CommandBuilder) Command(cmd string, args ...string) PreparedCommand

Command creates a command using common configuration.

func (*CommandBuilder) Output added in v0.5.0 

func (b *CommandBuilder) Output(cmd string, args ...string) (string, error)

Output executes the prepared command, returning stdout.

func (*CommandBuilder) OutputE added in v0.5.0 

func (b *CommandBuilder) OutputE(cmd string, args ...string) (string, error)

OutputE is like Output, but it only writes the command's output to os.Stderr when it fails.

func (*CommandBuilder) OutputS added in v0.5.0 

func (b *CommandBuilder) OutputS(cmd string, args ...string) (string, error)

Outputs is like Output, but nothing is written to stdout/stderr.

func (*CommandBuilder) OutputV added in v0.5.0 

func (b *CommandBuilder) OutputV(cmd string, args ...string) (string, error)

OutputV is like Output, but it always writes the command's stdout to os.Stdout.

func (*CommandBuilder) Run added in v0.5.0 

func (b *CommandBuilder) Run(cmd string, args ...string) error

Run the given command, directing stderr to this program's stderr and printing stdout to stdout if mage was run with -v.

func (*CommandBuilder) RunE added in v0.5.0 

func (b *CommandBuilder) RunE(cmd string, args ...string) error

RunE is like Run, but it only writes the command's output to os.Stderr when it fails.

func (*CommandBuilder) RunS added in v0.5.0 

func (b *CommandBuilder) RunS(cmd string, args ...string) error

RunS is like Run, but the command output is not written to stdout/stderr.

func (*CommandBuilder) RunV added in v0.5.0 

func (b *CommandBuilder) RunV(cmd string, args ...string) error

RunV is like Run, but always writes the command's stdout to os.Stdout.

type CopyOption added in v0.5.0 

type CopyOption int
const (
	CopyDefault CopyOption = iota
	// CopyNoOverwrite does not overwrite existing files in the destination
	CopyNoOverwrite
	CopyRecursive
)

type MoveOption added in v0.9.0 

type MoveOption int
const (
	MoveDefault MoveOption = iota
	// MoveNoOverwrite does not overwrite existing files in the destination
	MoveNoOverwrite
	MoveRecursive
)

type PreparedCommand added in v0.4.0 

type PreparedCommand struct {
	Cmd         *exec.Cmd
	StopOnError bool
}

func Command added in v0.4.0 

func Command(cmd string, args ...string) PreparedCommand

Command creates a default command. Stdout is logged in verbose mode. Stderr is sent to os.Stderr.

func (PreparedCommand) Args added in v0.4.0 

func (c PreparedCommand) Args(args ...string) PreparedCommand

Args appends additional arguments to the command.

Example 
package main

import (
	"log"

	"github.com/carolynvs/magex/shx"
)

func main() {
	cmd := shx.Command("go", "run", "echo.go")
	// Append arguments to the command
	err := cmd.Args("hello", "world").RunV()
	if err != nil {
		log.Fatal(err)
	}

}

Output:

hello world

func (PreparedCommand) CollapseArgs added in v0.4.0 

func (c PreparedCommand) CollapseArgs() PreparedCommand

CollapseArgs removes empty arguments from the argument list.

This is helpful when sometimes a flag should be specified and sometimes it shouldn't.

Example 
package main

import (
	"log"

	"github.com/carolynvs/magex/shx"
)

func main() {
	err := shx.Command("go", "run", "echo.go", "hello", "", "world").CollapseArgs().RunV()
	if err != nil {
		log.Fatal(err)
	}

}

Output:

hello world

func (PreparedCommand) Env added in v0.4.0 

func (c PreparedCommand) Env(vars ...string) PreparedCommand

Env defines additional environment variables for the command. All ambient environment variables are included by default. Example: 

c.Env("X=1", "Y=2")

func (PreparedCommand) Exec added in v0.4.0 

func (c PreparedCommand) Exec() (ran bool, code int, err error)

Exec the prepared command, returning if the command was run and its exit code. Does not modify the configured outputs.

func (PreparedCommand) In added in v0.4.0 

func (c PreparedCommand) In(dir string) PreparedCommand

In sets the working directory of the command.

Example 
package main

import (
	"io/ioutil"
	"log"
	"path/filepath"

	"github.com/carolynvs/magex/shx"
)

func main() {
	tmp, err := ioutil.TempDir("", "mage")
	if err != nil {
		log.Fatal(err)
	}

	contents := `package main

import "fmt"

func main() {
	fmt.Println("hello world")
}
`
	err = ioutil.WriteFile(filepath.Join(tmp, "test_main.go"), []byte(contents), 0644)
	if err != nil {
		log.Fatal(err)
	}

	// Run `go run test_main.go` in /tmp
	err = shx.Command("go", "run", "test_main.go").In(tmp).RunV()
	if err != nil {
		log.Fatal(err)
	}
}

Output:

hello world

func (PreparedCommand) Must added in v0.5.0 

func (c PreparedCommand) Must(stopOnError ...bool) PreparedCommand

Must immediately stops the build when the command fails.

func (PreparedCommand) Output added in v0.4.0 

func (c PreparedCommand) Output() (string, error)

Output executes the prepared command, directing stderr to os.Stderr and printing stdout to os.Stdout if mage was run with -v. The command's stdout is always returned.

func (PreparedCommand) OutputE added in v0.4.0 

func (c PreparedCommand) OutputE() (string, error)

OutputE is like Output, but it only writes the command output to os.Stderr when it fails.

func (PreparedCommand) OutputS added in v0.4.0 

func (c PreparedCommand) OutputS() (string, error)

Outputs is like Output, but the command output is not written to stdout/stderr.

func (PreparedCommand) OutputV added in v0.4.0 

func (c PreparedCommand) OutputV() (string, error)

OutputV is like Output, but it always writes the command output to os.Stdout.

func (PreparedCommand) Run added in v0.4.0 

func (c PreparedCommand) Run() error

Run the given command, directing stderr to os.Stderr and printing stdout to os.Stdout if mage was run with -v.

func (PreparedCommand) RunE added in v0.4.0 

func (c PreparedCommand) RunE() error

RunE is like Run, but it only writes the command combined to os.Stderr when it fails.

func (PreparedCommand) RunS added in v0.4.0 

func (c PreparedCommand) RunS() error

RunS is like Run, but the command output is not written to stdout/stderr.

Example 
package main

import (
	"log"

	"github.com/carolynvs/magex/shx"
)

func main() {
	err := shx.Command("go", "run", "echo.go", "hello world").RunS()
	if err != nil {
		log.Fatal(err)
	}
}

Output:

func (PreparedCommand) RunV added in v0.4.0 

func (c PreparedCommand) RunV() error

RunV is like Run, but always writes the command output to os.Stdout.

Example 
package main

import (
	"log"

	"github.com/carolynvs/magex/shx"
)

func main() {
	err := shx.Command("go", "run", "echo.go", "hello world").RunV()
	if err != nil {
		log.Fatal(err)
	}
}

Output:

hello world

func (PreparedCommand) Silent added in v0.4.0 

func (c PreparedCommand) Silent() PreparedCommand

Runs a command silently, without writing to stdout/stderr.

func (PreparedCommand) Stderr added in v0.4.0 

func (c PreparedCommand) Stderr(stderr io.Writer) PreparedCommand

Stderr directs stderr from the command.

func (PreparedCommand) Stdin added in v0.5.0 

func (c PreparedCommand) Stdin(stdin io.Reader) PreparedCommand

Stdin sets the command's stdin.

func (PreparedCommand) Stdout added in v0.4.0 

func (c PreparedCommand) Stdout(stdout io.Writer) PreparedCommand

Stdout directs stdout from the command.

func (PreparedCommand) String added in v0.4.0 

func (c PreparedCommand) String() string

String prints the command-line representation of the PreparedCommand.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.