Merge branch 'master' into suggestions

2022-04-19 16:45:20 -04:00
parent 002bde2233 7b2e60968b
commit 4b238b8ff0
62 changed files with 2097 additions and 439 deletions
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -6,6 +6,29 @@

 View [unreleased 2.X] series changes.

+## [2.2.0] - 2020-03-08
+
+These release notes were written for the git hash [d648edd48d89ef3a841b1ec75c2ebbd4de5f748f](https://github.com/urfave/cli/tree/d648edd48d89ef3a841b1ec75c2ebbd4de5f748f)
+
+### Fixed
+
+* Fixed zsh completion scripts in [urfave/cli/pull/1062](https://github.com/urfave/cli/pull/1062) via [@zhsj](https://github.com/zhsj)
+* Fixed description of subcommand to be more consistent in [urfave/cli/pull/1054](https://github.com/urfave/cli/pull/1054) via [@itchyny](https://github.com/itchyny)
+* Fixed possible runtime panic in slice parsing in [urfave/cli/pull/1049](https://github.com/urfave/cli/pull/1049) via [@saschagrunert](https://github.com/saschagrunert)
+* Fixed invalid man page header generation in [urfave/cli/pull/1041](https://github.com/urfave/cli/pull/1041) via [@saschagrunert](https://github.com/saschagrunert)
+
+### Changed
+
+* Improved auto-completion instructions and added example gifs in [urfave/cli/pull/1059](https://github.com/urfave/cli/pull/1059) via [@masonj188](https://github.com/masonj188)
+* Removed the author from generated man pages in [urfave/cli/pull/1041](https://github.com/urfave/cli/pull/1041) via [@saschagrunert](https://github.com/saschagrunert)
+
+### Added
+
+* Added destination field to `StringSliceFlag` in [urfave/cli/pull/1078](https://github.com/urfave/cli/pull/1078) via [@davidsbond](https://github.com/davidsbond)
+* Added `HideHelpCommand`. While `HideHelp` hides both `help` command and `--help` flag, `HideHelpCommand` only hides `help` command and leave `--help` flag as-is in [urfave/cli/pull/1083](https://github.com/urfave/cli/pull/1083) via [@AkihiroSuda](https://github.com/AkihiroSuda)
+* Added timestampFlag docs in [urfave/cli/pull/997](https://github.com/urfave/cli/pull/997) via [@drov0](https://github.com/drov0)
+* Added required flags documentation in [urfave/cli/pull/1008](https://github.com/urfave/cli/pull/1008) via [@lynncyrin](https://github.com/lynncyrin), [@anberns](https://github.com/anberns)
+
 ## [2.1.1] - 2019-12-24

 ### Fixed
@@ -67,6 +90,12 @@ The V2 changes were all shipped in [urfave/cli/pull/892](https://github.com/urfa

 View [unreleased 1.22.X] series changes.

+## [1.22.4] - 2020-03-31
+
+### Fixed
+
+- Fixed a panic with flag completion in [urfave/cli/pull/1101](https://github.com/urfave/cli/pull/1101) via [@unRob](https://github.com/unRob), [@VirrageS](https://github.com/VirrageS)
+
 ## [1.22.3] - 2020-02-25

 ### Fixed
@@ -555,12 +584,14 @@ signature of `func(*cli.Context) error`, as defined by `cli.ActionFunc`.
 ### Added
 - Initial implementation.

-[unreleased 2.X]: https://github.com/urfave/cli/compare/v2.1.1...HEAD
+[unreleased 2.X]: https://github.com/urfave/cli/compare/v2.2.0...HEAD
+[2.2.0]: https://github.com/urfave/cli/compare/v2.1.1...v2.2.0
 [2.1.1]: https://github.com/urfave/cli/compare/v2.1.0...v2.1.1
 [2.1.0]: https://github.com/urfave/cli/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/urfave/cli/compare/v1.22.2...v2.0.0

-[unreleased 1.22.X]: https://github.com/urfave/cli/compare/v1.22.3...v1
+[unreleased 1.22.X]: https://github.com/urfave/cli/compare/v1.22.4...v1
+[1.22.4]: https://github.com/urfave/cli/compare/v1.22.3...v1.22.4
 [1.22.3]: https://github.com/urfave/cli/compare/v1.22.2...v1.22.3
 [1.22.2]: https://github.com/urfave/cli/compare/v1.22.1...v1.22.2
 [1.22.1]: https://github.com/urfave/cli/compare/v1.22.0...v1.22.1
--- a/docs/migrate-v1-to-v2.md
+++ b/docs/migrate-v1-to-v2.md
@@ -0,0 +1,245 @@
+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
+compiler errors. We hope this will be sufficient for most typical
+users.
+
+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
+may need to update scripts, user documentation, etc.
+
+This will work:
+
+```
+cli hello --shout rick
+```
+
+This will not:
+
+```
+cli hello rick --shout
+```
+
+# Import string changed
+
+* OLD: `import "github.com/urfave/cli"`
+* NEW: `import "github.com/urfave/cli/v2"`
+
+Check each file for this and make the change.
+
+Shell command to find them all: `fgrep -rl github.com/urfave/cli *`
+
+# Flag aliases are done differently
+
+Change `Name: "foo, f"` to `Name: "foo", Aliases: []string{"f"}`
+
+* OLD:
+```go
+cli.StringFlag{
+        Name: "config, cfg"
+}
+```
+
+* NEW:
+```go
+cli.StringFlag{
+        Name: "config",
+        Aliases: []string{"cfg"},
+}
+```
+
+Sadly v2 doesn't warn you if a comma is in the name.
+(https://github.com/urfave/cli/issues/1103)
+
+# EnvVar is now a list (EnvVars)
+
+Change `EnvVar: "XXXXX"` to `EnvVars: []string{"XXXXX"}` (plural).
+
+* OLD:
+```go
+cli.StringFlag{
+        EnvVar: "APP_LANG"
+}
+```
+
+* NEW:
+```go
+cli.StringFlag{
+        EnvVars: []string{"APP_LANG"}
+}
+```
+
+# Actions returns errors
+
+A command's `Action:` now returns an `error`.
+
+* OLD: `Action: func(c *cli.Context) {`
+* NEW: `Action: func(c *cli.Context) error {`
+
+Compiler messages you might see:
+
+```
+cannot use func literal (type func(*cli.Context)) as type cli.ActionFunc in field value
+```
+
+# cli.Flag changed
+
+`cli.Flag` is now a list of pointers.
+
+What this means to you:
+
+If you make a list of flags, add a `&` in front of each
+item.   cli.BoolFlag, cli.StringFlag, etc.
+
+* OLD:
+```go
+        app.Flags = []cli.Flag{
+               cli.BoolFlag{
+```
+
+* NEW:
+```go
+        app.Flags = []cli.Flag{
+               &cli.BoolFlag{
+```
+
+Compiler messages you might see:
+
+```
+	cli.StringFlag does not implement cli.Flag (Apply method has pointer receiver)
+```
+
+# Commands are now lists of pointers
+
+Occurrences of `[]Command` have been changed to `[]*Command`.
+
+What this means to you:
+
+Look for `[]cli.Command{}` and change it to `[]*cli.Command{}`
+
+Example:
+
+* OLD: `var commands = []cli.Command{}`
+* NEW: `var commands = []*cli.Command{}`
+
+Compiler messages you might see:
+
+```
+cannot convert commands (type []cli.Command) to type cli.CommandsByName
+cannot use commands (type []cli.Command) as type []*cli.Command in assignment
+```
+
+# Lists of commands should be pointers
+
+If you are building up a list of commands, the individual items should
+now be pointers.
+
+* OLD: `cli.Command{`
+* NEW: `&cli.Command{`
+
+Compiler messages you might see:
+
+```
+cannot use cli.Command literal (type cli.Command) as type *cli.Command in argument to
+```
+
+# Appending Commands
+
+Appending to a list of commands needs to be changed since the list is
+now pointers.
+
+* OLD: `commands = append(commands, *c)`
+* NEW: `commands = append(commands, c)`
+
+Compiler messages you might see:
+
+```
+cannot use c (type *cli.Command) as type cli.Command in append
+```
+
+# GlobalString, GlobalBool and its likes are deprecated
+
+Use simply `String` instead of `GlobalString`, `Bool` instead of `GlobalBool` 
+
+# BoolTFlag and BoolT are deprecated
+
+BoolTFlag was a Bool Flag with its default value set to true and BoolT was used to find any BoolTFlag used locally, so both are deprecated.
+
+* OLD: 
+
+```go
+cli.BoolTFlag{
+		Name:   FlagName,
+		Usage:  FlagUsage,
+		EnvVar: "FLAG_ENV_VAR",
+}
+```
+* NEW: 
+```go
+cli.BoolFlag{
+		Name:   FlagName,
+		Value:  true,
+		Usage:  FlagUsage,
+		EnvVar: "FLAG_ENV_VAR",
+}
+```
+
+
+# &cli.StringSlice{""} replaced with cli.NewStringSlice("")
+
+Example: 
+
+* OLD: 
+
+```go
+Value: &cli.StringSlice{""},
+```
+* NEW: 
+```go
+Value: cli.NewStringSlice(""),
+}
+```
+# Replace deprecated functions
+
+`cli.NewExitError()` is deprecated.  Use `cli.Exit()` instead.  ([Staticcheck](https://staticcheck.io/) detects this automatically and recommends replacement code.)
+
+# Everything else
+
+Compile the code and work through any errors. Most should
+relate to issues listed above.
+
+Once it compiles, test the command. Review the output of `-h` or any
+help messages to verify they match the intended flags and subcommands.
+Then test the program itself.
+
+If you find any issues not covered by this document please let us know
+by submitting a comment on
+[Issue 921](https://github.com/urfave/cli/issues/921)
+so that others can benefit.
--- a/docs/v1/manual.md
+++ b/docs/v1/manual.md
@@ -27,6 +27,7 @@ cli v1 manual
  * [Version Flag](#version-flag)
    + [Customization](#customization-2)
    + [Full API Example](#full-api-example)
+  * [Migrating to V2](#migrating-to-v2)

 <!-- tocstop -->

@@ -611,7 +612,7 @@ given sources.
 Here is a more complete sample of a command using YAML support:

 <!-- {
-  "args": ["test-cmd", "&#45;&#45;help"],
+  "args": ["&#45;&#45;help"],
  "output": "&#45&#45;test value.*default: 0"
 } -->
 ``` go
@@ -1476,3 +1477,10 @@ func wopAction(c *cli.Context) error {
  return nil
 }
 ```
+
+## Migrating to V2
+
+There are a small set of breaking changes between v1 and v2.
+Converting is relatively straightforward and typically takes less than
+an hour. Specific steps are included in
+[Migration Guide: v1 to v2](../migrate-v1-to-v2.md).
--- a/docs/v2/manual.md
+++ b/docs/v2/manual.md
@@ -3,6 +3,7 @@ cli v2 manual

 <!-- toc -->

+- [Migrating From Older Releases](#migrating-from-older-releases)
 - [Getting Started](#getting-started)
 - [Examples](#examples)
  * [Arguments](#arguments)
@@ -29,6 +30,7 @@ cli v2 manual
    + [ZSH Support](#zsh-support)
    + [ZSH default auto-complete example](#zsh-default-auto-complete-example)
    + [ZSH custom auto-complete example](#zsh-custom-auto-complete-example)
+    + [PowerShell Support](#powershell-support)
  * [Generated Help Text](#generated-help-text)
    + [Customization](#customization-1)
  * [Version Flag](#version-flag)
@@ -39,6 +41,13 @@ cli v2 manual

 <!-- tocstop -->

+## Migrating From Older Releases
+
+There are a small set of breaking changes between v1 and v2.
+Converting is relatively straightforward and typically takes less than
+an hour. Specific steps are included in
+[Migration Guide: v1 to v2](../migrate-v1-to-v2.md). Also see the [pkg.go.dev docs](https://pkg.go.dev/github.com/urfave/cli/v2) for v2 API documentation.
+
 ## Getting Started

 One of the philosophies behind cli is that an API should be playful and full of
@@ -300,7 +309,7 @@ func main() {
 }
 ```

-See full list of flags at http://godoc.org/github.com/urfave/cli
+See full list of flags at https://pkg.go.dev/github.com/urfave/cli/v2

 #### Placeholder Values

@@ -418,15 +427,17 @@ import (
 func main() {
  app := &cli.App{
    Flags: []cli.Flag{
-      &cli.StringFlag{
-        Name:  "lang, l",
-        Value: "english",
-        Usage: "Language for the greeting",
-      },
-      &cli.StringFlag{
-        Name:  "config, c",
-        Usage: "Load configuration from `FILE`",
-      },
+        &cli.StringFlag{
+            Name:    "lang",
+            Aliases: []string{"l"},
+            Value:   "english",
+            Usage:   "Language for the greeting",
+        },
+        &cli.StringFlag{
+            Name:    "config",
+            Aliases: []string{"c"},
+            Usage:   "Load configuration from `FILE`",
+        },
    },
    Commands: []*cli.Command{
      {
@@ -504,7 +515,7 @@ func main() {
 ```

 If `EnvVars` contains more than one string, the first environment variable that
-resolves is used as the default.
+resolves is used.

 <!-- {
  "args": ["&#45;&#45;help"],
@@ -563,7 +574,8 @@ func main() {

  app.Flags = []cli.Flag {
    &cli.StringFlag{
-      Name: "password, p",
+      Name: "password",
+      Aliases: []string{"p"},
      Usage: "password for the mysql database",
      FilePath: "/etc/mysql/password",
    },
@@ -616,7 +628,7 @@ given sources.
 Here is a more complete sample of a command using YAML support:

 <!-- {
-  "args": ["test-cmd", "&#45;&#45;help"],
+  "args": ["&#45;&#45;help"],
  "output": "&#45&#45;test value.*default: 0"
 } -->
 ``` go
@@ -638,7 +650,7 @@ func main() {

  app := &cli.App{
    Action: func(c *cli.Context) error {
-      fmt.Println("yaml ist rad")
+      fmt.Println("--test value.*default: 0")
      return nil
    },
    Before: altsrc.InitInputSourceWithContext(flags, altsrc.NewYamlSourceFromFlagFunc("load")),
@@ -654,7 +666,7 @@ func main() {
 You can make a flag required by setting the `Required` field to `true`. If a user
 does not provide a required flag, they will be shown an error message.

-Take for example this app that reqiures the `lang` flag:
+Take for example this app that requires the `lang` flag:

 <!-- {
  "error": "Required flag \"lang\" not set"
@@ -665,9 +677,7 @@ package main
 import (
  "log"
  "os"
-  "strings"
-
-  "github.com/urfave/cli"
+  "github.com/urfave/cli/v2"
 )

 func main() {
@@ -1013,12 +1023,12 @@ import (
 	"fmt"
 	"log"
 	"os"
-	"github.com/urfave/cli"
+	"github.com/urfave/cli/v2"
 )
 func main() {
 	app := cli.NewApp()
 	app.EnableBashCompletion = true
-	app.Commands = []cli.Command{
+	app.Commands = []*cli.Command{
 		{
 			Name:    "add",
 			Aliases: []string{"a"},
@@ -1041,7 +1051,7 @@ func main() {
 			Name:    "template",
 			Aliases: []string{"t"},
 			Usage:   "options for task templates",
-			Subcommands: []cli.Command{
+			Subcommands: []*cli.Command{
 				{
 					Name:  "add",
 					Usage: "add a new template",
@@ -1217,6 +1227,23 @@ source  path/to/autocomplete/zsh_autocomplete
 #### ZSH custom auto-complete example
 ![](/docs/v2/images/custom-zsh-autocomplete.gif)

+#### PowerShell Support
+Auto-completion for PowerShell is also supported using the `autocomplete/powershell_autocomplete.ps1` 
+file included in this repo. 
+
+Rename the script to `<my program>.ps1` and move it anywhere in your file system.
+The location of script does not matter, only the file name of the script has to match
+the your program's binary name. 
+
+To activate it, enter `& path/to/autocomplete/<my program>.ps1`
+
+To persist across new shells, open the PowerShell profile (with `code $profile` or `notepad $profile`)
+and add the line:
+```
+& path/to/autocomplete/<my program>.ps1
+```
+
+
 ### Generated Help Text

 The default help flag (`-h/--help`) is defined as `cli.HelpFlag` and is checked
@@ -1304,7 +1331,8 @@ import (

 func main() {
  cli.HelpFlag = &cli.BoolFlag{
-    Name: "haaaaalp", Aliases: []string{"halp"},
+    Name: "haaaaalp",
+    Aliases: []string{"halp"},
    Usage: "HALP",
    EnvVars: []string{"SHOW_HALP", "HALPPLZ"},
  }
@@ -1339,7 +1367,8 @@ import (

 func main() {
  cli.VersionFlag = &cli.BoolFlag{
-    Name: "print-version", Aliases: []string{"V"},
+    Name: "print-version",
+    Aliases: []string{"V"},
    Usage: "print only the version",
  }