From dc16643e0df382681ced07059d81f03e06a383b7 Mon Sep 17 00:00:00 2001 From: Norwin Date: Fri, 3 Dec 2021 02:33:56 +0800 Subject: [PATCH] Improve Documentation (#433) - document more assumptions about usage context of gitea - improve some flag descriptions (#432, #377) Co-authored-by: Norwin Reviewed-on: https://gitea.com/gitea/tea/pulls/433 Reviewed-by: Lunny Xiao Reviewed-by: 6543 <6543@obermui.de> Co-authored-by: Norwin Co-committed-by: Norwin --- README.md | 16 +++++++++++----- cmd/pulls/create.go | 6 +++--- cmd/releases/create.go | 6 +++--- main.go | 11 +++++++---- 4 files changed, 24 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 87e9bd9..0a9ce22 100644 --- a/README.md +++ b/README.md @@ -8,16 +8,19 @@ ``` tea - command line tool to interact with Gitea - version 0.7.0-preview + version 0.8.0-preview USAGE tea command [subcommand] [command options] [arguments...] DESCRIPTION - tea is a productivity helper for Gitea. It can be used to manage most entities on one - or multiple Gitea instances and provides local helpers like 'tea pull checkout'. - tea makes use of context provided by the repository in $PWD if available, but is still - usable independently of $PWD. Configuration is persisted in $XDG_CONFIG_HOME/tea. + tea is a productivity helper for Gitea. It can be used to manage most entities on + one or multiple Gitea instances & provides local helpers like 'tea pr checkout'. + + tea tries to make use of context provided by the repository in $PWD if available. + tea works best in a upstream/fork workflow, when the local main branch tracks the + upstream repo. tea assumes that local git state is published on the remote before + doing operations with tea. Configuration is persisted in $XDG_CONFIG_HOME/tea. COMMANDS help, h Shows a list of commands or help for one command @@ -30,13 +33,16 @@ times, time, t Operate on tracked times of a repository's issues & pulls organizations, organization, org List, create, delete organizations repos, repo Show repository details + comment, c Add a comment to an issue / pr HELPERS: open, o Open something of the repository in web browser notifications, notification, n Show notifications + clone, C Clone a repository locally SETUP: logins, login Log in to a Gitea server logout Log out from a Gitea server shellcompletion, autocomplete Install shell completion for tea + whoami Show current logged in user OPTIONS --help, -h show help (default: false) diff --git a/cmd/pulls/create.go b/cmd/pulls/create.go index e1a1d11..bc9de1e 100644 --- a/cmd/pulls/create.go +++ b/cmd/pulls/create.go @@ -18,17 +18,17 @@ var CmdPullsCreate = cli.Command{ Name: "create", Aliases: []string{"c"}, Usage: "Create a pull-request", - Description: "Create a pull-request", + Description: "Create a pull-request in the current repo", Action: runPullsCreate, Flags: append([]cli.Flag{ &cli.StringFlag{ Name: "head", - Usage: "Set head branch (default is current one)", + Usage: "Branch name of the PR source (default is current one). To specify a different head repo, use :", }, &cli.StringFlag{ Name: "base", Aliases: []string{"b"}, - Usage: "Set base branch (default is default branch)", + Usage: "Branch name of the PR target (default is repos default branch)", }, }, flags.IssuePREditFlags...), } diff --git a/cmd/releases/create.go b/cmd/releases/create.go index ef203f3..3fe3483 100644 --- a/cmd/releases/create.go +++ b/cmd/releases/create.go @@ -27,11 +27,11 @@ var CmdReleaseCreate = cli.Command{ Flags: append([]cli.Flag{ &cli.StringFlag{ Name: "tag", - Usage: "Tag name", + Usage: "Tag name. If the tag does not exist yet, it will be created by Gitea", }, &cli.StringFlag{ Name: "target", - Usage: "Target refs, branch name or commit id", + Usage: "Target branch name or commit hash. Defaults to the default branch of the repo", }, &cli.StringFlag{ Name: "title", @@ -56,7 +56,7 @@ var CmdReleaseCreate = cli.Command{ &cli.StringSliceFlag{ Name: "asset", Aliases: []string{"a"}, - Usage: "List of files to attach", + Usage: "Path to file attachment. Can be specified multiple times", }, }, flags.AllDefaultFlags...), } diff --git a/main.go b/main.go index 580cb38..fe7a65a 100644 --- a/main.go +++ b/main.go @@ -69,10 +69,13 @@ func formatBuiltWith(Tags string) string { return " built with: " + strings.Replace(Tags, " ", ", ", -1) } -var appDescription = `tea is a productivity helper for Gitea. It can be used to manage most entities on one -or multiple Gitea instances and provides local helpers like 'tea pull checkout'. -tea makes use of context provided by the repository in $PWD if available, but is still -usable independently of $PWD. Configuration is persisted in $XDG_CONFIG_HOME/tea. +var appDescription = `tea is a productivity helper for Gitea. It can be used to manage most entities on +one or multiple Gitea instances & provides local helpers like 'tea pr checkout'. + +tea tries to make use of context provided by the repository in $PWD if available. +tea works best in a upstream/fork workflow, when the local main branch tracks the +upstream repo. tea assumes that local git state is published on the remote before +doing operations with tea. Configuration is persisted in $XDG_CONFIG_HOME/tea. ` var helpTemplate = bold(`