diff --git a/README.md b/README.md index ae9d19b068..408668bc3e 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,10 @@ Usage documentation exists for each major version. Don't know what version you'r - `v2` - [./docs/v2/manual.md](./docs/v2/manual.md) - `v1` - [./docs/v1/manual.md](./docs/v1/manual.md) +Guides for migrating to newer versions: + +- `v1-to-v2` - [./docs/migrate-v1-to-v2.md](./docs/migrate-v1-to-v2.md) + ## Installation Using this package requires a working Go environment. [See the install instructions for Go](http://golang.org/doc/install.html). diff --git a/docs/migrate-v1-to-v2.md b/docs/migrate-v1-to-v2.md new file mode 100644 index 0000000000..8d56a39935 --- /dev/null +++ b/docs/migrate-v1-to-v2.md @@ -0,0 +1,176 @@ +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. + + + + * [Flags before args](#flags-before-args) + * [Import string changed](#import-string-changed) + * [Flag aliases are done differently.](#flag-aliases-are-done-differently) + * [Commands are now lists of pointers](#commands-are-now-lists-of-pointers) + * [Lists of commands should be pointers](#lists-of-commands-should-be-pointers) + * [cli.Flag changed](#cliflag-changed) + * [Appending Commands](#appending-commands) + * [Actions returns errors](#actions-returns-errors) + * [Everything else](#everything-else) + * [Full API Example](#full-api-example) + + + +# 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. + +# 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 +``` + +# 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. diff --git a/docs/v1/manual.md b/docs/v1/manual.md index 51c5b72f3d..05ea37032e 100644 --- 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) @@ -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). diff --git a/docs/v2/manual.md b/docs/v2/manual.md index 71f5699917..55008b4b55 100644 --- a/docs/v2/manual.md +++ b/docs/v2/manual.md @@ -3,6 +3,7 @@ cli v2 manual +- [Migrating From Older Releases](#migrating-from-older-releases) - [Getting Started](#getting-started) - [Examples](#examples) * [Arguments](#arguments) @@ -38,6 +39,13 @@ cli v2 manual +## 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). + ## Getting Started One of the philosophies behind cli is that an API should be playful and full of