Proper help text & new README structure #311

Merged
lunny merged 11 commits from noerw/tea:improve-app-help into master 2020-12-21 13:37:21 +00:00
17 changed files with 172 additions and 60 deletions

130
README.md
View File

@ -2,67 +2,95 @@
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Release](https://raster.shields.io/badge/dynamic/json.svg?label=release&url=https://gitea.com/api/v1/repos/gitea/tea/releases&query=$[0].tag_name)](https://gitea.com/gitea/tea/releases) [![Build Status](https://drone.gitea.com/api/badges/gitea/tea/status.svg)](https://drone.gitea.com/gitea/tea) [![Join the chat at https://img.shields.io/discord/322538954119184384.svg](https://img.shields.io/discord/322538954119184384.svg)](https://discord.gg/Gitea) [![Go Report Card](https://goreportcard.com/badge/code.gitea.io/tea)](https://goreportcard.com/report/code.gitea.io/tea) [![GoDoc](https://godoc.org/code.gitea.io/tea?status.svg)](https://godoc.org/code.gitea.io/tea)
## The official CLI interface for gitea
### The official CLI for Gitea
noerw marked this conversation as resolved
Review

I would suggest to use ### The official CLI for gitea instead.

I would suggest to use `### The official CLI for gitea` instead.
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
![demo gif](./demo.gif)
Review

@techknowlogick can you update demo gif on dl.gitea.io with the gif of this pull?

@techknowlogick can you update demo gif on dl.gitea.io with the gif of this pull?
![demo gif](https://dl.gitea.io/screenshots/tea_demo.gif)
```
tea - command line tool to interact with Gitea
version 0.7.0-preview
noerw marked this conversation as resolved Outdated
Outdated
Review

version 0.7.0 preview ... or so (should be changed on release)

version 0.7.0 preview ... or so (should be changed on release)
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
```
noerw marked this conversation as resolved Outdated
Outdated
Review

I'd like to add ### macOS before these lines and also move them before alphinelinux since this is an official one.

I'd like to add `### macOS` before these lines and also move them before alphinelinux since this is an official one.
```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

View File

@ -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)",

11
cmd/categories.go Normal file
View File

@ -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"
)

View File

@ -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>]",

View File

@ -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,

View File

@ -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>]",

View File

@ -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>",

View File

@ -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>]",

View File

@ -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,

View File

@ -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,

View File

@ -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>]",

View File

@ -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>]",

View File

@ -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,

View File

@ -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>]",

View File

@ -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.`,

BIN
demo.gif Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 621 KiB

72
main.go
View File

@ -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'.
noerw marked this conversation as resolved Outdated
Outdated
Review
-or multiple Gitea instances, and also provides local helpers like 'tea pull checkout'.
+or multiple Gitea instances and provides local helpers like 'tea pull checkout'.
```diff -or multiple Gitea instances, and also provides local helpers like 'tea pull checkout'. +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)
}