v2 => v3 migration guide

[suzuki-shunsuke]

About the migration of v2 to v3, please see the guide: https://cli.urfave.org/migrate-v2-to-v3/
If you find any issues or questions, please post a comment on this discussion or consider sending a PR to help improve this guide.

Changes

Warning

This doesn't cover changes covered in the guide.

v2	v3
cli.App	cli.Command
cli.NewApp	Removed
Author	any #2084 (comment) #1630
App.EnableBashCompletion	Command.EnableShellCompletion
App.CustomAppHelpTemplate	Command.CustomRootCommandHelpTemplate
App.Compiled	Removed #1579
App.RunContext	Command.Run
App.BashComplete	Command.ShellComplete
Command.Subcommands	Command.Commands
Context.*	Command.*

entity	v2	v3
Command.Int()	int	int64
IntFlag.Value	int	int64
Default shell completion flag	--generate-bash-completion	--generate-shell-completion

ActionFunc

v2 https://pkg.go.dev/github.com/urfave/cli/v2#ActionFunc

type ActionFunc func(*Context) error

v3 https://pkg.go.dev/github.com/urfave/cli/v3#ActionFunc

type ActionFunc func(context.Context, *Command) error

Migration Script

https://github.com/suzuki-shunsuke/migrate-urfave-cli-v3

Note

• https://pkg.go.dev/github.com/urfave/cli/v3
• docs: fix the link to the migration discussion from v2 to v3 #2085
• Release 3.x meta/discussion #833

[suzuki-shunsuke]

I found cli.App has gone.

https://pkg.go.dev/github.com/urfave/cli/v3

[suzuki-shunsuke]

Was cli.App replaced with cli.Command?

[dearchap]

Yes

[paralin]

@dearchap Could we have an alias?

// App is an alias to Command.
type App = Command

[suzuki-shunsuke]

App.EnableBashCompletion has gone.

[suzuki-shunsuke]

https://cli.urfave.org/v3/examples/bash-completions/

Command.EnableShellCompletion.

[suzuki-shunsuke]

App.Compiled has gone.

[suzuki-shunsuke]

Removed.

• Remove App.Compiled #1579

[suzuki-shunsuke]

App.RunContext has gone.

[suzuki-shunsuke]

Command.Run.

[suzuki-shunsuke]

The signature of ActionFunc was changed.

v2 https://pkg.go.dev/github.com/urfave/cli/v2#ActionFunc

type ActionFunc func(*Context) error

v3 https://pkg.go.dev/github.com/urfave/cli/v3#ActionFunc

type ActionFunc func(context.Context, *Command) error

Methods such as Context.String were moved to Command.

ctx.String() => cmd.String()

[suzuki-shunsuke]

cli.NewApp has gone.

[dearchap]

https://cli.urfave.org/migrate-v2-to-v3/

[paralin]

cli.Author is gone

[suzuki-shunsuke]

This one?

• Allow any instead of custom *Author type #1630

Example:

cli/app_test.go

Lines 104 to 107 in cfd0e74

	Authors: []any{
	&mail.Address{Name: "Harrison", Address: "harrison@lolwut.example.com"},
	"Oliver Allen <oliver@toyshop.example.com>",
	},

[paralin]

My change list:

We are refactoring to urfave cli v3 from v2.

Changes:

1. Change app := &cli.App{} to &cli.Command{}
2. Change cli.NewApp() to &cli.Command{...
3. ActionFunc: type ActionFunc func(*cli.Context) error => type ActionFunc func(context.Context, *cli.Command) error
4. Authors: []*cli.Author{Name: "Some Guy", Email: "someguy@google.com"} => []any{"Some Guy someguy@google.com"}
5. app.Run(os.Args) => app.Run(ctx, os.Args)

[suzuki-shunsuke]

App.BashComplete has gone. https://pkg.go.dev/github.com/urfave/cli/v2#App

Command.ShellComplete https://pkg.go.dev/github.com/urfave/cli/v3#Command

[antiphp]

What is the replacement for cli.NewContext() passing a *flag.FlagSet?

[dearchap]

There is no more flag.FlagSet. The urfave/cli library has removed its dependency on golang flag lib. There are no more cli contexts. Just pass in a context.Context to Command.Run

[antiphp]

I see. While looking around the code base I found AllowExtFlags which is somewhat close to what I was looking for. Thank you!

[ldez]

TimestampFlag.Layout has been removed/replaced:

Before:

&cli.TimestampFlag{
    Name:   "foo",
    Layout: time.RFC3339,
}

After:

&cli.TimestampFlag{
    Name:  "foo",
    Config: cli.TimestampConfig{
        Layouts: []string{time.RFC3339},
    },
}

[ldez]

The cli.Command.Writer is not propagated to sub-commands: each sub-command should either share a "global" writer or use a dedicated writer.

[suzuki-shunsuke]

cli.ShowVersion was changed.

v2: https://pkg.go.dev/github.com/urfave/cli/v2#ShowVersion

cli/help.go

Lines 312 to 319 in 9d76d15

	// ShowVersion prints the version number of the App
	func ShowVersion(cCtx *Context) {
	VersionPrinter(cCtx)
	}
	func printVersion(cCtx *Context) {
	_, _ = fmt.Fprintf(cCtx.App.Writer, "%v version %v\n", cCtx.App.Name, cCtx.App.Version)
	}

cCtx has the information of the root App.

v3: https://pkg.go.dev/github.com/urfave/cli/v3#ShowVersion

cli/help.go

Lines 331 to 339 in c96fd24

	// ShowVersion prints the version number of the App
	func ShowVersion(cmd *Command) {
	tracef("showing version via VersionPrinter (cmd=%[1]q)", cmd.Name)
	VersionPrinter(cmd)
	}
	func printVersion(cmd *Command) {
	_, _ = fmt.Fprintf(cmd.Root().Writer, "%v version %v\n", cmd.Name, cmd.Version)
	}

On the other hand, when we implement version subcommand, Command.Name and Command.Version are different from the root command name and version.

• aqua version produces incorrect output aquaproj/aqua#3716

[suzuki-shunsuke]

The default shell completion flag was changed.

v2: https://cli.urfave.org/v2/examples/bash-completions/#customization

--generate-bash-completion

v3: https://cli.urfave.org/v3/examples/completions/shell-completions/#customization

--generate-shell-completion

• fix: bash and zsh completion command generation aquaproj/aqua#3729

[sinlov]

value of uintFlag

== "v2"

// cli.UintFlag from uint
func withGlobalFlag(c *cli.Command) error {
	timeoutSecond := c.Uint("timeout_second")
	return nil
}

== "v3"

// to uint64
func withGlobalFlag(c *cli.Command) error {
	timeoutSecond := uint(c.Uint("timeout_second"))
	return nil
}

[sinlov]

List of all authors who contribute

== "v2"

func main() {
	app := cli.NewApp()
	app.Name = "testcli"
	app.Version = "1.0.0"
	author := &cli.Author{
		Name:  jsonAuthor.Name,
		Email: jsonAuthor.Email,
	}
	app.Authors = []*cli.Author{
		author,
	}
	app.Action = func(c *cli.Context) error {
		args := c.Args()
		fmt.Println(args)
		return nil
	}
	if err := app.Run(os.Args); err != nil {
		fmt.Println(err)
	}
}

== "v3" 3.1.+ with Authors []any, more info see issure #2062

func main() {
	app := &cli.Command{
		Name:                  "testcli",
		Version:               "1.0.0",
	}
	// some kit get Author struct by json raw.
	jsonAuthor := pkg_kit.GetPackageJsonAuthor()
	app.Authors = []any{
		jsonAuthor,
	}
	if err := app.Run(context.Background(), os.Args); err != nil {
		fmt.Println(err)
	}
}

[nickchomey]

The docs say v3 is still considered alpha https://cli.urfave.org/#using-alpha-level-v3-releases, but there's now a 3.2 release. Do the docs need to be updated?

[meatballhat]

@nickchomey Thank you for calling this out! #2155 should address this.

[G-Rath]

The signature of cli.VersionPrinter has changed from taking ctx *cli.Context to cmd *cli.Command, which also by extension changes some of the possible implementation, i.e. clx.App.Version is now cmd.Version.

Also is the goal to someday get these into the actual migration guide, or are they being kept separate for some reason? As I'm happy to try doing a few PRs for some of this stuff if that's ok

[G-Rath]

Also looks like the Float64 flag has been renamed to just Float

[G-Rath]

And generic flags now require a Get method

[dearchap]

@G-Rath Lots of changes have happened in the last year wrt this package. If you want to raise any PRs against docs please go for it. I will be happy to review

[G-Rath]

I've opened #2111 to start with 🙂