Proper help text & new README structure (#311)
add cli.AppHelpTemplate for customization customize tea help view tea --version : improve parseability Rework README to include tea help output It's an antipattern to have different help texts aimed at the same users. So now that we have a good cli help text, lets use it here. This eases maintenance, and at the same time gives an honest impression on what we have to offer, while also encouraging to improve the internal help text in the future. I feel a bit sad for the GIF, but it was becoming outdated anyway.. group commands by category add new demo gif shows the (probably) most useful workflow readme improvement Merge branch 'master' into improve-app-help code review Merge branch 'master' into improve-app-help restructure installation section Co-authored-by: Norwin Roosen <git@nroo.de> Reviewed-on: https://gitea.com/gitea/tea/pulls/311 Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com> Reviewed-by: khmarbaise <khmarbaise@noreply.gitea.io> Co-Authored-By: Norwin <noerw@noreply.gitea.io> Co-Committed-By: Norwin <noerw@noreply.gitea.io>
This commit is contained in:
Norwin
Lunny Xiao
parent
43e9943757
commit
43a58bdba1
130
README.md
130
README.md
|
|
@ -2,67 +2,95 @@
|
|||
|
||||
[](https://opensource.org/licenses/MIT) [](https://gitea.com/gitea/tea/releases) [](https://drone.gitea.com/gitea/tea) [](https://discord.gg/Gitea) [](https://goreportcard.com/report/code.gitea.io/tea) [](https://godoc.org/code.gitea.io/tea)
|
||||
|
||||
## The official CLI interface for gitea
|
||||
### The official CLI for Gitea
|
||||
|
||||
Tea is a command line tool for interacting on one or more Gitea instances.
|
||||
It uses [code.gitea.io/sdk](https://code.gitea.io/sdk) and interacts with the Gitea API
|
||||
|
||||
|
||||
|
||||
```
|
||||
tea - command line tool to interact with Gitea
|
||||
version 0.7.0-preview
|
||||
|
||||
For a feature comparison with other git forge CLIs see [here](./FEATURE-COMPARISON.md).
|
||||
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.
|
||||
|
||||
COMMANDS
|
||||
help, h Shows a list of commands or help for one command
|
||||
ENTITIES:
|
||||
issues, issue, i List, create and update issues
|
||||
pulls, pull, pr Manage and checkout pull requests
|
||||
labels, label Manage issue labels
|
||||
milestones, milestone, ms List and create milestones
|
||||
releases, release, r Manage releases
|
||||
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
|
||||
HELPERS:
|
||||
open, o Open something of the repository in web browser
|
||||
notifications, notification, n Show notifications
|
||||
SETUP:
|
||||
logins, login Log in to a Gitea server
|
||||
logout Log out from a Gitea server
|
||||
shellcompletion, autocomplete Install shell completion for tea
|
||||
|
||||
OPTIONS
|
||||
--help, -h show help (default: false)
|
||||
--version, -v print the version (default: false)
|
||||
|
||||
EXAMPLES
|
||||
tea login add # add a login once to get started
|
||||
|
||||
tea pulls # list open pulls for the repo in $PWD
|
||||
tea pulls --repo $HOME/foo # list open pulls for the repo in $HOME/foo
|
||||
tea pulls --remote upstream # list open pulls for the repo pointed at by
|
||||
# your local "upstream" git remote
|
||||
# list open pulls for any gitea repo at the given login instance
|
||||
tea pulls --repo gitea/tea --login gitea.com
|
||||
|
||||
tea milestone issues 0.7.0 # view open issues for milestone '0.7.0'
|
||||
tea issue 189 # view contents of issue 189
|
||||
tea open 189 # open web ui for issue 189
|
||||
tea open milestones # open web ui for milestones
|
||||
|
||||
# send gitea desktop notifications every 5 minutes (bash + libnotify)
|
||||
while :; do tea notifications --all -o simple | xargs -i notify-send {}; sleep 300; done
|
||||
|
||||
ABOUT
|
||||
Written & maintained by The Gitea Authors.
|
||||
If you find a bug or want to contribute, we'll welcome you at https://gitea.com/gitea/tea.
|
||||
More info about Gitea itself on https://gitea.io.
|
||||
```
|
||||
|
||||
- [Compare features with other git forge CLIs](./FEATURE-COMPARISON.md)
|
||||
- tea uses [code.gitea.io/sdk](https://code.gitea.io/sdk) and interacts with the Gitea API.
|
||||
|
||||
## Installation
|
||||
|
||||
You can use the prebuilt binaries from [dl.gitea.io](https://dl.gitea.io/tea/)
|
||||
There are different ways to get `tea`:
|
||||
|
||||
To install from source, go 1.13 or newer is required:
|
||||
1. Install via your system package manager:
|
||||
- macOS via `brew` (gitea-maintained):
|
||||
```sh
|
||||
brew tap gitea/tap https://gitea.com/gitea/homebrew-gitea
|
||||
brew install tea
|
||||
```
|
||||
- arch linux ([gitea-tea](https://aur.archlinux.org/packages/gitea-tea), thirdparty)
|
||||
- alpine linux ([tea](https://pkgs.alpinelinux.org/packages?name=tea&branch=edge), thirdparty)
|
||||
|
||||
```sh
|
||||
go get code.gitea.io/tea
|
||||
go install code.gitea.io/tea
|
||||
```
|
||||
2. Use the prebuilt binaries from [dl.gitea.io](https://dl.gitea.io/tea/)
|
||||
|
||||
If you have `brew` installed, you can install `tea` via:
|
||||
3. Install from source (go 1.13 or newer is required):
|
||||
```sh
|
||||
go get code.gitea.io/tea
|
||||
go install code.gitea.io/tea
|
||||
```
|
||||
|
||||
```sh
|
||||
brew tap gitea/tap https://gitea.com/gitea/homebrew-gitea
|
||||
brew install tea
|
||||
```
|
||||
|
||||
Distribution packages exist for: **alpinelinux ([tea](https://pkgs.alpinelinux.org/packages?name=tea&branch=edge))** and **archlinux ([gitea-tea](https://aur.archlinux.org/packages/gitea-tea))**
|
||||
|
||||
|
||||
Shell completion can be added via `tea autocomplete --install`.
|
||||
|
||||
## Usage
|
||||
|
||||
First of all, you have to create a token on your `personal settings -> application` page of your gitea instance.
|
||||
Use this token to login with `tea`:
|
||||
|
||||
```sh
|
||||
tea login add --name=try --url=https://try.gitea.io --token=xxxxxx
|
||||
```
|
||||
|
||||
Now you can use the following `tea` subcommands.
|
||||
Detailed usage information is available via `tea <command> --help`.
|
||||
|
||||
```none
|
||||
login Log in to a Gitea server
|
||||
logout Log out from a Gitea server
|
||||
issues List, create and update issues
|
||||
pulls List, create, checkout and clean pull requests
|
||||
releases List, create, update and delete releases
|
||||
repos Operate with repositories
|
||||
labels Manage issue labels
|
||||
times Operate on tracked times of a repositorys issues and pulls
|
||||
open Open something of the repository on web browser
|
||||
notifications Show notifications
|
||||
milestones List and create milestones
|
||||
organizations List, create, delete organizations
|
||||
help, h Shows a list of commands or help for one command
|
||||
```
|
||||
|
||||
To fetch issues from different repos, use the `--remote` flag (when inside a gitea repository directory) or `--login` & `--repo` flags.
|
||||
4. Docker (thirdparty): [tgerczei/tea](https://hub.docker.com/r/tgerczei/tea)
|
||||
|
||||
## Compilation
|
||||
|
||||
|
|
|
|||
|
|
@ -19,6 +19,7 @@ import (
|
|||
var CmdAutocomplete = cli.Command{
|
||||
Name: "shellcompletion",
|
||||
Aliases: []string{"autocomplete"},
|
||||
Category: catSetup,
|
||||
Usage: "Install shell completion for tea",
|
||||
Description: "Install shell completion for tea",
|
||||
ArgsUsage: "<shell type> (bash, zsh, powershell)",
|
||||
|
|
|
|||
|
|
@ -0,0 +1,11 @@
|
|||
// Copyright 2020 The Gitea Authors. All rights reserved.
|
||||
// Use of this source code is governed by a MIT-style
|
||||
// license that can be found in the LICENSE file.
|
||||
|
||||
package cmd
|
||||
|
||||
var (
|
||||
catSetup = "SETUP"
|
||||
catEntities = "ENTITIES"
|
||||
catHelpers = "HELPERS"
|
||||
)
|
||||
|
|
@ -18,6 +18,7 @@ import (
|
|||
var CmdIssues = cli.Command{
|
||||
Name: "issues",
|
||||
Aliases: []string{"issue", "i"},
|
||||
Category: catEntities,
|
||||
Usage: "List, create and update issues",
|
||||
Description: "List, create and update issues",
|
||||
ArgsUsage: "[<issue index>]",
|
||||
|
|
|
|||
|
|
@ -15,6 +15,7 @@ import (
|
|||
var CmdLabels = cli.Command{
|
||||
Name: "labels",
|
||||
Aliases: []string{"label"},
|
||||
Category: catEntities,
|
||||
Usage: "Manage issue labels",
|
||||
Description: `Manage issue labels`,
|
||||
Action: runLabels,
|
||||
|
|
|
|||
|
|
@ -18,6 +18,7 @@ import (
|
|||
var CmdLogin = cli.Command{
|
||||
Name: "logins",
|
||||
Aliases: []string{"login"},
|
||||
Category: catSetup,
|
||||
Usage: "Log in to a Gitea server",
|
||||
Description: `Log in to a Gitea server`,
|
||||
ArgsUsage: "[<login name>]",
|
||||
|
|
|
|||
|
|
@ -13,6 +13,7 @@ import (
|
|||
// CmdLogout represents to logout a gitea server.
|
||||
var CmdLogout = cli.Command{
|
||||
Name: "logout",
|
||||
Category: catSetup,
|
||||
Usage: "Log out from a Gitea server",
|
||||
Description: `Log out from a Gitea server`,
|
||||
ArgsUsage: "<login name>",
|
||||
|
|
|
|||
|
|
@ -17,6 +17,7 @@ import (
|
|||
var CmdMilestones = cli.Command{
|
||||
Name: "milestones",
|
||||
Aliases: []string{"milestone", "ms"},
|
||||
Category: catEntities,
|
||||
Usage: "List and create milestones",
|
||||
Description: `List and create milestones`,
|
||||
ArgsUsage: "[<milestone name>]",
|
||||
|
|
|
|||
|
|
@ -17,6 +17,7 @@ import (
|
|||
var CmdNotifications = cli.Command{
|
||||
Name: "notifications",
|
||||
Aliases: []string{"notification", "n"},
|
||||
Category: catHelpers,
|
||||
Usage: "Show notifications",
|
||||
Description: "Show notifications, by default based of the current repo and unread one",
|
||||
Action: runNotifications,
|
||||
|
|
|
|||
|
|
@ -20,6 +20,7 @@ import (
|
|||
var CmdOpen = cli.Command{
|
||||
Name: "open",
|
||||
Aliases: []string{"o"},
|
||||
Category: catHelpers,
|
||||
Usage: "Open something of the repository in web browser",
|
||||
Description: `Open something of the repository in web browser`,
|
||||
Action: runOpen,
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@ import (
|
|||
var CmdOrgs = cli.Command{
|
||||
Name: "organizations",
|
||||
Aliases: []string{"organization", "org"},
|
||||
Category: catEntities,
|
||||
Usage: "List, create, delete organizations",
|
||||
Description: "Show organization details",
|
||||
ArgsUsage: "[<organization>]",
|
||||
|
|
|
|||
|
|
@ -21,6 +21,7 @@ import (
|
|||
var CmdPulls = cli.Command{
|
||||
Name: "pulls",
|
||||
Aliases: []string{"pull", "pr"},
|
||||
Category: catEntities,
|
||||
Usage: "Manage and checkout pull requests",
|
||||
Description: `Manage and checkout pull requests`,
|
||||
ArgsUsage: "[<pull index>]",
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@ import (
|
|||
var CmdReleases = cli.Command{
|
||||
Name: "releases",
|
||||
Aliases: []string{"release", "r"},
|
||||
Category: catEntities,
|
||||
Usage: "Manage releases",
|
||||
Description: "Manage releases",
|
||||
Action: releases.RunReleasesList,
|
||||
|
|
|
|||
|
|
@ -18,6 +18,7 @@ import (
|
|||
var CmdRepos = cli.Command{
|
||||
Name: "repos",
|
||||
Aliases: []string{"repo"},
|
||||
Category: catEntities,
|
||||
Usage: "Show repository details",
|
||||
Description: "Show repository details",
|
||||
ArgsUsage: "[<repo owner>/<repo name>]",
|
||||
|
|
|
|||
|
|
@ -11,9 +11,10 @@ import (
|
|||
|
||||
// CmdTrackedTimes represents the command to operate repositories' times.
|
||||
var CmdTrackedTimes = cli.Command{
|
||||
Name: "times",
|
||||
Aliases: []string{"time", "t"},
|
||||
Usage: "Operate on tracked times of a repository's issues & pulls",
|
||||
Name: "times",
|
||||
Aliases: []string{"time", "t"},
|
||||
Category: catEntities,
|
||||
Usage: "Operate on tracked times of a repository's issues & pulls",
|
||||
Description: `Operate on tracked times of a repository's issues & pulls.
|
||||
Depending on your permissions on the repository, only your own tracked
|
||||
times might be listed.`,
|
||||
|
|
|
|||
72
main.go
72
main.go
|
|
@ -22,24 +22,31 @@ var Version = "development"
|
|||
var Tags = ""
|
||||
|
||||
func main() {
|
||||
// make parsing tea --version easier, by printing /just/ the version string
|
||||
cli.VersionPrinter = func(c *cli.Context) { fmt.Fprintln(c.App.Writer, c.App.Version) }
|
||||
|
||||
app := cli.NewApp()
|
||||
app.Name = "tea"
|
||||
app.Usage = "Command line tool to interact with Gitea"
|
||||
app.Usage = "command line tool to interact with Gitea"
|
||||
app.Description = appDescription
|
||||
app.CustomAppHelpTemplate = helpTemplate
|
||||
app.Version = Version + formatBuiltWith(Tags)
|
||||
app.Commands = []*cli.Command{
|
||||
&cmd.CmdLogin,
|
||||
&cmd.CmdLogout,
|
||||
&cmd.CmdAutocomplete,
|
||||
|
||||
&cmd.CmdIssues,
|
||||
&cmd.CmdPulls,
|
||||
&cmd.CmdReleases,
|
||||
&cmd.CmdRepos,
|
||||
&cmd.CmdLabels,
|
||||
&cmd.CmdMilestones,
|
||||
&cmd.CmdReleases,
|
||||
&cmd.CmdTrackedTimes,
|
||||
&cmd.CmdOrgs,
|
||||
&cmd.CmdRepos,
|
||||
|
||||
&cmd.CmdOpen,
|
||||
&cmd.CmdNotifications,
|
||||
&cmd.CmdMilestones,
|
||||
&cmd.CmdOrgs,
|
||||
&cmd.CmdAutocomplete,
|
||||
}
|
||||
app.EnableBashCompletion = true
|
||||
err := app.Run(os.Args)
|
||||
|
|
@ -58,3 +65,56 @@ 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 helpTemplate = bold(`
|
||||
{{.Name}}{{if .Usage}} - {{.Usage}}{{end}}`) + `
|
||||
{{if .Version}}{{if not .HideVersion}}version {{.Version}}{{end}}{{end}}
|
||||
|
||||
USAGE
|
||||
{{if .UsageText}}{{.UsageText}}{{else}}{{.HelpName}}{{if .Commands}} command [subcommand] [command options]{{end}} {{if .ArgsUsage}}{{.ArgsUsage}}{{else}}[arguments...]{{end}}{{end}}{{if .Description}}
|
||||
|
||||
DESCRIPTION
|
||||
{{.Description | nindent 3 | trim}}{{end}}{{if .VisibleCommands}}
|
||||
|
||||
COMMANDS{{range .VisibleCategories}}{{if .Name}}
|
||||
{{.Name}}:{{range .VisibleCommands}}
|
||||
{{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{else}}{{range .VisibleCommands}}
|
||||
{{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{end}}{{end}}{{end}}{{if .VisibleFlags}}
|
||||
|
||||
OPTIONS
|
||||
{{range $index, $option := .VisibleFlags}}{{if $index}}
|
||||
{{end}}{{$option}}{{end}}{{end}}
|
||||
|
||||
EXAMPLES
|
||||
tea login add # add a login once to get started
|
||||
|
||||
tea pulls # list open pulls for the repo in $PWD
|
||||
tea pulls --repo $HOME/foo # list open pulls for the repo in $HOME/foo
|
||||
tea pulls --remote upstream # list open pulls for the repo pointed at by
|
||||
# your local "upstream" git remote
|
||||
# list open pulls for any gitea repo at the given login instance
|
||||
tea pulls --repo gitea/tea --login gitea.com
|
||||
|
||||
tea milestone issues 0.7.0 # view open issues for milestone '0.7.0'
|
||||
tea issue 189 # view contents of issue 189
|
||||
tea open 189 # open web ui for issue 189
|
||||
tea open milestones # open web ui for milestones
|
||||
|
||||
# send gitea desktop notifications every 5 minutes (bash + libnotify)
|
||||
while :; do tea notifications --all -o simple | xargs -i notify-send {}; sleep 300; done
|
||||
|
||||
ABOUT
|
||||
Written & maintained by The Gitea Authors.
|
||||
If you find a bug or want to contribute, we'll welcome you at https://gitea.com/gitea/tea.
|
||||
More info about Gitea itself on https://gitea.io.
|
||||
`
|
||||
|
||||
func bold(t string) string {
|
||||
return fmt.Sprintf("\033[1m%s\033[0m", t)
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue