mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-05 17:45:46 +00:00
103 lines
3.7 KiB
Markdown
103 lines
3.7 KiB
Markdown
---
|
|
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:
|
|
|
|
```bash
|
|
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](https://jqlang.org) expression and implies
|
|
`--json`. It runs inside gt, so jq does not need to be installed. String results print
|
|
without quotes:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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`.
|