0 Fork 0

Files

T

Cover the 1.0.0 command surface and stability guarantees:

- New reference files: projects.md, runners.md, extensions.md
- New commands: browse, project, runner, extension, upgrade, pr backport,
  pr update-branch, pr list --local, pr merge --method manually-merged,
  issue move, issue/pr comment attachment, webhook test
- Global --csv output; exit codes 5 (run watch failed) and 6 (--expect-head)
- Interactive edit forms for pr/label/release edit
- Fix fork flag (--add-remote), clone flag (--upstream-remote-name), and
  org member subcommands (add -> conceal/publicize)
- tea is archived; gt is the official successor; migration guide linked
- Semver: 1.x keeps commands/flags/JSON fields/exit codes stable
- Bump metadata/README to gt 1.0.0

2026-11-03 12:35:09 +04:00

4.4 KiB

Raw Blame History

Workflows (recipes)

End-to-end recipes for common tasks. For per-command flags and JSON fields, read the group file in this directory (listed in SKILL.md's command map). All flags are from gt 1.0.0; gt <cmd> --help is authoritative.

Issue lifecycle

gt issue list --assignee @me --state open
gt issue view 12 --comments
gt issue create --title "Crash on start" --body "Steps..." --label bug --milestone v1.0
gt issue edit 12 --add-label triage --add-assignee @me
gt issue comment 12 --body "Fixed in #14"
gt issue close 12 --comment "Done in #14"

Pull requests: create → checks → review → merge

gt pr create --fill                       # push branch, open PR, title/body from commits
gt pr create --fill --yes                 # non-interactive: also push without asking
gt pr list --author @me --state all
gt pr list --local                        # which local branches belong to a merged/closed PR
gt pr checkout 13 --update                # local branch tracking the PR head
gt pr diff 13 | git apply                 # pipe clean diff (git apply works)
gt pr checks 13 --watch                   # waits; exit 8 while pending, 1 if a check failed
gt pr review --approve
gt pr review 13 --request-changes -b "Please hash the password"
gt pr update-branch 13 --rebase           # bring the base branch in
gt pr merge 13 --squash --delete-branch
gt pr clean 13                            # delete the branch of a merged/closed PR

A branch that is not on the remote is pushed first, after a confirmation; in CI pass --yes (or --no-input will fail rather than prompt). See pull-requests.md for fork handling.

Backport a merged PR

gt pr backport 42 --to release/v1.2 --to release/v1.1 --yes
# On conflict, resolve yourself:
gt pr backport 42 --to release/v1.1 --keep
git add . && git cherry-pick --continue
gt pr backport --continue

Mark a PR merged outside Gitea

The repository must allow it (gt repo edit --allow-manual-merge).

git push origin main                      # the commit that merged the PR
gt pr merge 13 --method manually-merged --commit 4b825dc --delete-branch

Actions: dispatch, watch, logs, artifacts

gt workflow list
gt workflow run deploy.yml --ref main --field env=staging
gt run list --workflow CI --branch main --status failure
gt run watch 34 --timeout 10m && echo deployed
gt run watch 34 --expect-head HEAD        # exit 6 if the run is for another commit
gt run view 34 --log
gt run logs 34 --job build --follow
gt run logs 34 --failed --tail 50
gt run download 34 --name build --dir dist
gt secret set DEPLOY_TOKEN

gt run watch and gt workflow run --follow exit 5 when the run completes without success, so they chain well with &&; exit 1 means gt itself failed. See actions.md. Runners are in runners.md.

Projects

gt project create Roadmap --template basic_kanban
gt project list --state open
gt issue move 47 to "In progress"

Releases

gt release create v1.0.0 dist/tool-linux dist/tool-darwin --notes-file CHANGELOG.md
gt release list
gt release upload v1.0.0 dist/tool-darwin --clobber
gt release download v1.0.0

gt release create never pushes a tag: push it first (git push origin v1.0.0) or let Gitea create it with --target. See releases.md.

Fork, clone and keep in sync

gt repo fork --add-remote     # inside a clone: add fork as origin, rename old origin to upstream
gt repo clone alice/project src --depth 1
gt repo clone alice/project --find-instance   # pick the instance that has it
gt repo sync                  # fast-forward the default branch from its remote
gt repo sync bob/project      # fork without a local remote: update it on the server

In a clone with both upstream and origin, gt targets upstream (like gh). See repos.md.

Extensions and keeping `gt` current

gt extension install alice/gt-hello
gt extension list
gt upgrade                    # self-upgrade (verified checksum)

See extensions.md.

Machine-readable output: JSON and CSV

Text output is for people and may change; scripts should use --json/--jq or --csv.

gt issue list --state all --json number,title,state
gt issue list --state all --csv number,title,state > issues.csv
gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"'

4.4 KiB Raw Blame History