3.7 KiB
sidebar_position
| sidebar_position |
|---|
| 5 |
Output and scripting
gt prints text for people by default. Scripts should read JSON instead: the columns and wording of the text output may change between releases.
JSON
--json prints every field of the result, --json FIELDS only the comma-separated
fields you list:
gt issue list --json
gt pr view 123 --json number,title,state
The JSON FIELDS section of a command's --help lists its fields, and shell completion
offers them after --json. An unknown field reports the available ones. Commands that
return no resource, such as deletes, reject --json.
--jq (-q) filters the JSON with a jq expression and implies
--json. It runs inside gt, so jq does not need to be installed. String results print
without quotes:
gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"'
Some fields cost extra requests, such as the reviewers of gt pr list. gt makes them only
when the output includes the field: --json names it, or --json selects every field and
the --jq expression names it. An expression that reaches such a field without naming it,
as to_entries does, sees it empty; name the field in --json instead.
On a terminal, JSON is indented and colored; otherwise each value prints on one line. gt
does not prompt while it prints JSON; --interactive allows prompts anyway.
gt help formatting describes all of this.
Piped output
JSON and other results go to stdout. Diagnostics, prompts and the messages that confirm a change go to stderr, so they never end up in the data a script reads.
Piped or redirected, lists print as tab-separated values without a header row, ready for
cut or awk:
gt issue list --kind all --milestone v1.0 | cut -f1,2
Color settings never color piped output. Only a command's own --color always does, such
as gt pr diff --color always.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success, including an empty list |
| 1 | The command failed |
| 2 | Usage error: an unknown command or flag, or a missing or invalid argument |
| 3 | Canceled: a declined confirmation, a prompt left with Esc or Ctrl-D, or a timeout |
| 4 | Authentication is missing or was rejected |
| 8 | gt pr checks: some checks are still pending |
| 130 | Interrupted with Ctrl-C, also at a prompt |
A command may document further codes in its help. gt auth status, for example, exits
with 4 when there is no account or a credential is missing or rejected; with --json it
exits with 0 either way and reports the problem in its output.
The API
gt api sends an authenticated request to the instance's API, for what no command covers
yet. The endpoint is a path under /api/v1, and {owner} and {repo} take the current
repository:
gt api user --jq .login
gt api repos/{owner}/{repo}/issues -f title="Crash on start" -F labels='[3]'
gt api user/repos --paginate --jq '.[].full_name'
A response outside 2xx prints its body, then fails. gt auth token prints the token gt
uses, for tools that call the API themselves.
Aliases
An alias is a shortcut that expands to a gt command with its arguments:
# gt il runs gt issue list --label bug
gt alias set il "issue list --label bug"
# $1 takes the first argument: gt review 13 runs gt pr review 13 --approve
gt alias set review 'pr review $1 --approve'
$1, $2 and so on take the arguments in that position; other arguments follow the
expansion, so gt il --state all runs gt issue list --label bug --state all. Aliases never
run a shell, and a built-in command always wins over an alias of the same name.
--clobber replaces an existing alias, gt alias list lists them and gt alias delete
removes one. They are kept in config.yml.