process

Documentation

Overview

Package process wraps os/exec with a fluent builder modelled on Laravel's Process facade.

Compared to os/exec, the wrapper:

• returns a typed Result with ExitCode, Stdout, Stderr, Duration;
• accepts a context.Context for cancellation and timeouts;
• never starts a shell — the first argument is the program, the rest are exact argv entries (no string-split surprises, no injection from interpolated values).

Usage:

r, err := process.Command("git", "rev-parse", "HEAD").Run(ctx)
if err != nil { return err }
fmt.Println(r.Stdout)

// timeout + working directory + extra env
_, _ = process.Command("npm", "test").
    Dir("/srv/app").
    Env("CI", "1").
    Timeout(2 * time.Minute).
    Run(ctx)

Index

• Variables
• type Cmd
  • func Command(name string, args ...string) *Cmd
  • func (c *Cmd) AppendArgs(args ...string) *Cmd
  • func (c *Cmd) Args(args ...string) *Cmd
  • func (c *Cmd) Dir(d string) *Cmd
  • func (c *Cmd) Env(k, v string) *Cmd
  • func (c *Cmd) Run(ctx context.Context) (Result, error)
  • func (c *Cmd) Stdin(r io.Reader) *Cmd
  • func (c *Cmd) Timeout(d time.Duration) *Cmd
• type ExitError
  • func (e *ExitError) Error() string
  • func (e *ExitError) Unwrap() error
• type Result
  • func (r Result) Successful() bool

Variables

var ErrTimeout = errors.New("process: timeout")

ErrTimeout is returned when the process is killed because the configured timeout (or the caller's context deadline) elapsed.

Types

type Cmd

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

Cmd is an immutable builder. Each setter returns a clone so chains compose safely:

base := process.Command("git").Dir("/repo")
a := base.Args("status", "--short")  // doesn't mutate base

func Command

func Command(name string, args ...string) *Cmd

Command builds a process invocation. The first argument is the program; remaining arguments are passed as separate argv entries (no shell interpretation).

func (*Cmd) AppendArgs

func (c *Cmd) AppendArgs(args ...string) *Cmd

AppendArgs adds to the existing argument list.

func (*Cmd) Args

func (c *Cmd) Args(args ...string) *Cmd

Args replaces the argument list.

func (*Cmd) Dir

func (c *Cmd) Dir(d string) *Cmd

Dir sets the working directory.

func (*Cmd) Env

func (c *Cmd) Env(k, v string) *Cmd

Env adds an environment variable (in addition to the parent process environment).

func (*Cmd) Run

func (c *Cmd) Run(ctx context.Context) (Result, error)

Run executes the command and waits for it to finish. The returned error is non-nil for non-zero exit codes, transport failures, or timeouts; the Result is still populated when an exit code is known.

func (*Cmd) Stdin

func (c *Cmd) Stdin(r io.Reader) *Cmd

Stdin pipes r into the process stdin.

func (*Cmd) Timeout

func (c *Cmd) Timeout(d time.Duration) *Cmd

Timeout caps the wall-clock duration. 0 means no per-process timeout (the parent context still applies).

type ExitError

type ExitError struct {
	Result Result
	Err    error
}

ExitError wraps a non-zero exit so callers can inspect Result fields while still using errors.As.

func (*ExitError) Error

func (e *ExitError) Error() string

func (*ExitError) Unwrap

func (e *ExitError) Unwrap() error

type Result

type Result struct {
	ExitCode int
	Stdout   string
	Stderr   string
	Duration time.Duration
}

Result captures the outcome of a process invocation.

func (Result) Successful

func (r Result) Successful() bool

Successful reports whether the process exited with code 0.