Skip to content

Commit efab65a

Browse files
authored
Merge pull request #2093 from ldez/feat/improve-migration-guide
docs: improve migration guide v3
2 parents 20335c6 + 056c86f commit efab65a

File tree

3 files changed

+124
-41
lines changed

3 files changed

+124
-41
lines changed

docs/migrate-v2-to-v3.md

Lines changed: 114 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ If you find any issues not covered by this document, please post a
99
comment on [the discussion](https://github.com/urfave/cli/discussions/2084) or
1010
consider sending a PR to help improve this guide.
1111

12-
## Import string changed
12+
## New Import
1313

1414
=== "v2"
1515

@@ -23,9 +23,9 @@ Check each file for this and make the change.
2323

2424
Shell command to find them all: `fgrep -rl github.com/urfave/cli/v2 *`
2525

26-
## FilePath
26+
## Sources
2727

28-
Change `FilePath: "XXXXX"` to `Sources: Files("XXXXX")`.
28+
### FilePath
2929

3030
=== "v2"
3131

@@ -39,13 +39,21 @@ Change `FilePath: "XXXXX"` to `Sources: Files("XXXXX")`.
3939

4040
```go
4141
cli.StringFlag{
42-
Sources: Files("/path/to/foo"),
42+
Sources: cli.Files("/path/to/foo"),
4343
}
4444
```
4545

46-
## EnvVars
46+
or
4747

48-
Change `EnvVars: "XXXXX"` to `Sources: EnvVars("XXXXX")`.
48+
```go
49+
cli.StringFlag{
50+
Sources: cli.NewValueSourceChain(
51+
cli.File("/path/to/foo"),
52+
),
53+
}
54+
```
55+
56+
### EnvVars
4957

5058
=== "v2"
5159

@@ -59,83 +67,107 @@ Change `EnvVars: "XXXXX"` to `Sources: EnvVars("XXXXX")`.
5967

6068
```go
6169
cli.StringFlag{
62-
Sources: EnvVars("APP_LANG"),
70+
Sources: cli.EnvVars("APP_LANG"),
71+
}
72+
```
73+
74+
or
75+
76+
```go
77+
cli.StringFlag{
78+
Sources: cli.NewValueSourceChain(
79+
cli.EnvVar("APP_LANG"),
80+
),
6381
}
6482
```
6583

66-
## Altsrc has been moved out of the cli library into its own repo
84+
### Altsrc
85+
86+
#### Altsrc is now a dedicated module
6787

6888
=== "v2"
6989

7090
`import "github.com/urfave/cli/v2/altsrc"`
7191

7292
=== "v3"
7393

74-
`import "github.com/urfave/cli-altsrc/v3"`
94+
`import altsrc "github.com/urfave/cli-altsrc/v3"`
7595

76-
## Altsrc is now a value source for cli
96+
#### Altsrc is now a value source for CLI
7797

7898
=== "v2"
7999

80100
```go
81-
altsrc.StringFlag{
82-
&cli.String{....}
83-
}
101+
altsrc.NewStringFlag(
102+
&cli.StringFlag{
103+
Name: "key",
104+
Value: "/tmp/foo",
105+
},
106+
),
84107
```
85108

86109
=== "v3"
87110

111+
Requires to use at least `github.com/urfave/cli-altsrc/v3@v3.0.0-alpha2.0.20250227140532-11fbec4d81a7`
112+
88113
```go
89114
cli.StringFlag{
90-
Sources: altsrc.JSON("key", "/tmp/foo")
115+
Sources: cli.NewValueSourceChain(altsrcjson.JSON("key", altsrc.StringSourcer("/path/to/foo.json"))),
91116
}
92117
```
93118

94-
## Order of precedence of envvars, filepaths, altsrc now depends on the order in which they are defined
95-
119+
### Order of precedence of envvars, filepaths, altsrc now depends on the order in which they are defined
96120

97121
=== "v2"
98122

99123
```go
100-
cli.StringFlag{
101-
EnvVars: []string{"APP_LANG"},
102-
}
103-
cli.StringFlag{
124+
altsrc.NewStringFlag(
125+
&cli.StringFlag{
126+
Name: "key",
127+
EnvVars: []string{"APP_LANG"},
104128
FilePath: "/path/to/foo",
105-
}
129+
},
130+
),
106131
```
107132

108133
=== "v3"
109134

135+
Requires to use at least `github.com/urfave/cli-altsrc/v3@v3.0.0-alpha2.0.20250227140532-11fbec4d81a7`
136+
110137
```go
111-
cli.StringFlag{
112-
Sources: cli.ValueSourceChain{
113-
Chain: {
114-
EnvVars("APP_LANG"),
115-
Files("/path/to/foo"),
116-
altsrc.JSON("foo", "/path/to/"),
117-
}
118-
},
119-
}
138+
import altsrcjson "github.com/urfave/cli-altsrc/v3/json"
139+
140+
// ...
141+
142+
&cli.StringFlag{
143+
Name: "key",
144+
Sources: cli.NewValueSourceChain(
145+
cli.EnvVar("APP_LANG"),
146+
cli.File("/path/to/foo"),
147+
altsrcjson.JSON("key", altsrc.StringSourcer("/path/to/foo.json")),
148+
),
149+
},
120150
```
121151

122152
In the above case the Envs are checked first and if not found then files are looked at and then finally the `altsrc`
123153

124154
## cli.Context has been removed
125155

126-
All functions handled previously by cli.Context have been incorporated into `cli.Command`:
156+
All functions handled previously by `cli.Context` have been incorporated into `cli.Command`:
127157

128-
* Change `cli.Context.IsSet` -> `cli.Command.IsSet`
129-
* Change `cli.Context.NumFlags` -> `cli.Command.NumFlags`
130-
* Change `cli.Context.FlagNames` -> `cli.Command.FlagNames`
131-
* Change `cli.Context.LocalFlagNames` -> `cli.Command.LocalFlagNames`
132-
* Change `cli.Context.Lineage` -> `cli.Command.Lineage`
133-
* Change `cli.Context.Count` -> `cli.Command.Count`
134-
* Change `cli.Context.Value` -> `cli.Command.Value`
135-
* Change `cli.Context.Args` -> `cli.Command.Args`
136-
* Change `cli.Context.NArg` -> `cli.Command.NArg`
158+
| v2 | v3 |
159+
|------------------------------|------------------------------|
160+
| `cli.Context.IsSet` | `cli.Command.IsSet` |
161+
| `cli.Context.NumFlags` | `cli.Command.NumFlags` |
162+
| `cli.Context.FlagNames` | `cli.Command.FlagNames` |
163+
| `cli.Context.LocalFlagNames` | `cli.Command.LocalFlagNames` |
164+
| `cli.Context.Lineage` | `cli.Command.Lineage` |
165+
| `cli.Context.Count` | `cli.Command.Count` |
166+
| `cli.Context.Value` | `cli.Command.Value` |
167+
| `cli.Context.Args` | `cli.Command.Args` |
168+
| `cli.Context.NArg` | `cli.Command.NArg` |
137169

138-
## Handler func signatures have changed
170+
## Handler Function Signatures Changes
139171

140172
All handler functions now take at least 2 arguments a `context.Context` and a pointer to `Cli.Command`
141173
in addition to other specific args. This allows handler functions to utilize `context.Context` for
@@ -240,3 +272,44 @@ Similar messages would be shown for other funcs.
240272
},
241273
}
242274
```
275+
276+
## Authors
277+
278+
=== "v2"
279+
280+
```go
281+
&cli.App{
282+
Authors: []*cli.Author{
283+
{Name: "Some Guy", Email: "someguy@example.com"},
284+
},
285+
}
286+
```
287+
288+
=== "v3"
289+
290+
```go
291+
// import "net/mail"
292+
&cli.Command{
293+
Authors: []any{
294+
mail.Address{Name: "Some Guy", Address: "someguy@example.com"},
295+
},
296+
}
297+
```
298+
299+
## BashCompletion/ShellCompletion
300+
301+
=== "v2"
302+
303+
```go
304+
&cli.App{
305+
EnableBashCompletion: true,
306+
}
307+
```
308+
309+
=== "v3"
310+
311+
```go
312+
&cli.Command{
313+
EnableShellCompletion: true,
314+
}
315+
```

docs/v2/migrating-to-v3.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
tags:
3+
- v2
4+
---
5+
6+
There are a small set of breaking changes between v2 and v3.
7+
Converting is relatively straightforward and typically takes less than
8+
an hour. Specific steps are included in
9+
[Migration Guide: v2 to v3](../migrate-v2-to-v3.md).

mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ nav:
4343
- Full API Example: v3/examples/full-api-example.md
4444
- v2 Manual:
4545
- Getting Started: v2/getting-started.md
46+
- Migrating to v3: v2/migrating-to-v3.md
4647
- Migrating From Older Releases: v2/migrating-from-older-releases.md
4748
- Examples:
4849
- Greet: v2/examples/greet.md

0 commit comments

Comments
 (0)