Documentation
¶
Overview ¶
Package executil provides utilities for executing external processes with logging.
Index ¶
- Variables
- func ExecStreamedCommand(ctx context.Context, name string, args ...string) error
- func ExecStreamedCommandWithOpts(ctx context.Context, opts ExecStreamedOpts, name string, args ...string) error
- func LookPath(file string) (string, error)
- func ReadStdout(ctx context.Context, name string, args ...string) (string, error)
- type ExecStreamedOpts
- type Options
- type Result
Constants ¶
This section is empty.
Variables ¶
var ( // ErrCommandFailed is returned when a command exits with a non-zero status. ErrCommandFailed = fmt.Errorf("command exited with non-zero status") )
Functions ¶
func ExecStreamedCommand ¶
ExecStreamedCommand executes a command that emits log output. This function is designed for processes that write logs to stdout/stderr, not for processes that return parseable output.
Behavior:
- When stderr is connected to a TTY: displays a 5-line scrolling pterm Area with stdout and stderr output in dark gray
- When not connected to a TTY: logs stdout and stderr at debug level
- Never returns stdout/stderr to the caller
- Returns only the exit code and any execution error
The command name and arguments are logged before execution.
func ExecStreamedCommandWithOpts ¶
func ExecStreamedCommandWithOpts(ctx context.Context, opts ExecStreamedOpts, name string, args ...string) error
ExecStreamedCommandWithOpts executes a command with streaming output and custom options. This is the unified function that all other exec streaming functions delegate to.
Behavior based on options and environment:
- TTY && UseScrollingArea: displays a 5-line scrolling pterm Area
- TTY && !UseScrollingArea: displays prefixed lines directly to stderr
- No TTY: logs stdout and stderr at debug level
Returns only the exit code and any execution error.
func LookPath ¶
LookPath searches for an executable named file in the directories named by the PATH environment variable. It's a wrapper around exec.LookPath for consistency with the package API.
func ReadStdout ¶
ReadStdout executes a command and returns stdout as a string. Stdout is not logged since it's meant to be parsed by the caller. Stderr is logged at debug level. Returns an error if the command exits with non-zero status.
Types ¶
type ExecStreamedOpts ¶
type ExecStreamedOpts struct {
// WorkingDir is the directory to execute the command from.
// If empty, uses the current directory.
WorkingDir string
// UseScrollingArea determines whether to use a scrolling pterm area for TTY output.
// If true and stderr is a TTY, output is shown in a scrolling area.
// If false and stderr is a TTY, output is shown with prefixed lines.
// If stderr is not a TTY, logs are always used regardless of this setting.
UseScrollingArea bool
// ProcessName is an identifier for this process, used in log messages
// to distinguish output from concurrent processes.
ProcessName string
}
ExecStreamedOpts contains options for executing a streamed command.
type Options ¶
type Options struct {
// Logger is the logger to use for output. If nil, uses slog.Default()
Logger *slog.Logger
// LogLevel is the log level to use for stdout output. Defaults to Debug.
LogLevel slog.Level
// StderrLogLevel is the log level to use for stderr output. Defaults to Warn.
StderrLogLevel slog.Level
// DisableStreaming disables real-time output logging
DisableStreaming bool
}
Options contains optional configuration for command execution.
type Result ¶
type Result struct {
// Stdout contains all stdout output lines
Stdout []string
// Stderr contains all stderr output lines
Stderr []string
// ExitCode is the exit code of the process
ExitCode int
// Error is any error that occurred during execution
Error error
// Duration is how long the command took to execute
Duration time.Duration
}
Result contains the result of a command execution.
func Run ¶
Run executes a command with the given name and arguments. It logs stdout and stderr output in real-time and returns the result.
func RunWithOptions ¶
RunWithOptions executes a command with custom options.
func (*Result) CombinedOutput ¶
CombinedOutput returns stdout and stderr combined as a single string.
Source Files