Documentation
¶
Overview ¶
Package executil provides shell execution utilities.
Index ¶
- func RunSh(ctx context.Context, dir, cmd string) error
- func WithoutEnv(environ []string, names ...string) []string
- type CommandError
- type Executor
- type HeadWriter
- type RealExecutor
- func (e *RealExecutor) Run(ctx context.Context, cmd string, args ...string) ([]byte, error)
- func (e *RealExecutor) RunDir(ctx context.Context, dir, cmd string, args ...string) ([]byte, error)
- func (e *RealExecutor) RunDirStream(ctx context.Context, dir string, stdout, stderr io.Writer, cmd string, ...) error
- func (e *RealExecutor) RunOutputDir(ctx context.Context, dir, cmd string, args ...string) ([]byte, []byte, error)
- func (e *RealExecutor) RunStream(ctx context.Context, stdout, stderr io.Writer, cmd string, args ...string) error
- type RecordedCommand
- type RecordingExecutor
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RunSh ¶ added in v0.32.0
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
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
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.
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) 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.
type RecordedCommand ¶
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.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package executiltest provides a scripted executil.Executor test double.
|
Package executiltest provides a scripted executil.Executor test double. |