A bash script in a CI job runs with `set -x`, and the trace both corrupts the stderr output another tool parses and prints an API token into a shared build log. How do you route bash's trace somewhere other than stderr, and what does that still leave you responsible for?

## The problem with stderr as the trace channel By default xtrace shares fd 2 with everything else the script and its children write there. That creates two distinct failures in an automated pipeline. **Stream corruption.** If a wrapper reads the script's stderr — a CI system that surfaces stderr as the failure reason, a log shipper that parses it, a caller doing `err=$(./script.sh 2>&1 >/dev/null)` — the trace is now interleaved into data someone is parsing. The script looks like it emitted thousands of garbage diagnostics. **Disclosure.** xtrace prints commands *after expansion*. Every secret that reaches a command line is printed: ```bash curl -sS -H "Authorization: Bearer $TOKEN" "$API/deploy" # + curl -sS -H 'Authorization: Bearer ghp_realvaluehere' https://api.example/deploy ``` CI systems that mask known secret values help, but they mask only values they were told about, and only in the streams they capture. ## Routing the trace: BASH_XTRACEFD Bash 4.1 introduced `BASH_XTRACEFD`. If it is set to an integer that is a valid file descriptor, bash writes xtrace output to that descriptor instead of to stderr. ```bash trace_file=$(mktemp -t deploy-trace.XXXXXX) exec 9>"$trace_file" BASH_XTRACEFD=9 set -x ``` After this, fd 2 carries only the script's own diagnostics and those of the commands it runs, while the trace accumulates in a private file you can attach to a build artifact, upload only on failure, or delete. The descriptor number is your choice; pick a high one to stay clear of anything the script itself opens. Because the descriptor is inherited by child processes, be deliberate about whether you want subprocesses holding it open. A gated form, so the default run is quiet: ```bash if [[ ${TRACE:-0} == 1 ]]; then exec 9>"${TRACE_FILE:-/dev/null}" BASH_XTRACEFD=9 set -x fi ``` ## The sharp edge: unsetting it Bash documents that unsetting `BASH_XTRACEFD`, or assigning it a new value, closes the file descriptor it previously named. The consequence people hit is: ```bash BASH_XTRACEFD=2 # "same as the default, harmless" ... unset BASH_XTRACEFD # closes fd 2 — stderr is now gone ``` From that point every write to stderr in the script and in its children fails. The rule is simple: never point `BASH_XTRACEFD` at 2 or at any descriptor you still need, and if you want the trace back on stderr, assign the empty string rather than closing something you care about. ## What redirection does not solve Routing is a plumbing fix, not a security control. The trace file still contains the expanded commands, so: - **Create it privately.** A trace in a world-readable location on a shared runner is the same disclosure with an extra step; the mechanics of creating a private temp file and cleaning it up on every exit path is its own discipline. - **Decide its lifetime.** Uploading the trace as a build artifact on failure is useful and is also publishing it — to whoever can read that build. - **Keep secrets off command lines where you can.** Pass them via environment variables consumed by the tool, a config file, or a here-document on stdin, so the sensitive value never appears as an argument that xtrace can print. `curl --config -` reading from stdin is the classic example. - **Scope the tracing.** Turn xtrace on around the region under investigation and off again, rather than tracing a whole deploy, so the volume stays reviewable. ## Portability `BASH_XTRACEFD` requires bash 4.1 or newer. macOS ships bash 3.2, where the variable is an ordinary, meaningless variable and the trace keeps going to stderr — silently, which is the dangerous failure. If a script must behave on both, test the version explicitly (`(( BASH_VERSINFO[0] >= 5 ))`, or check the major and minor pair) or achieve the split with plain redirection of the whole invocation instead: `bash -x ./script.sh 2>trace.log`, which sends *everything* on stderr to the file — a blunter tool, because it takes the script's real diagnostics with it.