Documentation ¶
Overview ¶
Extend the github.com/magefile/mage/sh package with helper functions to run commands in a magefile.
Index ¶
- func Copy(src string, dest string, opts ...CopyOption) error
- func Move(src string, dest string, opts ...MoveOption) error
- func Output(cmd string, args ...string) (string, error)
- func OutputE(cmd string, args ...string) (string, error)
- func OutputS(cmd string, args ...string) (string, error)
- func OutputV(cmd string, args ...string) (string, error)
- func RecordStderr() *capture
- func RecordStdout() *capture
- func Run(cmd string, args ...string) error
- func RunE(cmd string, args ...string) error
- func RunS(cmd string, args ...string) error
- func RunV(cmd string, args ...string) error
- type CommandBuilder
- func (b *CommandBuilder) Command(cmd string, args ...string) PreparedCommand
- func (b *CommandBuilder) Output(cmd string, args ...string) (string, error)
- func (b *CommandBuilder) OutputE(cmd string, args ...string) (string, error)
- func (b *CommandBuilder) OutputS(cmd string, args ...string) (string, error)
- func (b *CommandBuilder) OutputV(cmd string, args ...string) (string, error)
- func (b *CommandBuilder) Run(cmd string, args ...string) error
- func (b *CommandBuilder) RunE(cmd string, args ...string) error
- func (b *CommandBuilder) RunS(cmd string, args ...string) error
- func (b *CommandBuilder) RunV(cmd string, args ...string) error
- type CopyOption
- type MoveOption
- type PreparedCommand
- func (c PreparedCommand) Args(args ...string) PreparedCommand
- func (c PreparedCommand) CollapseArgs() PreparedCommand
- func (c PreparedCommand) Env(vars ...string) PreparedCommand
- func (c PreparedCommand) Exec() (ran bool, code int, err error)
- func (c PreparedCommand) In(dir string) PreparedCommand
- func (c PreparedCommand) Must(stopOnError ...bool) PreparedCommand
- func (c PreparedCommand) Output() (string, error)
- func (c PreparedCommand) OutputE() (string, error)
- func (c PreparedCommand) OutputS() (string, error)
- func (c PreparedCommand) OutputV() (string, error)
- func (c PreparedCommand) Run() error
- func (c PreparedCommand) RunE() error
- func (c PreparedCommand) RunS() error
- func (c PreparedCommand) RunV() error
- func (c PreparedCommand) Silent() PreparedCommand
- func (c PreparedCommand) Stderr(stderr io.Writer) PreparedCommand
- func (c PreparedCommand) Stdin(stdin io.Reader) PreparedCommand
- func (c PreparedCommand) Stdout(stdout io.Writer) PreparedCommand
- func (c PreparedCommand) String() string
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Copy ¶
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/uwu-tools/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 ¶
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/uwu-tools/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 ¶
Output executes the prepared command, returning stdout.
Example ¶
package main import ( "log" "github.com/uwu-tools/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 ¶
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/uwu-tools/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 ¶
Outputs is like Output, but nothing is written to stdout/stderr.
Example ¶
package main import ( "log" "github.com/uwu-tools/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 ¶
OutputV is like Output, but it always writes the command's stdout to os.Stdout.
Example ¶
package main import ( "log" "github.com/uwu-tools/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 Run ¶
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/uwu-tools/magex/shx" ) func main() { // Only write to stdout when mage -v is set err := shx.Run("go", "run", "echo.go", "hello world") if err != nil { log.Fatal(err) } }
Output:
func RunE ¶
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/uwu-tools/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 ¶
RunS is like Run, but the command output is not written to stdout/stderr.
Example ¶
package main import ( "log" "github.com/uwu-tools/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 ¶
RunV is like Run, but always writes the command's stdout to os.Stdout.
Example ¶
package main import ( "log" "github.com/uwu-tools/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 ¶
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 ¶
func (b *CommandBuilder) Command(cmd string, args ...string) PreparedCommand
Command creates a command using common configuration.
func (*CommandBuilder) Output ¶
func (b *CommandBuilder) Output(cmd string, args ...string) (string, error)
Output executes the prepared command, returning stdout.
func (*CommandBuilder) OutputE ¶
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 ¶
func (b *CommandBuilder) OutputS(cmd string, args ...string) (string, error)
Outputs is like Output, but nothing is written to stdout/stderr.
func (*CommandBuilder) OutputV ¶
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 ¶
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 ¶
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.
type CopyOption ¶
type CopyOption int
const ( CopyDefault CopyOption = iota // CopyNoOverwrite does not overwrite existing files in the destination CopyNoOverwrite CopyRecursive )
type MoveOption ¶
type MoveOption int
const ( MoveDefault MoveOption = iota // MoveNoOverwrite does not overwrite existing files in the destination MoveNoOverwrite MoveRecursive )
type PreparedCommand ¶
func Command ¶
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 ¶
func (c PreparedCommand) Args(args ...string) PreparedCommand
Args appends additional arguments to the command.
Example ¶
package main import ( "log" "github.com/uwu-tools/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 ¶
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/uwu-tools/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 ¶
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 ¶
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 ¶
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/uwu-tools/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 ¶
func (c PreparedCommand) Must(stopOnError ...bool) PreparedCommand
Must immediately stops the build when the command fails.
func (PreparedCommand) Output ¶
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 ¶
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 ¶
func (c PreparedCommand) OutputS() (string, error)
Outputs is like Output, but the command output is not written to stdout/stderr.
func (PreparedCommand) OutputV ¶
func (c PreparedCommand) OutputV() (string, error)
OutputV is like Output, but it always writes the command output to os.Stdout.
func (PreparedCommand) Run ¶
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 ¶
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 ¶
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/uwu-tools/magex/shx" ) func main() { err := shx.Command("go", "run", "echo.go", "hello world").RunS() if err != nil { log.Fatal(err) } }
Output:
func (PreparedCommand) RunV ¶
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/uwu-tools/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 ¶
func (c PreparedCommand) Silent() PreparedCommand
Runs a command silently, without writing to stdout/stderr.
func (PreparedCommand) Stderr ¶
func (c PreparedCommand) Stderr(stderr io.Writer) PreparedCommand
Stderr directs stderr from the command.
func (PreparedCommand) Stdin ¶
func (c PreparedCommand) Stdin(stdin io.Reader) PreparedCommand
Stdin sets the command's stdin.
func (PreparedCommand) Stdout ¶
func (c PreparedCommand) Stdout(stdout io.Writer) PreparedCommand
Stdout directs stdout from the command.
func (PreparedCommand) String ¶
func (c PreparedCommand) String() string
String prints the command-line representation of the PreparedCommand.