mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-05 17:45:46 +00:00
docs: shorten the gt guides
Cover what users need to get going and leave the details to gt <command> --help and gt help. Signed-off-by: bircni <[email protected]>
This commit is contained in:
5 files changed
+72
-450
No files matched your search
+8
-88
@@ -4,99 +4,19 @@ 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:
|
||||
Scripts should read JSON: the text output is meant for people and may change.
|
||||
|
||||
```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.
|
||||
`--json` prints all fields or the ones you list; the **JSON FIELDS** section of a command's
|
||||
`--help` names them. `--jq` filters the result without needing jq installed. Piped lists
|
||||
print as tab-separated values.
|
||||
|
||||
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.
|
||||
gt exits with 0 on success, 1 when a command fails, 2 on a usage error and 4 when
|
||||
authentication is missing or rejected; `gt help exit-codes` lists all codes.
|
||||
|
||||
## 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`.
|
||||
`gt api` calls any API endpoint with gt's login, and `gt alias set` defines shortcuts for
|
||||
commands you use often.
|
||||
Reference in new issue
Block a user