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>

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
+   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
    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)

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 <user>:<branch>",
 		},
 		&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...),
 }

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...),
 }

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
+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(`