Git/gitea-tea
1
0 Fork 0
mirror of https://gitea.com/gitea/tea.git synced 2026-10-26 19:11:25 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: shorten help and migration texts to gh-like brevity

Browse Source 
Long texts no longer restate the flag list, the instance selection
of tea help environment, the config keys with descriptions or the
team argument rules shown under ARGUMENTS; webhook events come from
services.WebhookEvents; the migration guide refers to tea help
formatting for the terminal layout.

Signed-off-by: bircni <bircni@icloud.com>
This commit is contained in:
bircni committed 2026-10-12 20:14:09 +02:00
1 parent 8bf979099b
commit ab8ba6df4f
9 files changed
+31 -101
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/migration-1.0.md
+7 -23
View File
@@ -295,29 +295,13 @@ names; `--jq` / `-q` filters the result and implies `--json`. Commands that
produce no resource, such as deletes, reject `--json` with a usage error instead
of printing nothing. See `tea help formatting`.
Lists follow gh. On a terminal they print a "Showing 30 of 112 open issues in
alice/project" line, an uppercase header row and columns fitted to the terminal
width, with times relative ("about 3 hours ago"), states colored and the first
column linked to the web page (`tea config set hyperlinks never` turns the links
off). An empty list prints a message on stderr and exits 0. When stdout is not a
terminal, lists print tab-separated values without header, color or links, with
times in RFC 3339 UTC and stable columns, so `cut -f1` works; a `--page` hint
goes to stderr when more results follow. Still prefer `--json` in scripts: the
columns may change. Tabs and line breaks in list cells become spaces, and
control characters such as escape sequences are dropped from all human output,
bodies included.
Commands that change resources report each change on stderr, such as
`✓ Closed issue alice/project#5 (Fix login)` or `! … is already closed`, only
when stdout is a terminal. Create commands print the URL of the new resource
on stdout, so `url=$(tea issue create …)` works; other changes print nothing
when piped. With `--json` they print the changed resource instead.
Issue, pull request, release and comment bodies are rendered as Markdown on a
terminal and printed as written when piped; `tea config set markdown raw` always
prints them as written. Long output on a terminal goes through a pager
(`TEA_PAGER`, the `pager` preference or `PAGER`). Each command starts the pager
at most once.
When stdout is not a terminal, lists print tab-separated values without header,
color or links, with times in RFC 3339 UTC, and a `--page` hint goes to stderr;
prefer `--json` in scripts. Commands that change resources report each change on
stderr only on a terminal. Create commands print the URL of the new resource on
stdout, so `url=$(tea issue create …)` works; other changes print nothing when
piped. Bodies are rendered as Markdown only on a terminal (`tea config set
markdown raw` turns this off). See `tea help formatting` for the terminal layout.
## Exit codes
internal/app/action_runs.go
+1 -4
View File
@@ -28,10 +28,7 @@ func (a *application) runCommand() *cobra.Command {
group := &cobra.Command{
Use: "run",
Short: "View and manage Actions workflow runs",
Long: `List, view and watch the runs of a repository's Actions workflows, read their logs, download
their artifacts, and cancel, rerun or delete them.
Start a run with tea workflow run.`,
Long: "Work with the runs of a repository's Actions workflows. Start a run with tea workflow run.",
}
group.AddCommand(a.runListCommand(), a.runViewCommand(), a.runWatchCommand(), a.runCancelCommand(), a.runRerunCommand(), a.runDeleteCommand(),
a.runJobsCommand(), a.runLogsCommand(), a.runDownloadCommand(), a.artifactCommand())
internal/app/actions.go
+1 -3
View File
@@ -27,9 +27,7 @@ func (a *application) workflowCommand() *cobra.Command {
group := &cobra.Command{
Use: "workflow",
Short: "View, run, enable and disable Actions workflows",
Long: `View the Actions workflows of a repository, dispatch them, and enable or disable them.
List and inspect the runs of workflows with tea run.`,
Long: "Work with the Actions workflows of a repository. Inspect their runs with tea run.",
}
group.AddCommand(a.workflowListCommand(), a.workflowViewCommand(), a.workflowRunCommand(), a.workflowStateCommand(true), a.workflowStateCommand(false))
return group
internal/app/auth.go
+8 -24
View File
@@ -103,7 +103,8 @@ func (a *application) authCommand() *cobra.Command {
tea keeps the accounts of each instance in hosts.yml and their tokens in the system
keyring, or in a private file when you choose so. One account per instance is active;
--user or TEA_USER selects another for a single command. GITEA_TOKEN, together with
GITEA_INSTANCE_URL or TEA_HOST, replaces the stored credentials of its instance.`}
GITEA_INSTANCE_URL or TEA_HOST, replaces the stored credentials of its instance. See
tea help environment for how commands select the instance.`}
group.AddCommand(a.loginCommand(), a.logoutCommand(), a.authStatusCommand(), a.authSwitchCommand(), a.authRefreshCommand(), a.authTokenCommand(), a.setupGitCommand(), a.gitCredentialCommand())
return group
}
@@ -124,17 +125,8 @@ func (a *application) loginCommand() *cobra.Command {
login := &cobra.Command{
Use: "login", Short: "Log in to a Gitea instance", Args: argsExact(0),
Annotations: map[string]string{"tea.text": "login does not return a resource", "tea.confirm": "true"},
Long: `Log in to a Gitea instance.
On a terminal without a method flag, tea asks for the instance, how to log in, where to
keep the token and whether git should use tea for the instance. Otherwise choose one
method:
--with-token read an access token from stdin, or ask for it on a terminal
--oauth, --web authorize tea in a web browser
--ssh-key FILE sign requests with an SSH private key
--ssh-agent-key FP sign requests with the key of fingerprint FP in ssh-agent
--ssh-agent-principal P sign requests with the ssh-agent certificate of principal P
Long: `Log in to a Gitea instance. On a terminal without a method flag, tea asks for the instance,
how to log in, where to keep the token and whether git should use tea for the instance.
Create a token on the instance under Settings > Applications. Logging in to an account
that tea already has replaces its stored credential after a confirmation (or with --yes).`,
@@ -427,11 +419,8 @@ func (a *application) authStatusCommand() *cobra.Command {
status := &cobra.Command{
Use: "status", Short: "Show the accounts tea can use", Args: argsExact(0),
Long: `Show the accounts tea can use on each instance, the active one, and how they
authenticate. --verify asks each instance whether the credentials still work.
A GITEA_TOKEN in the environment shows under its instance, where it replaces the stored
accounts. tea auth status fails with exit code 4 when there is no account, or when a
credential is missing or rejected.`,
authenticate. Fails with exit code 4 when there is no account, or when a credential is
missing or rejected.`,
Example: `$ tea auth status
# Check the credentials against their instances
$ tea auth status --verify
@@ -637,8 +626,7 @@ func (a *application) authSwitchCommand() *cobra.Command {
Annotations: textOutput("switching accounts does not return a resource"), ValidArgsFunction: a.completeAccounts,
Long: `Switch the active account of an instance, which commands use unless --user or TEA_USER
selects another. With two accounts, tea auth switch toggles between them; with more, it
asks which one on a terminal. The instance is the one of the current repository, else
--host, TEA_HOST, default_host or the only instance.`,
asks which one on a terminal.`,
Example: "$ tea auth switch\n$ tea auth switch bob\n$ tea auth switch bob --host gitea.com",
RunE: func(cmd *cobra.Command, args []string) error {
t, err := a.instanceTarget(cmd.Context())
@@ -718,11 +706,7 @@ func (a *application) logoutCommand() *cobra.Command {
Annotations: map[string]string{"tea.text": "logout does not return a resource", "tea.confirm": "true"},
Long: `Log out of an account: tea forgets the account and deletes its stored credential. Git's
other credential helpers are asked to forget what they stored for the account on the
instance, such as a copy of its token that a keychain kept after a push.
Without an account argument or --user, tea logs out of the active account of the
current repository's instance, else of --host, TEA_HOST, default_host or the only
instance.`,
instance, such as a copy of its token that a keychain kept after a push.`,
Example: "$ tea auth logout\n$ tea auth logout bob --host gitea.com\n# Without confirmation\n$ tea auth logout alice --yes",
RunE: func(cmd *cobra.Command, args []string) error {
if len(args) == 1 {
internal/app/config.go
+6 -22
View File
@@ -175,28 +175,12 @@ Preferences live in config.yml and instance settings in hosts.yml, in the config
directory ($TEA_CONFIG_DIR, or tea under the XDG config directory); tea config path prints
both files. Environment variables that override settings are listed in tea help environment.
Preferences (tea config set <key> <value>):
default_host instance used when no --host, environment variable or repository selects one
git_protocol https or ssh, for clone and checkout remotes
editor command that edits bodies
prompt enabled or disabled
pager command that pages long output
browser command that opens web pages; never disables opening
color auto, always or never
hyperlinks auto, always or never: link the first column of lists to its web page
markdown auto or raw: render markdown bodies on a terminal, or print them as written
remote Git remote that selects the repository
aliases command shortcuts; manage them with tea alias
Instance settings (tea config set --host <url> <key> <value>):
user active account; change it with tea auth switch
ssh_host SSH host[:port] when it differs from the web host
insecure true skips TLS certificate verification
git_protocol https or ssh, overriding the preference for this instance
oauth_client_id OAuth application used by tea auth login --oauth
Account settings (tea config set --host <url> --user <name> <key> <value>):
ssh_key, ssh_agent, ssh_certificate_principal, ssh_key_fingerprint`}
Preferences: default_host, git_protocol, editor, prompt (enabled or disabled), pager,
browser (never disables opening), color, hyperlinks and markdown (auto or raw), remote and
aliases (see tea alias).
Instance settings (--host <url>): user, ssh_host, insecure, git_protocol, oauth_client_id.
Account settings (--host <url> --user <name>): ssh_key, ssh_agent,
ssh_certificate_principal, ssh_key_fingerprint.`}
group.AddCommand(&cobra.Command{
Use: "path", Short: "Print the paths of the settings files", Args: argsExact(0),
Annotations: map[string]string{"tea.text": "config path prints text", "tea.offline": "true"},
internal/app/notifications.go
+2 -5
View File
@@ -26,11 +26,8 @@ type notificationScope struct {
}
func (a *application) notificationCommand() *cobra.Command {
group := &cobra.Command{Use: "notification", Short: "Read and triage your notifications", Long: `Read and triage the notifications of your account.
Commands act on your whole inbox. -R OWNER/REPO limits them to one repository, and
--this-repo to the repository of the current directory. The IDs that tea notification
list shows identify notification threads; they are not issue numbers.`}
group := &cobra.Command{Use: "notification", Short: "Read and triage your notifications", Long: `Read and triage the notifications of your account, across your whole inbox unless -R or
--this-repo selects a repository. IDs identify notification threads, not issue numbers.`}
var mine, thisRepo bool
group.PersistentFlags().BoolVar(&mine, "mine", false, "Read your whole inbox (the default)")
_ = group.PersistentFlags().MarkHidden("mine")
internal/app/pull_review.go
+1 -6
View File
@@ -146,12 +146,7 @@ $ tea pr review 13
# Start a pending review with inline comments, then submit it
$ tea pr review 13 --pending --comments-file inline.json
$ tea pr review submit 13 --approve
# See who reviewed, then reply to and resolve an inline comment
$ tea pr review list 13
$ tea pr review reply 13 36 -b "Done"
$ tea pr review resolve 36`
$ tea pr review submit 13 --approve`
func (a *application) pullReviewCommand() *cobra.Command {
review := a.reviewCreateCommand("review [<number> | <url> | <branch>]", "Review a pull request or manage its reviews")
internal/app/teams.go
+3 -9
View File
@@ -91,9 +91,7 @@ func (a *application) completeTeamThen(next func(ctx context.Context, t target,
func (a *application) teamCommand() *cobra.Command {
group := &cobra.Command{Use: "team", Short: "Manage organization teams and access", Long: `Manage the teams of an organization: what they may do in its repositories, who belongs to
them, and which repositories they can reach.
` + teamArguments}
them, and which repositories they can reach.`}
group.AddCommand(a.teamListCommand(), a.teamViewCommand(), a.teamCreateCommand(), a.teamEditCommand(), a.teamDeleteCommand(), a.teamMemberCommand(), a.teamRepoCommand())
return group
}
@@ -485,9 +483,7 @@ func joinNames(names []string) string {
func (a *application) teamMemberCommand() *cobra.Command {
group := &cobra.Command{Use: "member", Short: "Manage team members", Long: `List, add and remove the members of a team. Adding a user to a team of an organization
also makes them a member of the organization.
` + teamArguments}
also makes them a member of the organization.`}
var limit, page int
list := &cobra.Command{
Use: "list <team>", Short: "List team members", Args: argsExact(1), ValidArgsFunction: a.completeTeams(),
@@ -585,9 +581,7 @@ func teamRepository(team services.Team, raw string) (string, error) {
func (a *application) teamRepoCommand() *cobra.Command {
group := &cobra.Command{Use: "repo", Short: "Manage team repository access", Long: `List the repositories a team can reach, and grant or revoke its access to repositories of
its organization. Repositories are named alone, such as service, or as ORG/NAME.
` + teamArguments}
its organization. Repositories are named alone, such as service, or as ORG/NAME.`}
var limit, page int
list := &cobra.Command{
Use: "list <team>", Short: "List team repositories", Args: argsExact(1), ValidArgsFunction: a.completeTeams(),
internal/app/webhooks.go
+2 -5
View File
@@ -260,11 +260,8 @@ $ tea webhook edit 3 --events push,release --authorization-header-file header.tx
command.Args = usageArgs(cobra.MaximumNArgs(1))
command.Long = `Create a webhook that delivers events to a URL, by default as JSON for push events.
Events: create, delete, fork, push, issues (every issue event), issues_only, issue_assign,
issue_label, issue_milestone, issue_comment, pull_request (every pull request event),
pull_request_only, pull_request_assign, pull_request_label, pull_request_milestone,
pull_request_comment, pull_request_review, pull_request_sync, pull_request_review_request, wiki,
repository, release, package, status, workflow_run, workflow_job.
Events: ` + strings.Join(services.WebhookEvents, ", ") + `; issues and pull_request
include every issue or pull request event.
Types: ` + strings.Join(services.WebhookTypes, ", ") + `. Slack webhooks need
--config channel=#name; other types take their settings through --config too.`