From 7a43c33b150f6ad2adff2772e9ed131a998bb026 Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Mon, 7 Apr 2025 00:00:52 +0200 Subject: [PATCH 1/9] docs: improve migration guide v3 --- docs/migrate-v2-to-v3.md | 84 +++++++++++++++++++++++++++++--------- docs/v2/migrating-to-v3.md | 9 ++++ mkdocs.yml | 1 + 3 files changed, 75 insertions(+), 19 deletions(-) create mode 100644 docs/v2/migrating-to-v3.md diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md index 625f8f0388..a7c75390e5 100644 --- a/docs/migrate-v2-to-v3.md +++ b/docs/migrate-v2-to-v3.md @@ -9,7 +9,7 @@ If you find any issues not covered by this document, please post a comment on [the discussion](https://github.com/urfave/cli/discussions/2084) or consider sending a PR to help improve this guide. -## Import string changed +## New Import === "v2" @@ -23,7 +23,9 @@ Check each file for this and make the change. Shell command to find them all: `fgrep -rl github.com/urfave/cli/v2 *` -## FilePath +## Sources + +### FilePath Change `FilePath: "XXXXX"` to `Sources: Files("XXXXX")`. @@ -43,7 +45,7 @@ Change `FilePath: "XXXXX"` to `Sources: Files("XXXXX")`. } ``` -## EnvVars +### EnvVars Change `EnvVars: "XXXXX"` to `Sources: EnvVars("XXXXX")`. @@ -63,7 +65,9 @@ Change `EnvVars: "XXXXX"` to `Sources: EnvVars("XXXXX")`. } ``` -## Altsrc has been moved out of the cli library into its own repo +### Altsrc + +#### Altsrc is now a dedicated module === "v2" @@ -71,9 +75,9 @@ Change `EnvVars: "XXXXX"` to `Sources: EnvVars("XXXXX")`. === "v3" - `import "github.com/urfave/cli-altsrc/v3"` + `import altsrc "github.com/urfave/cli-altsrc/v3"` -## Altsrc is now a value source for cli +#### Altsrc is now a value source for CLI === "v2" @@ -91,8 +95,7 @@ Change `EnvVars: "XXXXX"` to `Sources: EnvVars("XXXXX")`. } ``` -## Order of precedence of envvars, filepaths, altsrc now depends on the order in which they are defined - +### Order of precedence of envvars, filepaths, altsrc now depends on the order in which they are defined === "v2" @@ -123,19 +126,21 @@ In the above case the Envs are checked first and if not found then files are loo ## cli.Context has been removed -All functions handled previously by cli.Context have been incorporated into `cli.Command`: +All functions handled previously by `cli.Context` have been incorporated into `cli.Command`: -* Change `cli.Context.IsSet` -> `cli.Command.IsSet` -* Change `cli.Context.NumFlags` -> `cli.Command.NumFlags` -* Change `cli.Context.FlagNames` -> `cli.Command.FlagNames` -* Change `cli.Context.LocalFlagNames` -> `cli.Command.LocalFlagNames` -* Change `cli.Context.Lineage` -> `cli.Command.Lineage` -* Change `cli.Context.Count` -> `cli.Command.Count` -* Change `cli.Context.Value` -> `cli.Command.Value` -* Change `cli.Context.Args` -> `cli.Command.Args` -* Change `cli.Context.NArg` -> `cli.Command.NArg` +| v2 | v3 | +|------------------------------|------------------------------| +| `cli.Context.IsSet` | `cli.Command.IsSet` | +| `cli.Context.NumFlags` | `cli.Command.NumFlags` | +| `cli.Context.FlagNames` | `cli.Command.FlagNames` | +| `cli.Context.LocalFlagNames` | `cli.Command.LocalFlagNames` | +| `cli.Context.Lineage` | `cli.Command.Lineage` | +| `cli.Context.Count` | `cli.Command.Count` | +| `cli.Context.Value` | `cli.Command.Value` | +| `cli.Context.Args` | `cli.Command.Args` | +| `cli.Context.NArg` | `cli.Command.NArg` | -## Handler func signatures have changed +## Handler Function Signatures Changes All handler functions now take at least 2 arguments a `context.Context` and a pointer to `Cli.Command` in addition to other specific args. This allows handler functions to utilize `context.Context` for @@ -240,3 +245,44 @@ Similar messages would be shown for other funcs. }, } ``` + +## Authors + +=== "v2" + + ```go + &cli.App{ + Authors: []*cli.Author{ + {Name: "Some Guy", Email: "someguy@example.com"}, + }, + } + ``` + +=== "v3" + + ```go + // import "net/mail" + &cli.Command{ + Authors: []any{ + mail.Address{Name: "Some Guy", Address: "someguy@example.com"}, + }, + } + ``` + +## BashCompletion/ShellCompletion + +=== "v2" + + ```go + &cli.App{ + EnableBashCompletion: true, + } + ``` + +=== "v3" + + ```go + &cli.Command{ + EnableShellCompletion: true, + } + ``` diff --git a/docs/v2/migrating-to-v3.md b/docs/v2/migrating-to-v3.md new file mode 100644 index 0000000000..a0db6fb187 --- /dev/null +++ b/docs/v2/migrating-to-v3.md @@ -0,0 +1,9 @@ +--- +tags: + - v2 +--- + +There are a small set of breaking changes between v2 and v3. +Converting is relatively straightforward and typically takes less than +an hour. Specific steps are included in +[Migration Guide: v2 to v3](../migrate-v2-to-v3.md). diff --git a/mkdocs.yml b/mkdocs.yml index 3c09278d44..041c7131ad 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,6 +43,7 @@ nav: - Full API Example: v3/examples/full-api-example.md - v2 Manual: - Getting Started: v2/getting-started.md + - Migrating to v3: v2/migrating-to-v3.md - Migrating From Older Releases: v2/migrating-from-older-releases.md - Examples: - Greet: v2/examples/greet.md From 6f97fbc5bc3eb9602269a9f4fc93aa89b7797506 Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Mon, 7 Apr 2025 00:12:07 +0200 Subject: [PATCH 2/9] docs: fix chain example --- docs/migrate-v2-to-v3.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md index a7c75390e5..640955bcc8 100644 --- a/docs/migrate-v2-to-v3.md +++ b/docs/migrate-v2-to-v3.md @@ -102,8 +102,6 @@ Change `EnvVars: "XXXXX"` to `Sources: EnvVars("XXXXX")`. ```go cli.StringFlag{ EnvVars: []string{"APP_LANG"}, - } - cli.StringFlag{ FilePath: "/path/to/foo", } ``` @@ -112,13 +110,13 @@ Change `EnvVars: "XXXXX"` to `Sources: EnvVars("XXXXX")`. ```go cli.StringFlag{ - Sources: cli.ValueSourceChain{ - Chain: { - EnvVars("APP_LANG"), - Files("/path/to/foo"), - altsrc.JSON("foo", "/path/to/"), - } - }, + Sources: cli.ValueSourceChain{ + Chain: []cli.ValueSource{ + cli.EnvVar("APP_LANG"), + cli.File("/path/to/foo"), + altsrc.JSON("foo", "/path/to/"), + }, + }, } ``` From c2c23faad509104089e749ce5a82e5f9d071bb66 Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Mon, 7 Apr 2025 00:33:37 +0200 Subject: [PATCH 3/9] docs: fix altsrc example --- docs/migrate-v2-to-v3.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md index 640955bcc8..08c6284f61 100644 --- a/docs/migrate-v2-to-v3.md +++ b/docs/migrate-v2-to-v3.md @@ -82,9 +82,12 @@ Change `EnvVars: "XXXXX"` to `Sources: EnvVars("XXXXX")`. === "v2" ```go - altsrc.StringFlag{ - &cli.String{....} - } + altsrc.NewStringFlag( + &cli.StringFlag{ + Name: "key", + Value: "/tmp/foo", + }, + ), ``` === "v3" From d9cf513360674fc97e8dd4a1df634c4915e55334 Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Mon, 7 Apr 2025 00:37:22 +0200 Subject: [PATCH 4/9] docs: fix FilePath and EnvVars examples --- docs/migrate-v2-to-v3.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md index 08c6284f61..e15c32bc98 100644 --- a/docs/migrate-v2-to-v3.md +++ b/docs/migrate-v2-to-v3.md @@ -41,13 +41,13 @@ Change `FilePath: "XXXXX"` to `Sources: Files("XXXXX")`. ```go cli.StringFlag{ - Sources: Files("/path/to/foo"), + Sources: cli.Files("/path/to/foo"), } ``` ### EnvVars -Change `EnvVars: "XXXXX"` to `Sources: EnvVars("XXXXX")`. +Change `EnvVars: "XXXXX"` to `Sources: cli.EnvVars("XXXXX")`. === "v2" @@ -61,7 +61,7 @@ Change `EnvVars: "XXXXX"` to `Sources: EnvVars("XXXXX")`. ```go cli.StringFlag{ - Sources: EnvVars("APP_LANG"), + Sources: cli.EnvVars("APP_LANG"), } ``` From 28f46d14c8a1bd59336ddc28a5181af065c37bc1 Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Mon, 7 Apr 2025 00:42:13 +0200 Subject: [PATCH 5/9] docs: improve FilePath and EnvVars exmaples --- docs/migrate-v2-to-v3.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md index e15c32bc98..da583f20d5 100644 --- a/docs/migrate-v2-to-v3.md +++ b/docs/migrate-v2-to-v3.md @@ -27,8 +27,6 @@ Shell command to find them all: `fgrep -rl github.com/urfave/cli/v2 *` ### FilePath -Change `FilePath: "XXXXX"` to `Sources: Files("XXXXX")`. - === "v2" ```go @@ -45,9 +43,19 @@ Change `FilePath: "XXXXX"` to `Sources: Files("XXXXX")`. } ``` -### EnvVars + or -Change `EnvVars: "XXXXX"` to `Sources: cli.EnvVars("XXXXX")`. + ```go + cli.StringFlag{ + Sources: cli.ValueSourceChain{ + Chain: []cli.ValueSource{ + cli.File("/path/to/foo"), + }, + }, + } + ``` + +### EnvVars === "v2" @@ -65,6 +73,18 @@ Change `EnvVars: "XXXXX"` to `Sources: cli.EnvVars("XXXXX")`. } ``` + or + + ```go + cli.StringFlag{ + Sources: cli.ValueSourceChain{ + Chain: []cli.ValueSource{ + cli.EnvVar("APP_LANG") + }, + }, + } + ``` + ### Altsrc #### Altsrc is now a dedicated module From 0e955c4efb695261511c786fb5b58686f6631741 Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Mon, 7 Apr 2025 00:52:58 +0200 Subject: [PATCH 6/9] docs: fix precedence example --- docs/migrate-v2-to-v3.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md index da583f20d5..83b7c4f056 100644 --- a/docs/migrate-v2-to-v3.md +++ b/docs/migrate-v2-to-v3.md @@ -123,21 +123,25 @@ Shell command to find them all: `fgrep -rl github.com/urfave/cli/v2 *` === "v2" ```go - cli.StringFlag{ - EnvVars: []string{"APP_LANG"}, + altsrc.NewStringFlag( + &cli.StringFlag{ + Name: "key", + EnvVars: []string{"APP_LANG"}, FilePath: "/path/to/foo", - } + }, + ), ``` === "v3" ```go cli.StringFlag{ + Name: "key", Sources: cli.ValueSourceChain{ Chain: []cli.ValueSource{ cli.EnvVar("APP_LANG"), cli.File("/path/to/foo"), - altsrc.JSON("foo", "/path/to/"), + altsrc.JSON("key", "/path/to/foo"), }, }, } From 6a34e8d0f4c08914988fffdbb92cfa35307efb27 Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Mon, 7 Apr 2025 01:05:03 +0200 Subject: [PATCH 7/9] docs: improve chain examples --- docs/migrate-v2-to-v3.md | 34 ++++++++++++++-------------------- 1 file changed, 14 insertions(+), 20 deletions(-) diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md index 83b7c4f056..0658bca857 100644 --- a/docs/migrate-v2-to-v3.md +++ b/docs/migrate-v2-to-v3.md @@ -47,11 +47,9 @@ Shell command to find them all: `fgrep -rl github.com/urfave/cli/v2 *` ```go cli.StringFlag{ - Sources: cli.ValueSourceChain{ - Chain: []cli.ValueSource{ - cli.File("/path/to/foo"), - }, - }, + Sources: cli.NewValueSourceChain( + cli.File("/path/to/foo"), + ), } ``` @@ -77,11 +75,9 @@ Shell command to find them all: `fgrep -rl github.com/urfave/cli/v2 *` ```go cli.StringFlag{ - Sources: cli.ValueSourceChain{ - Chain: []cli.ValueSource{ - cli.EnvVar("APP_LANG") - }, - }, + Sources: cli.NewValueSourceChain( + cli.EnvVar("APP_LANG"), + ), } ``` @@ -135,16 +131,14 @@ Shell command to find them all: `fgrep -rl github.com/urfave/cli/v2 *` === "v3" ```go - cli.StringFlag{ - Name: "key", - Sources: cli.ValueSourceChain{ - Chain: []cli.ValueSource{ - cli.EnvVar("APP_LANG"), - cli.File("/path/to/foo"), - altsrc.JSON("key", "/path/to/foo"), - }, - }, - } + &cli.StringFlag{ + Name: "key", + Sources: cli.NewValueSourceChain( + cli.EnvVar("APP_LANG"), + cli.File("/path/to/foo"), + altsrc.JSON("key", "/path/to/foo"), + ), + }, ``` In the above case the Envs are checked first and if not found then files are looked at and then finally the `altsrc` From 7d0e69ecdde1d5c37835178e08d606427187b6a5 Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Mon, 7 Apr 2025 01:47:58 +0200 Subject: [PATCH 8/9] docs: fix precedence example --- docs/migrate-v2-to-v3.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md index 0658bca857..062506c680 100644 --- a/docs/migrate-v2-to-v3.md +++ b/docs/migrate-v2-to-v3.md @@ -130,13 +130,19 @@ Shell command to find them all: `fgrep -rl github.com/urfave/cli/v2 *` === "v3" + Requires to use at least `github.com/urfave/cli-altsrc/v3@v3.0.0-alpha2.0.20250227140532-11fbec4d81a7` + ```go + import altsrcjson "github.com/urfave/cli-altsrc/v3/json" + + // ... + &cli.StringFlag{ Name: "key", Sources: cli.NewValueSourceChain( cli.EnvVar("APP_LANG"), cli.File("/path/to/foo"), - altsrc.JSON("key", "/path/to/foo"), + altsrcjson.JSON("key", altsrc.StringSourcer("/path/to/foo.json")), ), }, ``` From 056c86fe72f126ddc727c1fff99648e4ef01515e Mon Sep 17 00:00:00 2001 From: Fernandez Ludovic Date: Mon, 7 Apr 2025 01:50:59 +0200 Subject: [PATCH 9/9] docs: fix altsrc example --- docs/migrate-v2-to-v3.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md index 062506c680..1b023ffcfd 100644 --- a/docs/migrate-v2-to-v3.md +++ b/docs/migrate-v2-to-v3.md @@ -108,9 +108,11 @@ Shell command to find them all: `fgrep -rl github.com/urfave/cli/v2 *` === "v3" + Requires to use at least `github.com/urfave/cli-altsrc/v3@v3.0.0-alpha2.0.20250227140532-11fbec4d81a7` + ```go cli.StringFlag{ - Sources: altsrc.JSON("key", "/tmp/foo") + Sources: cli.NewValueSourceChain(altsrcjson.JSON("key", altsrc.StringSourcer("/path/to/foo.json"))), } ```