Environment

Default Sandbox Layout

Every gbash session starts with a minimal virtual filesystem:

The default PATH is /usr/bin:/bin.

Command Directories

/usr/bin and /bin contain virtual stubs that allow the shell to resolve command names during parsing. These are not real executables. When a command runs, gbash dispatches it through the command registry or shell engine, not through the host filesystem.

This means ls /usr/bin lists the available command names, but the files themselves are placeholders used only for shell resolution (which, type, command -v, and related flows).

Shell Features

gbash supports a broad subset of bash syntax and behavior:

• Pipelines - cmd1 | cmd2 | cmd3
• Redirections - >, >>, <, 2>&1, &>
• Variable expansion - $VAR, ${VAR:-default}, ${#VAR}
• Command substitution - $(cmd), `cmd`
• Arithmetic - $((x + 1)), $(( 2 ** 10 ))
• Conditionals - if/elif/else/fi, [[ ... ]], test, [ ... ]
• Loops - for, while, until
• Shell functions - fn() { ...; }
• Logical operators - &&, ||
• Here documents - <<EOF
• Indexed and associative arrays
• Sourcing and evaluation - source, ., and eval
• Directory stack builtins - cd, pushd, popd, dirs
• Nested bash/sh - bash -c "..." and sh -c "..." re-enter the runtime

Limitations

gbash is not a full bash reimplementation. Notable differences:

• No job control (bg, fg, jobs, background process orchestration)
• No readline-style line editing or tab-completion frontend in the shipped CLI
• No host TTY emulation or subprocess passthrough
• Shell-local variables, functions, and option state do not persist across separate Session.Exec calls
• Some advanced edge-case shell forms may still surface as normal shell errors instead of matching GNU Bash exactly

Base Environment

New sessions inherit a deterministic base environment:

gbash also seeds internal metadata variables such as GBASH_ARCH, GBASH_UNAME_*, and GBASH_UMASK so commands like arch and uname have deterministic values inside the sandbox.

Override the base environment with WithBaseEnv:

rt, err := gbash.New(
    gbash.WithBaseEnv(map[string]string{
        "LANG": "en_US.UTF-8",
        "EDITOR": "vim",
    }),
)

Per-execution environment overrides can also be passed through ExecutionRequest, and ExecutionResult.FinalEnv lets you carry exported variables and PWD forward between session turns when needed.