add debug mode and update readme (#805)

Fix #456
Fix #207

Reviewed-on: https://gitea.com/gitea/tea/pulls/805

README.md

@@ -11,69 +11,79 @@
 ![demo gif](./demo.gif)
 
 ```
-   tea - command line tool to interact with Gitea
+NAME:
-   version 0.8.0-preview
+  tea - command line tool to interact with Gitea
 
- USAGE
+USAGE:
-   tea command [subcommand] [command options] [arguments...]
+  tea [global options] [command [command options]]
 
- DESCRIPTION
+VERSION:
-   tea is a productivity helper for Gitea. It can be used to manage most entities on
+  Version: 0.10.1+15-g8876fe3  golang: 1.25.0  go-sdk: v0.21.0
-   one or multiple Gitea instances & provides local helpers like 'tea pr checkout'.
-   
-   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
+DESCRIPTION:
-   help, h  Shows a list of commands or help for one command
+  tea is a productivity helper for Gitea. It can be used to manage most entities on
-   ENTITIES:
+  one or multiple Gitea instances & provides local helpers like 'tea pr checkout'.
-     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
-     release assets, release asset, r a  Manage release attachments
-     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
-     whoami                         Show current logged in user
 
- OPTIONS
+  tea tries to make use of context provided by the repository in $PWD if available.
-   --help, -h     show help (default: false)
+  tea works best in a upstream/fork workflow, when the local main branch tracks the
-   --version, -v  print the version (default: false)
+  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.
 
- EXAMPLES
+COMMANDS:
-   tea login add                       # add a login once to get started
+  help, h  Shows a list of commands or help for one command
 
-   tea pulls                           # list open pulls for the repo in $PWD
+  ENTITIES:
-   tea pulls --repo $HOME/foo          # list open pulls for the repo in $HOME/foo
+    issues, issue, i                  List, create and update issues
-   tea pulls --remote upstream         # list open pulls for the repo pointed at by
+    pulls, pull, pr                   Manage and checkout pull requests
-                                       # your local "upstream" git remote
+    labels, label                     Manage issue labels
-   # list open pulls for any gitea repo at the given login instance
+    milestones, milestone, ms         List and create milestones
-   tea pulls --repo gitea/tea --login gitea.com
+    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
+    branches, branch, b               Consult branches
+    comment, c                        Add a comment to an issue / pr
 
-   tea milestone issues 0.7.0          # view open issues for milestone '0.7.0'
+  HELPERS:
-   tea issue 189                       # view contents of issue 189
+    open, o                         Open something of the repository in web browser
-   tea open 189                        # open web ui for issue 189
+    notifications, notification, n  Show notifications
-   tea open milestones                 # open web ui for milestones
+    clone, C                        Clone a repository locally
 
-   # send gitea desktop notifications every 5 minutes (bash + libnotify)
+  MISCELLANEOUS:
-   while :; do tea notifications --mine -o simple | xargs -i notify-send {}; sleep 300; done
+    whoami    Show current logged in user
+    admin, a  Operations requiring admin access on the Gitea instance
 
- ABOUT
+  SETUP:
-   Written & maintained by The Gitea Authors.
+    logins, login  Log in to a Gitea server
-   If you find a bug or want to contribute, we'll welcome you at https://gitea.com/gitea/tea.
+    logout         Log out from a Gitea server
-   More info about Gitea itself on https://about.gitea.com.
+
+GLOBAL OPTIONS:
+  --debug, --vvv  Enable debug mode (default: false)
+  --help, -h      show help
+  --version, -v   print the version
+
+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 --mine -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://about.gitea.com.
 ```
 
 - [Compare features with other git forge CLIs](./FEATURE-COMPARISON.md)

cmd/clone.go

@@ -10,6 +10,7 @@ import (
 	"code.gitea.io/tea/cmd/flags"
 	"code.gitea.io/tea/modules/config"
 	"code.gitea.io/tea/modules/context"
+	"code.gitea.io/tea/modules/debug"
 	"code.gitea.io/tea/modules/git"
 	"code.gitea.io/tea/modules/interact"
 	"code.gitea.io/tea/modules/task"
@@ -68,12 +69,15 @@ func runRepoClone(ctx stdctx.Context, cmd *cli.Command) error {
 		return err
 	}
 
+	debug.Printf("Cloning repository %s into %s", url.String(), dir)
+
 	owner, repo = utils.GetOwnerAndRepo(url.Path, login.User)
 	if url.Host != "" {
 		login = config.GetLoginByHost(url.Host)
 		if login == nil {
 			return fmt.Errorf("No login configured matching host '%s', run `tea login add` first", url.Host)
 		}
+		debug.Printf("Matched login '%s' for host '%s'", login.Name, url.Host)
 	}
 
 	_, err = task.RepoClone(

main.go

@@ -10,10 +10,12 @@ import (
 	"os"
 
 	"code.gitea.io/tea/cmd"
+	"code.gitea.io/tea/modules/debug"
 )
 
 func main() {
 	app := cmd.App()
+	app.Flags = append(app.Flags, debug.CliFlag())
 	err := app.Run(context.Background(), os.Args)
 	if err != nil {
 		// app.Run already exits for errors implementing ErrorCoder,

modules/config/login.go

@@ -17,6 +17,7 @@ import (
 	"time"
 
 	"code.gitea.io/sdk/gitea"
+	"code.gitea.io/tea/modules/debug"
 	"code.gitea.io/tea/modules/theme"
 	"code.gitea.io/tea/modules/utils"
 	"github.com/charmbracelet/huh"
@@ -277,6 +278,9 @@ func (l *Login) Client(options ...gitea.ClientOption) *gitea.Client {
 	}
 
 	options = append(options, gitea.SetToken(l.Token), gitea.SetHTTPClient(httpClient))
+	if debug.IsDebug() {
+		options = append(options, gitea.SetDebugMode())
+	}
 
 	if ok, err := utils.IsKeyEncrypted(l.SSHKey); ok && err == nil && l.SSHPassphrase == "" {
 		if err := huh.NewInput().

modules/debug/debug.go

@@ -0,0 +1,44 @@
+// Copyright 2025 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package debug
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/urfave/cli/v3"
+)
+
+var debug bool
+
+// IsDebug returns true if debug mode is enabled
+func IsDebug() bool {
+	return debug
+}
+
+// SetDebug sets the debug mode
+func SetDebug(on bool) {
+	debug = on
+}
+
+// Printf prints debug information if debug mode is enabled
+func Printf(info string, args ...any) {
+	if debug {
+		fmt.Printf("DEBUG: "+info+"\n", args...)
+	}
+}
+
+// CliFlag returns the CLI flag for debug mode
+func CliFlag() cli.Flag {
+	return &cli.BoolFlag{
+		Name:    "debug",
+		Aliases: []string{"vvv"},
+		Usage:   "Enable debug mode",
+		Value:   false,
+		Action: func(ctx context.Context, cmd *cli.Command, v bool) error {
+			SetDebug(v)
+			return nil
+		},
+	}
+}