Skip to main content

Global flags

gitq parses its own command line in one place, src/cli/main.ts, with node's parseArgs, in non-strict mode. This page is the complete list of what it recognizes, which commands read what, and what non-strict mode actually does with a flag you typo.

Flags every command accepts​

FlagTypeMeaning
-C <path>stringRun as if invoked from <path> instead of the current directory. Resolved once, before the command dispatches (src/cli/main.ts:124).
--jsonbooleanEmit machine readable JSON on stdout instead of the human summary. See JSON output.
--stack <name>stringPick which tracked stack a command applies to. Not every command reads it; see the rule below.
--help, -hbooleanPrint usage and exit 0 without running the command. See the section below.
--version, -vbooleanPrint the bare semver and exit 0. Answered ahead of parseArgs and of anything that resolves a repo, so it works on a machine with no configuration at all.

These three, plus every command-specific flag below, are declared in one options object passed to parseArgs (src/cli/main.ts:94-107); allowPositionals: true is what lets the command name and its own positional arguments (a branch name, for example) through alongside them.

The --stack rule​

Optional when the repo has exactly one tracked stack, required once it has more than one.

The resolution is pickStack (src/cli/commands/crud.ts:9-18): given --stack <name>, it looks up that name and fails with no stack named <name> (have: ...) if nothing matches; given no --stack and exactly one tracked stack, it uses that one; given no --stack and more than one, it refuses. Real capture, a repo with two tracked stacks, running a command that needs one:

$ gitq add featx --parent main
gitq: --stack required (have: demo, second)

pickStack backs add, remove, sync, absorb, split, fold, reparent, rename, reset, and publish. continue and abort read ctx.flags.stack directly instead of calling pickStack, to disambiguate which parked cascade to resume when more than one stack is parked at once (findParkedLease, src/cli/slots.ts:99-110); with only one parked cascade, no flag is needed there either, and with none at all both commands say nothing to continue (no parked cascade) regardless of whether you asked for continue or abort. track and untrack take the stack name as a plain positional argument instead of --stack: track is creating a new stack, so there is nothing yet to disambiguate, and untrack names the one it removes. stacks, diagnose, preflight, log, undo, and import never take --stack at all: the first four report on every tracked stack in one call, undo resolves the most recent operation for the repo regardless of which stack it touched, and import replaces the whole store.

Command-specific flags​

FlagUsed byMeaning
--root <branch>trackThe new stack's root branch.
--parent <branch>addThe parent branch the new node attaches under.
--onto <branch>reparentThe new parent branch.
--at <sha>splitTail-split mode: move every commit from <sha> onward into the new branch. Mutually exclusive with --files.
--at <branch>absorbCommit every attributed file to <branch> instead of where attribution would put it. Same flag name, different argument: split reads a sha, absorb reads a branch.
--files <glob[,glob...]>splitFile-split mode: move files matching the comma separated glob(s) into the new branch. Mutually exclusive with --at.
--name <newBranch>splitName of the branch either split mode creates.
--previewabsorb, pushShow what the command would do without doing it: the file attribution for absorb, the per-branch push plan for push.
--mr-meta <path>publishPath to a JSON file of {"<branch>": {"title": "...", "description": "..."}}. Branches not listed get default titles and descriptions.
--replaceimportOverwrite a non-empty local store instead of refusing.

(Source: each command reads its own flags straight off ctx.flags in src/cli/commands/crud.ts, src/cli/commands/surgery.ts, and src/cli/commands/forge.ts.)

--help answers before the command runs​

gitq --help prints the command table; gitq <command> --help prints that command's synopsis. Both exit 0, and -h is the same flag. Help is handled in the dispatcher before createContext (src/cli/main.ts:112-117), so it resolves no repo, reads no store, and takes no lease: gitq absorb --help outside a git repo prints usage rather than failing, and inside one with a dirty worktree it absorbs nothing.

That ordering is the point. Every mutating command is one word away from its own help flag, and until this was handled --help fell through to the command itself: gitq absorb --help ran a real absorb.

$ gitq absorb --help
usage: gitq absorb [--preview] [--stack <name>] [--json]

The synopsis for each command lives in USAGE (src/cli/main.ts:49-70), and a test asserts it stays in step with the command table.

parseArgs runs non-strict, and a typo is silent​

main.ts calls parseArgs with strict: false (src/cli/main.ts:90-108). Verified directly rather than assumed: an unrecognized flag is never an error. It does not throw, it does not print a warning, and gitq behaves exactly as if you had not passed it at all. There is no "did you mean" and no strict-mode rejection, for any command. --help and -h are the one exception, and they are matched off the raw argv rather than through parseArgs.

--json typo'd as --jsonn, run against a real scratch repo:

$ gitq stacks --jsonn
demo (root main): feat-api -> feat-handlers

Exit 0, plain human text, no complaint about --jsonn anywhere on stdout or stderr. If you are scripting against --json and parsing stdout as JSON, a typo like this fails silently: you get plain text where you expected JSON, with nothing in the exit code to tell you why. The same held for every other unrecognized flag tried against a scratch repo: --bogus, --bogus=value, --bogus somevalue, and -x were all accepted without complaint, whatever followed them.

Check a flag name before you rely on it. gitq will not tell you that you got it wrong.

Next​