Skip to content

Undocumented -x (xtrace) wrapper flag #2063

Description

@codeforester

Problem

basectl --help shows a real, wired-up wrapper-level flag that isn't documented anywhere:

-x  Enable Bash xtrace before running the command

Confirmed wired in cli/bash/commands/basectl/basectl.sh:848,851 (getopts ":hvx" ... x) set -x ;;). It is not mentioned in docs/command-reference.md, docs/execution-model.md, or docs/stability-tiers.md's public/internal wrapper-option lists -- those docs document -v and --keep-temp but not -x.

Why this matters

-x is exactly the kind of flag a contributor debugging a Bash-layer issue would want to know about (it's the wrapper-level xtrace switch, distinct from -v's DEBUG logging and --debug-wrapper's pre-runtime diagnostics) -- but it's currently only discoverable via --help itself, not the docs that specifically catalog wrapper options.

Related: #1606 (open) proposes a canonical command-metadata source to prevent flag documentation from silently diverging from --help output; this issue is the concrete current gap.

Proposed change

Add -x to the wrapper-option documentation in docs/command-reference.md, docs/execution-model.md, and docs/stability-tiers.md's public option lists, alongside the existing -v/--keep-temp entries.

Acceptance criteria

  • -x is documented in the wrapper-option reference alongside the other public wrapper flags.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationDocumentation improvements

Type

No type

Projects

  • Status
    Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions