Git/cheat
1
0
Fork 0
mirror of https://github.com/cheat/cheat.git synced 2026-03-07 11:13:33 +01:00
Code Issues Packages Projects Releases Wiki Activity

feat: migrate from docopt to cobra for CLI argument parsing

Browse Source 
Replace docopt-go with spf13/cobra, giving cheat a built-in
`--completion` flag that dynamically generates shell completions for
bash, zsh, fish, and powershell. This replaces the manually-maintained
static completion scripts and resolves the root cause of multiple
completion issues (#768, #705, #633, #632, #476).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Christopher Allen Lane
2026-02-15 17:33:47 -05:00
parent ca1ec0e38d
commit 9b92261604
119 changed files with 14204 additions and 3127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
cmd/cheat/cmd_conf.go
View File

@@ -3,9 +3,11 @@ package main
import (
"fmt"
"github.com/spf13/cobra"
"github.com/cheat/cheat/internal/config"
)
func cmdConf(_ map[string]interface{}, conf config.Config) {
func cmdConf(_ *cobra.Command, _ []string, conf config.Config) {
fmt.Println(conf.Path)
}

4
cmd/cheat/cmd_directories.go
View File

@@ -5,12 +5,14 @@ import (
"fmt"
"text/tabwriter"
"github.com/spf13/cobra"
"github.com/cheat/cheat/internal/config"
"github.com/cheat/cheat/internal/display"
)
// cmdDirectories lists the configured cheatpaths.
func cmdDirectories(_ map[string]interface{}, conf config.Config) {
func cmdDirectories(_ *cobra.Command, _ []string, conf config.Config) {
// initialize a tabwriter to produce cleanly columnized output
var out bytes.Buffer

23
cmd/cheat/cmd_edit.go
View File

@@ -7,6 +7,8 @@ import (
"path/filepath"
"strings"
"github.com/spf13/cobra"
"github.com/cheat/cheat/internal/cheatpath"
"github.com/cheat/cheat/internal/config"
"github.com/cheat/cheat/internal/sheet"
@@ -14,9 +16,9 @@ import (
)
// cmdEdit opens a cheatsheet for editing (or creates it if it doesn't exist).
func cmdEdit(opts map[string]interface{}, conf config.Config) {
func cmdEdit(cmd *cobra.Command, _ []string, conf config.Config) {
cheatsheet := opts["--edit"].(string)
cheatsheet, _ := cmd.Flags().GetString("edit")
// validate the cheatsheet name
if err := sheet.Validate(cheatsheet); err != nil {
@@ -30,10 +32,11 @@ func cmdEdit(opts map[string]interface{}, conf config.Config) {
fmt.Fprintf(os.Stderr, "failed to list cheatsheets: %v\n", err)
os.Exit(1)
}
if opts["--tag"] != nil {
if cmd.Flags().Changed("tag") {
tagVal, _ := cmd.Flags().GetString("tag")
cheatsheets = sheets.Filter(
cheatsheets,
strings.Split(opts["--tag"].(string), ","),
strings.Split(tagVal, ","),
)
}
@@ -90,14 +93,14 @@ func cmdEdit(opts map[string]interface{}, conf config.Config) {
// call to `exec.Command` will fail.
parts := strings.Fields(conf.Editor)
editor := parts[0]
args := append(parts[1:], editpath)
editorArgs := append(parts[1:], editpath)
// edit the cheatsheet
cmd := exec.Command(editor, args...)
cmd.Stdout = os.Stdout
cmd.Stdin = os.Stdin
cmd.Stderr = os.Stderr
if err := cmd.Run(); err != nil {
editorCmd := exec.Command(editor, editorArgs...)
editorCmd.Stdout = os.Stdout
editorCmd.Stdin = os.Stdin
editorCmd.Stderr = os.Stderr
if err := editorCmd.Run(); err != nil {
fmt.Fprintf(os.Stderr, "failed to edit cheatsheet: %v\n", err)
os.Exit(1)
}

19
cmd/cheat/cmd_list.go
View File

@@ -9,6 +9,8 @@ import (
"strings"
"text/tabwriter"
"github.com/spf13/cobra"
"github.com/cheat/cheat/internal/config"
"github.com/cheat/cheat/internal/display"
"github.com/cheat/cheat/internal/sheet"
@@ -16,7 +18,7 @@ import (
)
// cmdList lists all available cheatsheets.
func cmdList(opts map[string]interface{}, conf config.Config) {
func cmdList(cmd *cobra.Command, args []string, conf config.Config) {
// load the cheatsheets
cheatsheets, err := sheets.Load(conf.Cheatpaths)
@@ -24,10 +26,11 @@ func cmdList(opts map[string]interface{}, conf config.Config) {
fmt.Fprintf(os.Stderr, "failed to list cheatsheets: %v\n", err)
os.Exit(1)
}
if opts["--tag"] != nil {
if cmd.Flags().Changed("tag") {
tagVal, _ := cmd.Flags().GetString("tag")
cheatsheets = sheets.Filter(
cheatsheets,
strings.Split(opts["--tag"].(string), ","),
strings.Split(tagVal, ","),
)
}
@@ -47,16 +50,13 @@ func cmdList(opts map[string]interface{}, conf config.Config) {
})
// filter if <cheatsheet> was specified
// NB: our docopt specification is misleading here. When used in conjunction
// with `-l`, `<cheatsheet>` is really a pattern against which to filter
// sheet titles.
if opts["<cheatsheet>"] != nil {
if len(args) > 0 {
// initialize a slice of filtered sheets
filtered := []sheet.Sheet{}
// initialize our filter pattern
pattern := "(?i)" + opts["<cheatsheet>"].(string)
pattern := "(?i)" + args[0]
// compile the regex
reg, err := regexp.Compile(pattern)
@@ -86,7 +86,8 @@ func cmdList(opts map[string]interface{}, conf config.Config) {
w := tabwriter.NewWriter(&out, 0, 0, 1, ' ', 0)
// generate sorted, columnized output
if opts["--brief"].(bool) {
briefFlag, _ := cmd.Flags().GetBool("brief")
if briefFlag {
fmt.Fprintln(w, "title:\ttags:")
for _, sheet := range flattened {
fmt.Fprintf(w, "%s\t%s\n", sheet.Title, strings.Join(sheet.Tags, ","))

11
cmd/cheat/cmd_remove.go
View File

@@ -5,15 +5,17 @@ import (
"os"
"strings"
"github.com/spf13/cobra"
"github.com/cheat/cheat/internal/config"
"github.com/cheat/cheat/internal/sheet"
"github.com/cheat/cheat/internal/sheets"
)
// cmdRemove removes (deletes) a cheatsheet.
func cmdRemove(opts map[string]interface{}, conf config.Config) {
func cmdRemove(cmd *cobra.Command, _ []string, conf config.Config) {
cheatsheet := opts["--rm"].(string)
cheatsheet, _ := cmd.Flags().GetString("rm")
// validate the cheatsheet name
if err := sheet.Validate(cheatsheet); err != nil {
@@ -27,10 +29,11 @@ func cmdRemove(opts map[string]interface{}, conf config.Config) {
fmt.Fprintf(os.Stderr, "failed to list cheatsheets: %v\n", err)
os.Exit(1)
}
if opts["--tag"] != nil {
if cmd.Flags().Changed("tag") {
tagVal, _ := cmd.Flags().GetString("tag")
cheatsheets = sheets.Filter(
cheatsheets,
strings.Split(opts["--tag"].(string), ","),
strings.Split(tagVal, ","),
)
}

21
cmd/cheat/cmd_search.go
View File

@@ -6,15 +6,19 @@ import (
"regexp"
"strings"
"github.com/spf13/cobra"
"github.com/cheat/cheat/internal/config"
"github.com/cheat/cheat/internal/display"
"github.com/cheat/cheat/internal/sheets"
)
// cmdSearch searches for strings in cheatsheets.
func cmdSearch(opts map[string]interface{}, conf config.Config) {
func cmdSearch(cmd *cobra.Command, args []string, conf config.Config) {
phrase := opts["--search"].(string)
phrase, _ := cmd.Flags().GetString("search")
colorize, _ := cmd.Flags().GetBool("colorize")
useRegex, _ := cmd.Flags().GetBool("regex")
// load the cheatsheets
cheatsheets, err := sheets.Load(conf.Cheatpaths)
@@ -22,10 +26,11 @@ func cmdSearch(opts map[string]interface{}, conf config.Config) {
fmt.Fprintf(os.Stderr, "failed to list cheatsheets: %v\n", err)
os.Exit(1)
}
if opts["--tag"] != nil {
if cmd.Flags().Changed("tag") {
tagVal, _ := cmd.Flags().GetString("tag")
cheatsheets = sheets.Filter(
cheatsheets,
strings.Split(opts["--tag"].(string), ","),
strings.Split(tagVal, ","),
)
}
@@ -33,7 +38,7 @@ func cmdSearch(opts map[string]interface{}, conf config.Config) {
pattern := "(?i)" + phrase
// unless --regex is provided, in which case we pass the regex unaltered
if opts["--regex"] == true {
if useRegex {
pattern = phrase
}
@@ -53,7 +58,7 @@ func cmdSearch(opts map[string]interface{}, conf config.Config) {
// if <cheatsheet> was provided, constrain the search only to
// matching cheatsheets
if opts["<cheatsheet>"] != nil && sheet.Title != opts["<cheatsheet>"] {
if len(args) > 0 && sheet.Title != args[0] {
continue
}
@@ -68,7 +73,7 @@ func cmdSearch(opts map[string]interface{}, conf config.Config) {
}
// if colorization was requested, apply it here
if conf.Color(opts) {
if conf.Color(colorize) {
sheet.Colorize(conf)
}
@@ -78,7 +83,7 @@ func cmdSearch(opts map[string]interface{}, conf config.Config) {
// append the cheatsheet title
sheet.Title,
// append the cheatsheet path
display.Faint(fmt.Sprintf("(%s)", sheet.CheatPath), conf.Color(opts)),
display.Faint(fmt.Sprintf("(%s)", sheet.CheatPath), conf.Color(colorize)),
// indent each line of content
display.Indent(sheet.Text),
)

4
cmd/cheat/cmd_tags.go
View File

@@ -4,13 +4,15 @@ import (
"fmt"
"os"
"github.com/spf13/cobra"
"github.com/cheat/cheat/internal/config"
"github.com/cheat/cheat/internal/display"
"github.com/cheat/cheat/internal/sheets"
)
// cmdTags lists all tags in use.
func cmdTags(_ map[string]interface{}, conf config.Config) {
func cmdTags(_ *cobra.Command, _ []string, conf config.Config) {
// load the cheatsheets
cheatsheets, err := sheets.Load(conf.Cheatpaths)

22
cmd/cheat/cmd_view.go
View File

@@ -5,15 +5,19 @@ import (
"os"
"strings"
"github.com/spf13/cobra"
"github.com/cheat/cheat/internal/config"
"github.com/cheat/cheat/internal/display"
"github.com/cheat/cheat/internal/sheets"
)
// cmdView displays a cheatsheet for viewing.
func cmdView(opts map[string]interface{}, conf config.Config) {
func cmdView(cmd *cobra.Command, args []string, conf config.Config) {
cheatsheet := opts["<cheatsheet>"].(string)
cheatsheet := args[0]
colorize, _ := cmd.Flags().GetBool("colorize")
// load the cheatsheets
cheatsheets, err := sheets.Load(conf.Cheatpaths)
@@ -21,15 +25,17 @@ func cmdView(opts map[string]interface{}, conf config.Config) {
fmt.Fprintf(os.Stderr, "failed to list cheatsheets: %v\n", err)
os.Exit(1)
}
if opts["--tag"] != nil {
if cmd.Flags().Changed("tag") {
tagVal, _ := cmd.Flags().GetString("tag")
cheatsheets = sheets.Filter(
cheatsheets,
strings.Split(opts["--tag"].(string), ","),
strings.Split(tagVal, ","),
)
}
// if --all was passed, display cheatsheets from all cheatpaths
if opts["--all"].(bool) {
allFlag, _ := cmd.Flags().GetBool("all")
if allFlag {
// iterate over the cheatpaths
out := ""
for _, cheatpath := range cheatsheets {
@@ -40,11 +46,11 @@ func cmdView(opts map[string]interface{}, conf config.Config) {
// identify the matching cheatsheet
out += fmt.Sprintf("%s %s\n",
sheet.Title,
display.Faint(fmt.Sprintf("(%s)", sheet.CheatPath), conf.Color(opts)),
display.Faint(fmt.Sprintf("(%s)", sheet.CheatPath), conf.Color(colorize)),
)
// apply colorization if requested
if conf.Color(opts) {
if conf.Color(colorize) {
sheet.Colorize(conf)
}
@@ -71,7 +77,7 @@ func cmdView(opts map[string]interface{}, conf config.Config) {
}
// apply colorization if requested
if conf.Color(opts) {
if conf.Color(colorize) {
sheet.Colorize(conf)
}

202
cmd/cheat/main.go
View File

@@ -5,25 +5,138 @@ import (
"fmt"
"os"
"runtime"
"strings"
"github.com/docopt/docopt-go"
"github.com/mitchellh/go-homedir"
"github.com/spf13/cobra"
"github.com/cheat/cheat/internal/cheatpath"
"github.com/cheat/cheat/internal/completions"
"github.com/cheat/cheat/internal/config"
"github.com/cheat/cheat/internal/installer"
)
const version = "4.7.1"
const version = "5.0.0"
var rootCmd = &cobra.Command{
Use: "cheat [cheatsheet]",
Short: "Create and view interactive cheatsheets on the command-line",
Long: `cheat allows you to create and view interactive cheatsheets on the
command-line. It was designed to help remind *nix system administrators of
options for commands that they use frequently, but not frequently enough to
remember.`,
Example: ` To initialize a config file:
mkdir -p ~/.config/cheat && cheat --init > ~/.config/cheat/conf.yml
To view the tar cheatsheet:
cheat tar
To edit (or create) the foo cheatsheet:
cheat -e foo
To edit (or create) the foo/bar cheatsheet on the "work" cheatpath:
cheat -p work -e foo/bar
To view all cheatsheet directories:
cheat -d
To list all available cheatsheets:
cheat -l
To briefly list all cheatsheets whose titles match "apt":
cheat -b apt
To list all tags in use:
cheat -T
To list available cheatsheets that are tagged as "personal":
cheat -l -t personal
To search for "ssh" among all cheatsheets, and colorize matches:
cheat -c -s ssh
To search (by regex) for cheatsheets that contain an IP address:
cheat -c -r -s '(?:[0-9]{1,3}\.){3}[0-9]{1,3}'
To remove (delete) the foo/bar cheatsheet:
cheat --rm foo/bar
To view the configuration file path:
cheat --conf
To generate shell completions (bash, zsh, fish, powershell):
cheat --completion bash`,
RunE: run,
Args: cobra.MaximumNArgs(1),
SilenceErrors: true,
SilenceUsage: true,
ValidArgsFunction: completions.Cheatsheets,
CompletionOptions: cobra.CompletionOptions{
DisableDefaultCmd: true,
},
}
func init() {
f := rootCmd.Flags()
// bool flags
f.BoolP("all", "a", false, "Search among all cheatpaths")
f.BoolP("brief", "b", false, "List cheatsheets without file paths")
f.BoolP("colorize", "c", false, "Colorize output")
f.BoolP("directories", "d", false, "List cheatsheet directories")
f.Bool("init", false, "Write a default config file to stdout")
f.BoolP("list", "l", false, "List cheatsheets")
f.BoolP("regex", "r", false, "Treat search <phrase> as a regex")
f.BoolP("tags", "T", false, "List all tags in use")
f.BoolP("version", "v", false, "Print the version number")
f.Bool("conf", false, "Display the config file path")
// string flags
f.StringP("edit", "e", "", "Edit `cheatsheet`")
f.StringP("path", "p", "", "Return only sheets found on cheatpath `name`")
f.StringP("search", "s", "", "Search cheatsheets for `phrase`")
f.StringP("tag", "t", "", "Return only sheets matching `tag`")
f.String("rm", "", "Remove (delete) `cheatsheet`")
f.String("completion", "", "Generate shell completion script (`shell`: bash, zsh, fish, powershell)")
// register flag completion functions
rootCmd.RegisterFlagCompletionFunc("tag", completions.Tags)
rootCmd.RegisterFlagCompletionFunc("path", completions.Paths)
rootCmd.RegisterFlagCompletionFunc("edit", completions.Cheatsheets)
rootCmd.RegisterFlagCompletionFunc("rm", completions.Cheatsheets)
}
func main() {
if err := rootCmd.Execute(); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}
// initialize options
opts, err := docopt.ParseArgs(usage(), nil, version)
if err != nil {
// panic here, because this should never happen
panic(fmt.Errorf("docopt failed to parse: %v", err))
func run(cmd *cobra.Command, args []string) error {
f := cmd.Flags()
// handle --init early (no config needed)
if initFlag, _ := f.GetBool("init"); initFlag {
home, err := homedir.Dir()
if err != nil {
fmt.Fprintf(os.Stderr, "failed to get user home directory: %v\n", err)
os.Exit(1)
}
envvars := config.EnvVars()
cmdInit(home, envvars)
os.Exit(0)
}
// handle --version early
if versionFlag, _ := f.GetBool("version"); versionFlag {
fmt.Println(version)
os.Exit(0)
}
// handle --completion early (no config needed)
if f.Changed("completion") {
shell, _ := f.GetString("completion")
return completions.Generate(cmd, shell, os.Stdout)
}
// get the user's home directory
@@ -34,24 +147,9 @@ func main() {
}
// read the envvars into a map of strings
envvars := map[string]string{}
for _, e := range os.Environ() {
// os.Environ() guarantees "key=value" format (see ADR-002)
pair := strings.SplitN(e, "=", 2)
if runtime.GOOS == "windows" {
pair[0] = strings.ToUpper(pair[0])
}
envvars[pair[0]] = pair[1]
}
envvars := config.EnvVars()
// if --init was passed, we don't want to attempt to load a config file.
// Instead, just execute cmd_init and exit
if opts["--init"] == true {
cmdInit(home, envvars)
os.Exit(0)
}
// identify the os-specifc paths at which configs may be located
// identify the os-specific paths at which configs may be located
confpaths, err := config.Paths(runtime.GOOS, home, envvars)
if err != nil {
fmt.Fprintf(os.Stderr, "failed to load config: %v\n", err)
@@ -105,10 +203,11 @@ func main() {
}
// filter the cheatpaths if --path was passed
if opts["--path"] != nil {
if f.Changed("path") {
pathVal, _ := f.GetString("path")
conf.Cheatpaths, err = cheatpath.Filter(
conf.Cheatpaths,
opts["--path"].(string),
pathVal,
)
if err != nil {
fmt.Fprintf(os.Stderr, "invalid option --path: %v\n", err)
@@ -117,41 +216,44 @@ func main() {
}
// determine which command to execute
var cmd func(map[string]interface{}, config.Config)
confFlag, _ := f.GetBool("conf")
dirFlag, _ := f.GetBool("directories")
listFlag, _ := f.GetBool("list")
briefFlag, _ := f.GetBool("brief")
tagsFlag, _ := f.GetBool("tags")
tagVal, _ := f.GetString("tag")
switch {
case opts["--conf"].(bool):
cmd = cmdConf
case confFlag:
cmdConf(cmd, args, conf)
case opts["--directories"].(bool):
cmd = cmdDirectories
case dirFlag:
cmdDirectories(cmd, args, conf)
case opts["--edit"] != nil:
cmd = cmdEdit
case f.Changed("edit"):
cmdEdit(cmd, args, conf)
case opts["--list"].(bool), opts["--brief"].(bool):
cmd = cmdList
case listFlag, briefFlag:
cmdList(cmd, args, conf)
case opts["--tags"].(bool):
cmd = cmdTags
case tagsFlag:
cmdTags(cmd, args, conf)
case opts["--search"] != nil:
cmd = cmdSearch
case f.Changed("search"):
cmdSearch(cmd, args, conf)
case opts["--rm"] != nil:
cmd = cmdRemove
case f.Changed("rm"):
cmdRemove(cmd, args, conf)
case opts["<cheatsheet>"] != nil:
cmd = cmdView
case len(args) > 0:
cmdView(cmd, args, conf)
case opts["--tag"] != nil && opts["--tag"].(string) != "":
cmd = cmdList
case tagVal != "":
cmdList(cmd, args, conf)
default:
fmt.Println(usage())
os.Exit(0)
return cmd.Help()
}
// execute the command
cmd(opts, conf)
return nil
}

65
cmd/cheat/usage.go
View File

@@ -1,65 +0,0 @@
package main
// usage returns the usage text for the cheat command
func usage() string {
return `Usage:
cheat [options] [<cheatsheet>]
Options:
--init Write a default config file to stdout
-a --all Search among all cheatpaths
-b --brief List cheatsheets without file paths
-c --colorize Colorize output
-d --directories List cheatsheet directories
-e --edit=<cheatsheet> Edit <cheatsheet>
-l --list List cheatsheets
-p --path=<name> Return only sheets found on cheatpath <name>
-r --regex Treat search <phrase> as a regex
-s --search=<phrase> Search cheatsheets for <phrase>
-t --tag=<tag> Return only sheets matching <tag>
-T --tags List all tags in use
-v --version Print the version number
--rm=<cheatsheet> Remove (delete) <cheatsheet>
--conf Display the config file path
Examples:
To initialize a config file:
mkdir -p ~/.config/cheat && cheat --init > ~/.config/cheat/conf.yml
To view the tar cheatsheet:
cheat tar
To edit (or create) the foo cheatsheet:
cheat -e foo
To edit (or create) the foo/bar cheatsheet on the "work" cheatpath:
cheat -p work -e foo/bar
To view all cheatsheet directories:
cheat -d
To list all available cheatsheets:
cheat -l
To briefly list all cheatsheets whose titles match "apt":
cheat -b apt
To list all tags in use:
cheat -T
To list available cheatsheets that are tagged as "personal":
cheat -l -t personal
To search for "ssh" among all cheatsheets, and colorize matches:
cheat -c -s ssh
To search (by regex) for cheatsheets that contain an IP address:
cheat -c -r -s '(?:[0-9]{1,3}\.){3}[0-9]{1,3}'
To remove (delete) the foo/bar cheatsheet:
cheat --rm foo/bar
To view the configuration file path:
cheat --conf`
}