Import unexported variables from POSIX islands and support set -a natively
Canonical Quirl project documentation synced from docs/decisions/2026-11-11_233501614_import-unexported-variables-from-posix-islands-and-support-s.md.
Accepted · 2026-11-11
Decision
eval, source, ., and the implicit /bin/sh islands that interactive
Normal mode creates for syntax outside the native subset now import the
unexported variables their code changes, and set -a/set +a become native.
A plain source .env makes its variables available to later commands as in
Bash and Zsh, and set -a; source .env; set +a exports them.
Unexported import. Exports keep their existing contract: the final
env -0 replaces the session's exported variables. In addition:
- Every scalar shell variable set when the island exits, absent from that
env -0, whose value or export attribute differs from a baseline taken after the session locals are injected and before the code runs, becomes a session local.unset X; X=sameon an exportedXtherefore leaves an unexportedX, as in Bash. - Session locals that the baseline held and the code unset are removed.
- Shell bookkeeping never counts:
_,SHLVL,PPID,UID,EUID,OPTIND,OPTARG,LINENO,RANDOM,SRANDOM,SECONDS,EPOCHREALTIME,EPOCHSECONDS,PIPESTATUS,FUNCNAME,GROUPS,DIRSTACK,HISTCMD,SHELLOPTS,POSIXLY_CORRECT,BASH,BASHOPTS,BASHPID, every name beginning withBASH_, and the wrapper's__quirl_*scratch variables. Look-alikes such asBASHFUL,COLUMNS, andLINEScount like any other variable.PWDandOLDPWDreach the session through the existing directory handling.IFS,PS1, and other shell defaults count only when the code changes them, because the baseline already holds them. - Functions, aliases, arrays, readonly attributes, traps, positional parameters, and shell options stay inside the island.
The mechanism never parses or evaluates values. set output only nominates
candidate names: the text before the first = of each line, kept only when it
is a shell name. The shell confirms each candidate with ${NAME+x} and prints
NAME=value NUL-terminated with its builtin printf; a multi-line value that
contains a line such as FAKE=spoofed nominates FAKE, which is dropped
unless it is really set. Bash lists arrays as NAME=(...) and quotes every
scalar beginning with (, so those lines are skipped; because a line inside a
multi-line value can also nominate an array's name with a scalar-looking value,
every name some line lists as NAME=( is checked with Bash's own
declare -p, and real arrays are skipped. The EXIT trap first turns off
-x and -v, so tracing the code left on never prints values, and removes
every alias and any function shadowing printf, unalias, builtin, or
declare; in POSIX mode the special builtins it also uses cannot be shadowed
by functions, and it quotes their names against aliases. Code that leaves POSIX
mode and redefines set, or protects a function with readonly -f, can defeat
that scrub; such code is inside the trust boundary below, and a final dump with
no variables, which a real shell never writes, counts as malformed. It then saves IFS and
LC_ALL and turns off -a, -e, and -u so options the code left on cannot
stop the dump. env -0 reports the exports before the dump changes IFS, so
an exported IFS keeps the code's value. Both dumps run under LC_ALL=C,
which keeps the name check byte-wise in every locale; the baseline restores the
session's IFS and LC_ALL before the code runs.
The trust boundary is the code, not the dump. Sourced code is trusted: it runs
with the user's rights and can already set any variable it likes, so the import
does not try to defend against it. What the import guarantees is narrower:
variable values are data, so no value can spoof another variable's name or
inject code into the session, and a broken or interrupted dump imports nothing.
Both dumps are framed by fixed header and trailer records, and Rust revalidates
every name. A truncated or malformed dump (for example after the code ran
readonly IFS or unset PWD), a dump above its byte bound, or a shell that
ended before its trap wrote the dump (killed by a signal, exec, or a
replaced EXIT trap) imports nothing: exports, locals, and the directory stay
as they were, and the session prints a one-line warning saying no variables
were imported and why. Every variable change commits in one transaction that
checks the session's variable and byte limits, so an import over a limit also
changes nothing.
set -a and set +a. The session keeps a native allexport flag. While it
is on, every assignment (bare NAME=value, for variables, ${NAME:=word},
and arithmetic assignments) sets and exports; existing unexported variables
stay private until assigned again. Islands start their code with set -a after
the session locals are injected, so their assignments come back exported.
set +a stops automatic export without removing the export attribute from
variables it already exported, as in Bash. set -o allexport and
set +o allexport are the same options. Other set forms in a plain command
list, and set as a pipeline stage, fail with a diagnostic naming the
supported forms, instead of exec: set: not found.
Amendments
This amends the "Import variables set without export" alternative that the
POSIX invocation decision
rejected, and its statement that "variables set without export ... stay inside
the island". Its other clauses, including running eval and source in
/bin/sh and the export import, still apply.
It also amends two clauses of the
native control-flow decision:
set with only allexport operands no longer sends a compound program to the
island, because the executor runs it natively; other set forms still do. Of
its "two intended differences" between native and island execution, unexported
variables assigned in a loop no longer differ, because islands now import them
too. Only persistent functions remain a difference.
Context
Issue #25: a user of Quirl 0.6.0 ran source .env on a dotenv file without
export lines and found every variable empty, directly and inside a loop,
while Bash and Zsh set them. The documented workaround, set -a; source .env; set +a, failed with exec: set: not found. The source help even used
source .env as its example.
The POSIX invocation decision rejected importing unexported variables because
sh has no portable, unambiguous way to list them, and because children would
not see them in Bash or Zsh either. Since 0.6.0 Quirl keeps unexported shell
variables natively, so the second reason no longer holds: an imported local
behaves exactly as in Bash. The first reason is answered by using set output
only for names and letting the shell itself confirm and print each value.
Alternatives considered:
- Keep the behavior and support only
set -a. Rejected: plainsource .envwould keep silently doing nothing, which is the surprising part. - Fix only the help text. Rejected for the same reason.
- Parse
setoutput values in Rust. Rejected: quoting differs between Bash and Dash, and a parser of shell quoting is exactly the approximation the island exists to avoid. Values never leave the shell except throughprintf. - Import every unexported variable, without a baseline. Rejected: the
shell's own defaults (
PS1,IFS,OPTIND,HOSTNAME, …) would flood the session.
Consequences
source .env,eval 'X=1', and pasted island-only lines set session variables as Bash and Zsh do, verified by differential tests against/bin/sh(Bash 3.2 in POSIX mode on macOS) and Dash.- Each island costs two
setsnapshots and two dump loops. Measured on an Apple Silicon Mac with 40 to 100 environment variables, 20 session locals, and a 30-line dotenv file, the median island grew from 4.9–5.2 ms to 10.8–12.8 ms under/bin/sh(Bash 3.2), and from 3.3–3.4 ms to 5.9–7.1 ms under Dash. The cost is linear in the number of set variables; Bash 3.2's per-variable loop dominates, at roughly 10 to 15 ms per island for a 30-line dotenv file including the array check, and running the loop underLC_ALL=Ccut it by about 40%. Checking array-looking names withdeclare -padds one subshell per such name, which only Bash arrays and spoofing values produce. - The dump file can hold the session environment twice, so its byte bound is twice the session byte limit plus framing.
- A variable the code sets to the value it already had, and that was not exported before, is indistinguishable from an untouched one and is not re-imported; the session already holds that value.
BASH,BASHOPTS,BASHPID, names beginning withBASH_or__quirl_, and the other bookkeeping names cannot be set through an island. Session locals named__quirl_*are not passed in, and neither are the shell's read-onlyPPID,UID,EUID,SHELLOPTS,BASHOPTS, andBASH_VERSINFO, which would otherwise stop every island.- A sourced file that redefines
printfor aliasesevalstill imports its real values. One that leaves the shell unable to report (readonly IFS,unset PWD, its ownEXITtrap) imports nothing and says so.
Start process-group anchors with a trusted fast shell in parallel
Canonical Quirl project documentation synced from docs/decisions/2026-11-08_041414983_start-process-group-anchors-with-a-trusted-fast-shell-in-par.md.
Contributing
Work on Quirl with the same safety, performance, and quality boundaries as the project.