Make sure you have a working Go environment. Go version 1.11+ is supported. [See the install instructions for Go](http://golang.org/doc/install.html).
Using this package requires a working Go environment. [See the install instructions for Go](http://golang.org/doc/install.html).
Go Modules are strongly recommended when using this package. [See the go blog guide on using Go Modules](https://blog.golang.org/using-go-modules).
Go Modules are required when using this package. [See the go blog guide on using Go Modules](https://blog.golang.org/using-go-modules).
### Using `v2` releases
@ -63,4 +67,4 @@ export PATH=$PATH:$GOPATH/bin
cli is tested against multiple versions of Go on Linux, and against the latest
released version of Go on OS X and Windows. This project uses Github Actions for
builds. For more build info, please look at the [./.github/workflows/cli.yml](https://github.com/urfave/cli/blob/master/.github/workflows/cli.yml).
builds. To see our currently supported go versions and platforms, look at the [./.github/workflows/cli.yml](https://github.com/urfave/cli/blob/master/.github/workflows/cli.yml).
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`.
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
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": ["--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:
{"foobar",newSetFloat64Slice(),&Float64SliceFlag{Name:"seconds",EnvVars:[]string{"SECONDS"}},`could not parse "\[\]float64{}" as float64 slice value for flag seconds: .*`},
{"1.2,2",newSetIntSlice(),&IntSliceFlag{Name:"seconds",EnvVars:[]string{"SECONDS"}},`could not parse "1.2,2" as int slice value for flag seconds: .*`},
{"foobar",newSetIntSlice(),&IntSliceFlag{Name:"seconds",EnvVars:[]string{"SECONDS"}},`could not parse "foobar" as int slice value for flag seconds: .*`},
expect(t,err,fmt.Errorf("invalid value \"2006-01-02T15:04:05Z\" for flag -time: parsing time \"2006-01-02T15:04:05Z\" as \"Jan 2, 2006 at 3:04pm (MST)\": cannot parse \"2006-01-02T15:04:05Z\" as \"Jan\""))
GitHub