Help us shape the future of Go! Take the 2026 Go Developer Survey

executil

package
v0.66.1 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package executil provides shell execution utilities.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RunSh added in v0.32.0

func RunSh(ctx context.Context, dir, cmd string) error

RunSh executes a shell command in the given directory (empty means inherit cwd). On failure, stderr is returned as the error message, capped at 500 bytes to prevent large or ANSI-polluted output from corrupting logs or TUI display. The original *exec.ExitError is preserved via wrapping so callers can inspect exit codes with errors.As.

func WithoutEnv added in v0.60.0

func WithoutEnv(environ []string, names ...string) []string

WithoutEnv returns a copy of environ without the variables named in names. A nil environ means this process's environment, as it does for exec.Cmd.Env.

Types

type CommandError added in v0.60.0

type CommandError struct {
	Command string
	Dir     string
	Output  []byte
	Err     error
}

CommandError describes a failed child process and its capped output.

func NewCommandError added in v0.60.0

func NewCommandError(command, dir string, output []byte, err error) *CommandError

NewCommandError creates a command error with at most 500 bytes of child output.

func (*CommandError) Error added in v0.60.0

func (e *CommandError) Error() string

func (*CommandError) Unwrap added in v0.60.0

func (e *CommandError) Unwrap() error

type Executor

type Executor interface {
	// Run executes a command and returns its combined output.
	Run(ctx context.Context, cmd string, args ...string) ([]byte, error)
	// RunDir executes a command in a specific directory.
	RunDir(ctx context.Context, dir, cmd string, args ...string) ([]byte, error)
	// RunStream executes a command and streams stdout/stderr to the provided writers.
	RunStream(ctx context.Context, stdout, stderr io.Writer, cmd string, args ...string) error
	// RunDirStream executes a command in a specific directory and streams output.
	RunDirStream(ctx context.Context, dir string, stdout, stderr io.Writer, cmd string, args ...string) error
}

Executor runs shell commands.

type HeadWriter added in v0.60.0

type HeadWriter struct {
	Max int
	// contains filtered or unexported fields
}

HeadWriter keeps the first Max bytes written to it and discards the rest. Write always reports the full length, so a noisy child never blocks on a full pipe and io.Copy never fails with io.ErrShortWrite. It is safe for concurrent use, so one HeadWriter can take both stdout and stderr.

func (*HeadWriter) Bytes added in v0.60.0

func (w *HeadWriter) Bytes() []byte

Bytes returns a copy of the bytes kept so far.

func (*HeadWriter) String added in v0.60.0

func (w *HeadWriter) String() string

func (*HeadWriter) Truncated added in v0.60.0

func (w *HeadWriter) Truncated() bool

Truncated reports whether any written byte was discarded.

func (*HeadWriter) Write added in v0.60.0

func (w *HeadWriter) Write(p []byte) (int, error)

type RealExecutor

type RealExecutor struct {
	// Env, when set, is the environment each command runs with.
	Env func(ctx context.Context) []string
	// LookPath, when set, resolves the command name before it runs. os/exec
	// searches this process's PATH and ignores Cmd.Env, so a program that only
	// the Env PATH holds needs this to start. A name LookPath cannot resolve
	// runs unchanged, so the caller sees the OS's own error for it.
	LookPath func(ctx context.Context, file string) (string, error)
	// StreamDiagnosticBytes, when positive, appends up to that many leading
	// bytes of a failed streamed command's stderr to its error, for callers
	// that stream stderr somewhere nobody reads.
	StreamDiagnosticBytes int
}

RealExecutor calls actual shell commands. Its zero value runs them in this process's environment and resolves them through this process's PATH.

func (*RealExecutor) Run

func (e *RealExecutor) Run(ctx context.Context, cmd string, args ...string) ([]byte, error)

Run executes a command and returns its combined output.

func (*RealExecutor) RunDir

func (e *RealExecutor) RunDir(ctx context.Context, dir, cmd string, args ...string) ([]byte, error)

RunDir executes a command in a specific directory.

func (*RealExecutor) RunDirStream

func (e *RealExecutor) RunDirStream(ctx context.Context, dir string, stdout, stderr io.Writer, cmd string, args ...string) error

RunDirStream executes a command in a specific directory and streams output.

func (*RealExecutor) RunOutputDir added in v0.56.0

func (e *RealExecutor) RunOutputDir(ctx context.Context, dir, cmd string, args ...string) ([]byte, []byte, error)

RunOutputDir executes a command in dir (empty means inherit cwd) and returns stdout and stderr separately. Keeping the streams apart lets callers parse stdout as JSON while surfacing stderr as the error message.

func (*RealExecutor) RunStream

func (e *RealExecutor) RunStream(ctx context.Context, stdout, stderr io.Writer, cmd string, args ...string) error

RunStream executes a command and streams stdout/stderr to the provided writers.

type RecordedCommand

type RecordedCommand struct {
	Dir  string
	Cmd  string
	Args []string
}

RecordedCommand captures a command that was executed.

type RecordingExecutor

type RecordingExecutor struct {
	Commands []RecordedCommand

	// Outputs maps command names to their output.
	// Key is the command name (e.g., "git").
	Outputs map[string][]byte

	// Errors maps command names to their error.
	Errors map[string]error
	// contains filtered or unexported fields
}

RecordingExecutor captures commands for testing. Configure Outputs and Errors maps to control return values.

func (*RecordingExecutor) Reset

func (e *RecordingExecutor) Reset()

Reset clears recorded commands.

func (*RecordingExecutor) Run

func (e *RecordingExecutor) Run(ctx context.Context, cmd string, args ...string) ([]byte, error)

Run records the command and returns configured output/error.

func (*RecordingExecutor) RunDir

func (e *RecordingExecutor) RunDir(ctx context.Context, dir, cmd string, args ...string) ([]byte, error)

RunDir records the command with directory and returns configured output/error.

Directories

Path Synopsis
Package executiltest provides a scripted executil.Executor test double.
Package executiltest provides a scripted executil.Executor test double.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL