From ab8ba6df4f79ae0e234a429bafba4426c6a6cf79 Mon Sep 17 00:00:00 2001 From: bircni Date: Mon, 12 Oct 2026 20:14:09 +0200 Subject: [PATCH] docs: shorten help and migration texts to gh-like brevity 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 --- docs/migration-1.0.md | 30 +++++++----------------------- internal/app/action_runs.go | 5 +---- internal/app/actions.go | 4 +--- internal/app/auth.go | 32 ++++++++------------------------ internal/app/config.go | 28 ++++++---------------------- internal/app/notifications.go | 7 ++----- internal/app/pull_review.go | 7 +------ internal/app/teams.go | 12 +++--------- internal/app/webhooks.go | 7 ++----- 9 files changed, 31 insertions(+), 101 deletions(-) diff --git a/docs/migration-1.0.md b/docs/migration-1.0.md index dc88d3f3..a97834ec 100644 --- a/docs/migration-1.0.md +++ b/docs/migration-1.0.md @@ -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 diff --git a/internal/app/action_runs.go b/internal/app/action_runs.go index ac22bdec..4349bc07 100644 --- a/internal/app/action_runs.go +++ b/internal/app/action_runs.go @@ -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()) diff --git a/internal/app/actions.go b/internal/app/actions.go index 5ab6262f..7293aa34 100644 --- a/internal/app/actions.go +++ b/internal/app/actions.go @@ -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 diff --git a/internal/app/auth.go b/internal/app/auth.go index 6312bec9..7871de05 100644 --- a/internal/app/auth.go +++ b/internal/app/auth.go @@ -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 { diff --git a/internal/app/config.go b/internal/app/config.go index 3794c471..1fef896d 100644 --- a/internal/app/config.go +++ b/internal/app/config.go @@ -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 ): - 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 ): - 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 --user ): - 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 ): user, ssh_host, insecure, git_protocol, oauth_client_id. +Account settings (--host --user ): 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"}, diff --git a/internal/app/notifications.go b/internal/app/notifications.go index 7ae7fae1..fb66e0d6 100644 --- a/internal/app/notifications.go +++ b/internal/app/notifications.go @@ -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") diff --git a/internal/app/pull_review.go b/internal/app/pull_review.go index c1379528..c40db618 100644 --- a/internal/app/pull_review.go +++ b/internal/app/pull_review.go @@ -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 [ | | ]", "Review a pull request or manage its reviews") diff --git a/internal/app/teams.go b/internal/app/teams.go index 9a6b40ef..c8295e61 100644 --- a/internal/app/teams.go +++ b/internal/app/teams.go @@ -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 ", 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 ", Short: "List team repositories", Args: argsExact(1), ValidArgsFunction: a.completeTeams(), diff --git a/internal/app/webhooks.go b/internal/app/webhooks.go index 440ce3b1..9448fd73 100644 --- a/internal/app/webhooks.go +++ b/internal/app/webhooks.go @@ -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.`