Improve Documentation (#433)

- document more assumptions about usage context of gitea
- improve some flag descriptions (#432, #377)

Co-authored-by: Norwin <git@nroo.de>
Reviewed-on: https://gitea.com/gitea/tea/pulls/433
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Reviewed-by: 6543 <6543@obermui.de>
Co-authored-by: Norwin <noerw@noreply.gitea.io>
Co-committed-by: Norwin <noerw@noreply.gitea.io>
This commit is contained in:
Norwin 2021-12-03 02:33:56 +08:00 committed by 6543
parent ac25e89ebf
commit dc16643e0d
4 changed files with 24 additions and 15 deletions

View File

@ -8,16 +8,19 @@
``` ```
tea - command line tool to interact with Gitea tea - command line tool to interact with Gitea
version 0.7.0-preview version 0.8.0-preview
USAGE USAGE
tea command [subcommand] [command options] [arguments...] tea command [subcommand] [command options] [arguments...]
DESCRIPTION DESCRIPTION
tea is a productivity helper for Gitea. It can be used to manage most entities on one tea is a productivity helper for Gitea. It can be used to manage most entities on
or multiple Gitea instances and provides local helpers like 'tea pull checkout'. one or multiple Gitea instances & provides local helpers like 'tea pr 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 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 COMMANDS
help, h Shows a list of commands or help for one command 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 times, time, t Operate on tracked times of a repository's issues & pulls
organizations, organization, org List, create, delete organizations organizations, organization, org List, create, delete organizations
repos, repo Show repository details repos, repo Show repository details
comment, c Add a comment to an issue / pr
HELPERS: HELPERS:
open, o Open something of the repository in web browser open, o Open something of the repository in web browser
notifications, notification, n Show notifications notifications, notification, n Show notifications
clone, C Clone a repository locally
SETUP: SETUP:
logins, login Log in to a Gitea server logins, login Log in to a Gitea server
logout Log out from a Gitea server logout Log out from a Gitea server
shellcompletion, autocomplete Install shell completion for tea shellcompletion, autocomplete Install shell completion for tea
whoami Show current logged in user
OPTIONS OPTIONS
--help, -h show help (default: false) --help, -h show help (default: false)

View File

@ -18,17 +18,17 @@ var CmdPullsCreate = cli.Command{
Name: "create", Name: "create",
Aliases: []string{"c"}, Aliases: []string{"c"},
Usage: "Create a pull-request", Usage: "Create a pull-request",
Description: "Create a pull-request", Description: "Create a pull-request in the current repo",
Action: runPullsCreate, Action: runPullsCreate,
Flags: append([]cli.Flag{ Flags: append([]cli.Flag{
&cli.StringFlag{ &cli.StringFlag{
Name: "head", 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 <user>:<branch>",
}, },
&cli.StringFlag{ &cli.StringFlag{
Name: "base", Name: "base",
Aliases: []string{"b"}, 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...), }, flags.IssuePREditFlags...),
} }

View File

@ -27,11 +27,11 @@ var CmdReleaseCreate = cli.Command{
Flags: append([]cli.Flag{ Flags: append([]cli.Flag{
&cli.StringFlag{ &cli.StringFlag{
Name: "tag", Name: "tag",
Usage: "Tag name", Usage: "Tag name. If the tag does not exist yet, it will be created by Gitea",
}, },
&cli.StringFlag{ &cli.StringFlag{
Name: "target", 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{ &cli.StringFlag{
Name: "title", Name: "title",
@ -56,7 +56,7 @@ var CmdReleaseCreate = cli.Command{
&cli.StringSliceFlag{ &cli.StringSliceFlag{
Name: "asset", Name: "asset",
Aliases: []string{"a"}, Aliases: []string{"a"},
Usage: "List of files to attach", Usage: "Path to file attachment. Can be specified multiple times",
}, },
}, flags.AllDefaultFlags...), }, flags.AllDefaultFlags...),
} }

11
main.go
View File

@ -69,10 +69,13 @@ func formatBuiltWith(Tags string) string {
return " built with: " + strings.Replace(Tags, " ", ", ", -1) 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 var appDescription = `tea is a productivity helper for Gitea. It can be used to manage most entities on
or multiple Gitea instances and provides local helpers like 'tea pull checkout'. one or multiple Gitea instances & provides local helpers like 'tea pr 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 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(` var helpTemplate = bold(`