shell

Documentation

Overview

Package shell provides a cross-platform virtual shell abstraction for executing commands.

It is intended for internal use by buildkite-agent only.

Index

• Variables
• func BatchEscape(str string) string
• func GetExitCode(err error) int
• func IsExitError(err error) bool
• func IsExitSignaled(err error) bool
• func LookPath(file string, path string, fileExtensions string) (string, error)
• func TempFileWithExtension(filename string) (*os.File, error)
• type ExitError
  • func (ee *ExitError) Error() string
• type LockFile
• type Logger
• type LoggerStreamer
  • func NewLoggerStreamer(logger Logger) *LoggerStreamer
  • func (l *LoggerStreamer) Close() error
  • func (l *LoggerStreamer) Output() error
  • func (l *LoggerStreamer) Write(p []byte) (n int, err error)
• type Shell
  • func New() (*Shell, error)
  • func NewTestShell(t *testing.T) *Shell
  • func (s *Shell) AbsolutePath(executable string) (string, error)
  • func (s *Shell) Chdir(path string) error
  • func (s *Shell) Getwd() string
  • func (s *Shell) Interrupt()
  • func (s *Shell) LockFile(ctx context.Context, path string, timeout time.Duration) (LockFile, error)
  • func (s *Shell) Run(ctx context.Context, command string, arg ...string) error
  • func (s *Shell) RunAndCapture(ctx context.Context, command string, arg ...string) (string, error)
  • func (s *Shell) RunScript(ctx context.Context, path string, extra *env.Environment) error
  • func (s *Shell) RunWithEnv(ctx context.Context, environ *env.Environment, command string, arg ...string) error
  • func (s *Shell) RunWithoutPrompt(ctx context.Context, command string, arg ...string) error
  • func (s *Shell) Terminate()
  • func (s *Shell) WaitStatus() (process.WaitStatus, error)
  • func (s *Shell) WithStdin(r io.Reader) *Shell
• type TestingLogger
  • func (tl TestingLogger) Commentf(format string, v ...any)
  • func (tl TestingLogger) Errorf(format string, v ...any)
  • func (tl TestingLogger) Headerf(format string, v ...any)
  • func (tl TestingLogger) Printf(format string, v ...any)
  • func (tl TestingLogger) Promptf(format string, v ...any)
  • func (tl TestingLogger) Warningf(format string, v ...any)
  • func (tl TestingLogger) Write(b []byte) (int, error)
• type WriterLogger
  • func (wl *WriterLogger) Commentf(format string, v ...any)
  • func (wl *WriterLogger) Errorf(format string, v ...any)
  • func (wl *WriterLogger) Headerf(format string, v ...any)
  • func (wl *WriterLogger) Printf(format string, v ...any)
  • func (wl *WriterLogger) Promptf(format string, v ...any)
  • func (wl *WriterLogger) Warningf(format string, v ...any)
  • func (wl *WriterLogger) Write(b []byte) (int, error)

Variables

var DiscardLogger = &WriterLogger{
	Writer: io.Discard,
}

DiscardLogger discards all log messages

var StderrLogger = &WriterLogger{
	Writer: os.Stderr,
	Ansi:   true,
}

StderrLogger is a Logger that writes to Stderr

Functions

func BatchEscape

func BatchEscape(str string) string

BatchEscape escapes a string for use with an `ECHO` statement in a Windows Batch file. http://www.robvanderwoude.com/escapechars.php

func GetExitCode

func GetExitCode(err error) int

GetExitCode extracts an exit code from an error where the platform supports it, otherwise returns 0 for no error and 1 for an error

func IsExitError

func IsExitError(err error) bool

func IsExitSignaled

func IsExitSignaled(err error) bool

IsExitSignaled returns true if the error is an ExitError that was caused by receiving a signal

func LookPath

func LookPath(file string, path string, fileExtensions string) (string, error)

LookPath searches for an executable binary named file in the directories within the path variable, which is a colon delimited path. If file contains a slash, it is tried directly

func TempFileWithExtension

func TempFileWithExtension(filename string) (*os.File, error)

TempFileWithExtension creates a temporary file that copies the extension of the provided filename

Types

type ExitError

type ExitError struct {
	Code    int
	Message string
}

ExitError is an error that carries a shell exit code

func (*ExitError) Error

func (ee *ExitError) Error() string

Error returns the string message and fulfils the error interface

type LockFile

type LockFile interface {
	Unlock() error
}

LockFile is a pid-based lock for cross-process locking

type Logger

type Logger interface {
	io.Writer

	// Printf prints a line of output
	Printf(format string, v ...any)

	// Headerf prints a Buildkite formatted header
	Headerf(format string, v ...any)

	// Commentf prints a comment line, e.g `# my comment goes here`
	Commentf(format string, v ...any)

	// Errorf shows a Buildkite formatted error expands the previous group
	Errorf(format string, v ...any)

	// Warningf shows a buildkite bootstrap warning
	Warningf(format string, v ...any)

	// Promptf prints a shell prompt
	Promptf(format string, v ...any)
}

Logger represents a logger that outputs to a buildkite shell.

type LoggerStreamer

type LoggerStreamer struct {
	Logger Logger
	Prefix string
	// contains filtered or unexported fields
}

func NewLoggerStreamer

func NewLoggerStreamer(logger Logger) *LoggerStreamer

func (*LoggerStreamer) Close

func (l *LoggerStreamer) Close() error

func (*LoggerStreamer) Output

func (l *LoggerStreamer) Output() error

func (*LoggerStreamer) Write

func (l *LoggerStreamer) Write(p []byte) (n int, err error)

type Shell

type Shell struct {
	Logger

	// The running environment for the shell
	Env *env.Environment

	// Whether the shell is a PTY
	PTY bool

	// Where stdout is written, defaults to os.Stdout
	Writer io.Writer

	// Whether to run the shell in debug mode
	Debug bool

	// The signal to use to interrupt the command
	InterruptSignal process.Signal
	// contains filtered or unexported fields
}

Shell represents a virtual shell, handles logging, executing commands and provides hooks for capturing output and exit conditions.

Provides a lowest-common denominator abstraction over macOS, Linux and Windows

func New

func New() (*Shell, error)

New returns a new Shell

func NewTestShell

func NewTestShell(t *testing.T) *Shell

NewTestShell creates a minimal shell suitable for tests.

func (*Shell) AbsolutePath

func (s *Shell) AbsolutePath(executable string) (string, error)

AbsolutePath returns the absolute path to an executable based on the PATH and PATHEXT of the Shell

func (*Shell) Chdir

func (s *Shell) Chdir(path string) error

Chdir changes the working directory of the shell

func (*Shell) Getwd

func (s *Shell) Getwd() string

Getwd returns the current working directory of the shell

func (*Shell) Interrupt

func (s *Shell) Interrupt()

Interrupt running command

func (*Shell) LockFile

func (s *Shell) LockFile(ctx context.Context, path string, timeout time.Duration) (LockFile, error)

Create a cross-process file-based lock based on pid files

func (*Shell) Run

func (s *Shell) Run(ctx context.Context, command string, arg ...string) error

Run runs a command, write stdout and stderr to the logger and return an error if it fails

func (*Shell) RunAndCapture

func (s *Shell) RunAndCapture(ctx context.Context, command string, arg ...string) (string, error)

RunAndCapture runs a command and captures the output for processing. Stdout is captured, but stderr isn't. If the shell is in debug mode then the command will be eched and both stderr and stdout will be written to the logger. A PTY is never used for RunAndCapture.

func (*Shell) RunScript

func (s *Shell) RunScript(ctx context.Context, path string, extra *env.Environment) error

RunScript is like Run, but the target is an interpreted script which has some extra checks to ensure it gets to the correct interpreter. Extra environment vars can also be passed the script

func (*Shell) RunWithEnv

func (s *Shell) RunWithEnv(ctx context.Context, environ *env.Environment, command string, arg ...string) error

func (*Shell) RunWithoutPrompt

func (s *Shell) RunWithoutPrompt(ctx context.Context, command string, arg ...string) error

RunWithoutPrompt runs a command, writes stdout and err to the logger, and returns an error if it fails. It doesn't show a prompt.

func (*Shell) Terminate

func (s *Shell) Terminate()

Terminate running command

func (*Shell) WaitStatus

func (s *Shell) WaitStatus() (process.WaitStatus, error)

Returns the WaitStatus of the shell's process.

The shell must have been started.

func (*Shell) WithStdin

func (s *Shell) WithStdin(r io.Reader) *Shell

WithStdin returns a copy of the Shell with the provided io.Reader set as the Stdin for the next command. The copy should be discarded after one command. For example, sh.WithStdin(strings.NewReader("hello world")).Run("cat")

type TestingLogger

type TestingLogger struct {
	*testing.T
}

func (TestingLogger) Commentf

func (tl TestingLogger) Commentf(format string, v ...any)

func (TestingLogger) Errorf

func (tl TestingLogger) Errorf(format string, v ...any)

func (TestingLogger) Headerf

func (tl TestingLogger) Headerf(format string, v ...any)

func (TestingLogger) Printf

func (tl TestingLogger) Printf(format string, v ...any)

func (TestingLogger) Promptf

func (tl TestingLogger) Promptf(format string, v ...any)

func (TestingLogger) Warningf

func (tl TestingLogger) Warningf(format string, v ...any)

func (TestingLogger) Write

func (tl TestingLogger) Write(b []byte) (int, error)

type WriterLogger

type WriterLogger struct {
	Writer io.Writer
	Ansi   bool
}

WriterLogger provides a logger that writes to an io.Writer

func (*WriterLogger) Commentf

func (wl *WriterLogger) Commentf(format string, v ...any)

func (*WriterLogger) Errorf

func (wl *WriterLogger) Errorf(format string, v ...any)

func (*WriterLogger) Headerf

func (wl *WriterLogger) Headerf(format string, v ...any)

func (*WriterLogger) Printf

func (wl *WriterLogger) Printf(format string, v ...any)

func (*WriterLogger) Promptf

func (wl *WriterLogger) Promptf(format string, v ...any)

func (*WriterLogger) Warningf

func (wl *WriterLogger) Warningf(format string, v ...any)

func (*WriterLogger) Write

func (wl *WriterLogger) Write(b []byte) (int, error)