diff --git a/README.md b/README.md index 2db5e41..cd1665c 100644 --- a/README.md +++ b/README.md @@ -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 -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) -![demo gif](https://dl.gitea.io/screenshots/tea_demo.gif) +``` + 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 --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 diff --git a/cmd/autocomplete.go b/cmd/autocomplete.go index ca28d38..64e7289 100644 --- a/cmd/autocomplete.go +++ b/cmd/autocomplete.go @@ -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: " (bash, zsh, powershell)", diff --git a/cmd/categories.go b/cmd/categories.go new file mode 100644 index 0000000..4b2088b --- /dev/null +++ b/cmd/categories.go @@ -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" +) diff --git a/cmd/issues.go b/cmd/issues.go index 7febb0b..e24b738 100644 --- a/cmd/issues.go +++ b/cmd/issues.go @@ -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: "[]", diff --git a/cmd/labels.go b/cmd/labels.go index 722e1d0..bb27cb1 100644 --- a/cmd/labels.go +++ b/cmd/labels.go @@ -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, diff --git a/cmd/login.go b/cmd/login.go index 5b84e07..561f04c 100644 --- a/cmd/login.go +++ b/cmd/login.go @@ -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: "[]", diff --git a/cmd/logout.go b/cmd/logout.go index c676b9e..ecaafcf 100644 --- a/cmd/logout.go +++ b/cmd/logout.go @@ -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: "", diff --git a/cmd/milestones.go b/cmd/milestones.go index 74376f1..88b3509 100644 --- a/cmd/milestones.go +++ b/cmd/milestones.go @@ -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: "[]", diff --git a/cmd/notifications.go b/cmd/notifications.go index 3cab988..544329a 100644 --- a/cmd/notifications.go +++ b/cmd/notifications.go @@ -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, diff --git a/cmd/open.go b/cmd/open.go index 9868bc1..250c8a8 100644 --- a/cmd/open.go +++ b/cmd/open.go @@ -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, diff --git a/cmd/organizations.go b/cmd/organizations.go index d849097..3ad8687 100644 --- a/cmd/organizations.go +++ b/cmd/organizations.go @@ -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: "[]", diff --git a/cmd/pulls.go b/cmd/pulls.go index 6b1ab61..62aaa56 100644 --- a/cmd/pulls.go +++ b/cmd/pulls.go @@ -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: "[]", diff --git a/cmd/releases.go b/cmd/releases.go index 4a6792e..126938e 100644 --- a/cmd/releases.go +++ b/cmd/releases.go @@ -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, diff --git a/cmd/repos.go b/cmd/repos.go index 8622a67..3962706 100644 --- a/cmd/repos.go +++ b/cmd/repos.go @@ -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: "[/]", diff --git a/cmd/times.go b/cmd/times.go index 0a010f6..3f4c5e5 100644 --- a/cmd/times.go +++ b/cmd/times.go @@ -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.`, diff --git a/demo.gif b/demo.gif new file mode 100644 index 0000000..e102a93 Binary files /dev/null and b/demo.gif differ diff --git a/main.go b/main.go index c9e9c6f..ea114e8 100644 --- a/main.go +++ b/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) +}