Merge remote-tracking branch 'origin/main' into mostynb-report_source…

…_of_parse_errors

.github/workflows/cli.yml

@@ -37,7 +37,7 @@ jobs:
       - name: vet
         run: go run internal/build/build.go vet
 
-      - name: test with tags
+      - name: test with urfave_cli_no_docs tag
         run: go run internal/build/build.go -tags urfave_cli_no_docs test
 
       - name: test
@@ -47,7 +47,7 @@ jobs:
         run: go run internal/build/build.go check-binary-size
 
       - name: check-binary-size with tags (informational only)
-        run: go run internal/build/build.go -tags urfave_cli_no_docs check-binary-size || true
+        run: go run internal/build/build.go -tags urfave_cli_no_docs check-binary-size
 
       - name: Upload coverage to Codecov
         if: success() && matrix.go == '1.18.x' && matrix.os == 'ubuntu-latest'
@@ -76,19 +76,37 @@ jobs:
         uses: actions/checkout@v3
 
       - name: Install Dependencies
-        run:
-          mkdir -p "${GITHUB_WORKSPACE}/.local/bin" &&
-          curl -fsSL -o "${GITHUB_WORKSPACE}/.local/bin/gfmrun" "https://github.com/urfave/gfmrun/releases/download/v1.3.0/gfmrun-$(go env GOOS)-$(go env GOARCH)-v1.3.0" &&
-          chmod +x "${GITHUB_WORKSPACE}/.local/bin/gfmrun" &&
-          npm install -g markdown-toc@1.2.0
+        run: |
+          mkdir -p "${GITHUB_WORKSPACE}/.local/bin"
+          curl -fsSL -o "${GITHUB_WORKSPACE}/.local/bin/gfmrun" "https://github.com/urfave/gfmrun/releases/download/v1.3.0/gfmrun-$(go env GOOS)-$(go env GOARCH)-v1.3.0"
+          chmod +x "${GITHUB_WORKSPACE}/.local/bin/gfmrun"
 
       - name: gfmrun
         run: go run internal/build/build.go gfmrun docs/v2/manual.md
 
-      - name: toc
-        run: go run internal/build/build.go toc docs/v2/manual.md
-
       - name: diff check
         run: |
           git diff --exit-code
           git diff --cached --exit-code
+
+  publish:
+    if: startswith(github.ref, 'refs/tags/')
+    name: publish
+    needs: [test-docs]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Setup mkdocs
+        run: |
+          pip install -U pip
+          pip install -r mkdocs-requirements.txt
+          git remote rm origin
+          git remote add origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/urfave/cli.git
+
+      - name: Publish Docs
+        run: |
+          mkdocs gh-deploy --force

.gitignore

@@ -1,10 +1,10 @@
 *.coverprofile
 *.orig
-node_modules/
 vendor
 .idea
 internal/*/built-example
 coverage.txt
 /.local/
+/site/
 
 *.exe

Makefile

@@ -5,7 +5,7 @@
 # attention on files that are primarily Go.
 
 .PHONY: all
-all: generate vet tag-test test check-binary-size tag-check-binary-size gfmrun toc v2diff
+all: generate vet tag-test test check-binary-size tag-check-binary-size gfmrun v2diff
 
 # NOTE: this is a special catch-all rule to run any of the commands
 # defined in internal/build/build.go with optional arguments passed
@@ -27,6 +27,14 @@ tag-check-binary-size:
 gfmrun:
 	go run internal/build/build.go gfmrun docs/v2/manual.md
 
-.PHONY: toc
-toc:
-	go run internal/build/build.go toc docs/v2/manual.md
+.PHONY: docs
+docs:
+	mkdocs build
+
+.PHONY: docs-deps
+docs-deps:
+	pip install -r mkdocs-requirements.txt
+
+.PHONY: serve-docs
+serve-docs:
+	mkdocs serve

README.md

@@ -63,7 +63,7 @@ You can use the following build tags:
 
 When set, this removes `ToMarkdown` and `ToMan` methods, so your application
 won't be able to call those. This reduces the resulting binary size by about
-300-400 KB (measured using Go 1.18.1 on Linux/amd64), due to less dependencies.
+300-400 KB (measured using Go 1.18.1 on Linux/amd64), due to fewer dependencies.
 
 ### GOPATH
 

app.go

@@ -94,6 +94,8 @@ type App struct {
 	// single-character bool arguments into one
 	// i.e. foobar -o -v -> foobar -ov
 	UseShortOptionHandling bool
+	// Enable suggestions for commands and flags
+	Suggest bool
 
 	didSetup bool
 }
@@ -264,6 +266,11 @@ func (a *App) RunContext(ctx context.Context, arguments []string) (err error) {
 			return err
 		}
 		_, _ = fmt.Fprintf(a.Writer, "%s %s\n\n", "Incorrect Usage.", err.Error())
+		if a.Suggest {
+			if suggestion, err := a.suggestFlagFromError(err, ""); err == nil {
+				fmt.Fprintf(a.Writer, suggestion)
+			}
+		}
 		_ = ShowAppHelp(cCtx)
 		return err
 	}
@@ -383,6 +390,11 @@ func (a *App) RunAsSubcommand(ctx *Context) (err error) {
 			return err
 		}
 		_, _ = fmt.Fprintf(a.Writer, "%s %s\n\n", "Incorrect Usage.", err.Error())
+		if a.Suggest {
+			if suggestion, err := a.suggestFlagFromError(err, cCtx.Command.Name); err == nil {
+				fmt.Fprintf(a.Writer, suggestion)
+			}
+		}
 		_ = ShowSubcommandHelp(cCtx)
 		return err
 	}

app_test.go

@@ -228,6 +228,7 @@ func ExampleApp_Run_subcommandNoAction() {
 }
 
 func ExampleApp_Run_bashComplete_withShortFlag() {
+	os.Setenv("SHELL", "bash")
 	os.Args = []string{"greet", "-", "--generate-bash-completion"}
 
 	app := NewApp()
@@ -255,6 +256,7 @@ func ExampleApp_Run_bashComplete_withShortFlag() {
 }
 
 func ExampleApp_Run_bashComplete_withLongFlag() {
+	os.Setenv("SHELL", "bash")
 	os.Args = []string{"greet", "--s", "--generate-bash-completion"}
 
 	app := NewApp()
@@ -283,6 +285,7 @@ func ExampleApp_Run_bashComplete_withLongFlag() {
 	// --similar-flag
 }
 func ExampleApp_Run_bashComplete_withMultipleLongFlag() {
+	os.Setenv("SHELL", "bash")
 	os.Args = []string{"greet", "--st", "--generate-bash-completion"}
 
 	app := NewApp()
@@ -315,7 +318,7 @@ func ExampleApp_Run_bashComplete_withMultipleLongFlag() {
 }
 
 func ExampleApp_Run_bashComplete() {
-	// set args for examples sake
+	os.Setenv("SHELL", "bash")
 	os.Args = []string{"greet", "--generate-bash-completion"}
 
 	app := &App{
@@ -355,7 +358,7 @@ func ExampleApp_Run_bashComplete() {
 func ExampleApp_Run_zshComplete() {
 	// set args for examples sake
 	os.Args = []string{"greet", "--generate-bash-completion"}
-	_ = os.Setenv("_CLI_ZSH_AUTOCOMPLETE_HACK", "1")
+	_ = os.Setenv("SHELL", "/usr/bin/zsh")
 
 	app := NewApp()
 	app.Name = "greet"

autocomplete/zsh_autocomplete

@@ -1,23 +1,20 @@
 #compdef $PROG
 
 _cli_zsh_autocomplete() {
-
   local -a opts
   local cur
   cur=${words[-1]}
   if [[ "$cur" == "-"* ]]; then
-    opts=("${(@f)$(_CLI_ZSH_AUTOCOMPLETE_HACK=1 ${words[@]:0:#words[@]-1} ${cur} --generate-bash-completion)}")
+    opts=("${(@f)$(${words[@]:0:#words[@]-1} ${cur} --generate-bash-completion)}")
   else
-    opts=("${(@f)$(_CLI_ZSH_AUTOCOMPLETE_HACK=1 ${words[@]:0:#words[@]-1} --generate-bash-completion)}")
+    opts=("${(@f)$(${words[@]:0:#words[@]-1} --generate-bash-completion)}")
   fi
 
   if [[ "${opts[1]}" != "" ]]; then
     _describe 'values' opts
   else
     _files
   fi
-
-  return
 }
 
 compdef _cli_zsh_autocomplete $PROG

command.go

@@ -119,6 +119,11 @@ func (c *Command) Run(ctx *Context) (err error) {
 		}
 		_, _ = fmt.Fprintln(cCtx.App.Writer, "Incorrect Usage:", err.Error())
 		_, _ = fmt.Fprintln(cCtx.App.Writer)
+		if ctx.App.Suggest {
+			if suggestion, err := ctx.App.suggestFlagFromError(err, c.Name); err == nil {
+				fmt.Fprintf(cCtx.App.Writer, suggestion)
+			}
+		}
 		_ = ShowCommandHelp(cCtx, c.Name)
 		return err
 	}
@@ -249,6 +254,7 @@ func (c *Command) startApp(ctx *Context) error {
 	app.ErrWriter = ctx.App.ErrWriter
 	app.ExitErrHandler = ctx.App.ExitErrHandler
 	app.UseShortOptionHandling = ctx.App.UseShortOptionHandling
+	app.Suggest = ctx.App.Suggest
 
 	app.categories = newCommandCategories()
 	for _, command := range c.Subcommands {

docs/CNAME

@@ -0,0 +1 @@
+cli.urfave.org

docs/CODE_OF_CONDUCT.md

@@ -0,0 +1 @@
+../CODE_OF_CONDUCT.md

docs/CONTRIBUTING.md

@@ -98,6 +98,28 @@ line help system which may be consulted for further information, e.g.:
 go run internal/genflags/cmd/genflags/main.go --help
 ```
 
+#### docs output
+
+The documentation in the `docs` directory is automatically built via `mkdocs` into a
+static site and published when releases are pushed (see [RELEASING](./RELEASING/)). There
+is no strict requirement to build the documentation when developing locally, but the
+following `make` targets may be used if desired:
+
+```sh
+# install documentation dependencies with `pip`
+make docs-deps
+```
+
+```sh
+# build the static site in `./site`
+make docs
+```
+
+```sh
+# start an mkdocs development server
+make serve-docs
+```
+
 ### pull requests
 
 Please feel free to open a pull request to fix a bug or add a feature. The @urfave/cli

docs/index.md

@@ -0,0 +1,21 @@
+# Welcome to urfave/cli
+
+[![GoDoc](https://godoc.org/github.com/urfave/cli?status.svg)](https://pkg.go.dev/github.com/urfave/cli/v2)
+[![codebeat](https://codebeat.co/badges/0a8f30aa-f975-404b-b878-5fab3ae1cc5f)](https://codebeat.co/projects/github-com-urfave-cli)
+[![Go Report Card](https://goreportcard.com/badge/urfave/cli)](https://goreportcard.com/report/urfave/cli)
+[![codecov](https://codecov.io/gh/urfave/cli/branch/main/graph/badge.svg)](https://codecov.io/gh/urfave/cli)
+
+`urfave/cli` is a simple, fast, and fun package for building command line apps in Go. The
+goal is to enable developers to write fast and distributable command line applications in
+an expressive way.
+
+These are the guides for each major supported version:
+
+- [`v2`](./v2/)
+- [`v1`](./v1/)
+
+In addition to the version-specific guides, these other documents are available:
+
+- [CONTRIBUTING](./CONTRIBUTING/)
+- [CODE OF CONDUCT](./CODE_OF_CONDUCT/)
+- [RELEASING](./RELEASING/)

docs/migrate-v1-to-v2.md

@@ -1,6 +1,4 @@
-Migration Guide: v1 to v2
-===
-
+# Migration Guide: v1 to v2
 
 v2 has a number of breaking changes but converting is relatively
 straightforward: make the changes documented below then resolve any
@@ -11,25 +9,6 @@ If you find any issues not covered by this document, please post a
 comment on [Issue 921](https://github.com/urfave/cli/issues/921) or
 consider sending a PR to help improve this guide.
 
-<!-- toc -->
-
-  * [Flags before args](#flags-before-args)
-  * [Import string changed](#import-string-changed)
-  * [Flag aliases are done differently](#flag-aliases-are-done-differently)
-  * [EnvVar is now a list (EnvVars)](#envvar-is-now-a-list-envvars)
-  * [Actions returns errors](#actions-returns-errors)
-  * [cli.Flag changed](#cliflag-changed)
-  * [Commands are now lists of pointers](#commands-are-now-lists-of-pointers)
-  * [Lists of commands should be pointers](#lists-of-commands-should-be-pointers)
-  * [Appending Commands](#appending-commands)
-  * [GlobalString, GlobalBool and its likes are deprecated](#globalstring-globalbool-and-its-likes-are-deprecated)
-  * [BoolTFlag and BoolT are deprecated](#booltflag-and-boolt-are-deprecated)
-  * [&cli.StringSlice{""} replaced with cli.NewStringSlice("")](#clistringslice-replaced-with-clinewstringslice)
-  * [Replace deprecated functions](#replace-deprecated-functions)
-  * [Everything else](#everything-else)
-
-<!-- tocstop -->
-
 # Flags before args
 
 In v2 flags must come before args. This is more POSIX-compliant.  You

docs/v1/index.md

@@ -0,0 +1 @@
+manual.md

docs/v1/manual.md

@@ -1,35 +1,4 @@
-cli v1 manual
-===
-
-<!-- toc -->
-
-- [Getting Started](#getting-started)
-- [Examples](#examples)
-  * [Arguments](#arguments)
-  * [Flags](#flags)
-    + [Placeholder Values](#placeholder-values)
-    + [Alternate Names](#alternate-names)
-    + [Ordering](#ordering)
-    + [Values from the Environment](#values-from-the-environment)
-    + [Values from files](#values-from-files)
-    + [Values from alternate input sources (YAML, TOML, and others)](#values-from-alternate-input-sources-yaml-toml-and-others)
-    + [Precedence](#precedence)
-  * [Subcommands](#subcommands)
-  * [Subcommands categories](#subcommands-categories)
-  * [Exit code](#exit-code)
-  * [Combining short options](#combining-short-options)
-  * [Bash Completion](#bash-completion)
-    + [Enabling](#enabling)
-    + [Distribution](#distribution)
-    + [Customization](#customization)
-  * [Generated Help Text](#generated-help-text)
-    + [Customization](#customization-1)
-  * [Version Flag](#version-flag)
-    + [Customization](#customization-2)
-    + [Full API Example](#full-api-example)
-  * [Migrating to V2](#migrating-to-v2)
-
-<!-- tocstop -->
+# v1 guide
 
 ## Getting Started
 

docs/v2/index.md

@@ -0,0 +1 @@
+manual.md