Merge branch 'main' into feat/stop-on-nth-arg

Author: dearchap

.github/dependabot.yml

@@ -1,10 +1,17 @@
 version: 2
 updates:
-  - package-ecosystem: "gomod"
-    directory: "/"
+  - package-ecosystem: gomod
+    directory: /
     schedule:
-      interval: "weekly"
-  - package-ecosystem: "github-actions"
-    directory: "/"
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: /
     schedule:
-      interval: "weekly"
+      interval: weekly
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python-packages:
+        patterns: ["*"]

.github/workflows/lint.yml

@@ -15,11 +15,11 @@ permissions:
 
 jobs:
   golangci-lint:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
 
     steps:
       - name: Clone repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Go
         uses: actions/setup-go@v5

.github/workflows/publish-docs.yml

@@ -13,9 +13,9 @@ permissions:
 jobs:
   test-docs:
     name: test-docs
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Set up Go
         uses: actions/setup-go@v5
@@ -44,17 +44,17 @@ jobs:
     if: startswith(github.ref, 'refs/tags/')
     name: publish
     needs: [test-docs]
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
       - uses: actions/setup-python@v5
         with:
           python-version: '3.13'
           cache: pip
-          cache-dependency-path: mkdocs-reqs.txt
+          cache-dependency-path: mkdocs-requirements.txt
 
       - name: Ensure mkdocs is available
         run: make ensure-mkdocs

.github/workflows/test.yml

@@ -17,14 +17,14 @@ jobs:
   test:
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-24.04, macos-15, windows-2025]
         go: [stable, oldstable]
 
     name: ${{ matrix.os }} @ Go ${{ matrix.go }}
     runs-on: ${{ matrix.os }}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Set up Go
         uses: actions/setup-go@v5
@@ -34,25 +34,25 @@ jobs:
       - name: Set PATH
         run: echo "${GITHUB_WORKSPACE}/.local/bin" >>"${GITHUB_PATH}"
 
-      - if: matrix.go == 'stable' && matrix.os == 'ubuntu-latest'
+      - if: matrix.go == 'stable' && matrix.os == 'ubuntu-24.04'
         run: make ensure-goimports
 
-      - if: matrix.go == 'stable' && matrix.os == 'ubuntu-latest'
+      - if: matrix.go == 'stable' && matrix.os == 'ubuntu-24.04'
         run: make lint
 
       - run: make vet
       - run: make test
       - run: make check-binary-size
 
-      - if: matrix.go == 'stable' && matrix.os == 'ubuntu-latest'
+      - if: matrix.go == 'stable' && matrix.os == 'ubuntu-24.04'
         run: make generate
 
       - run: make diffcheck
 
-      - if: matrix.go == 'stable' && matrix.os == 'ubuntu-latest'
+      - if: matrix.go == 'stable' && matrix.os == 'ubuntu-24.04'
         run: make v3diff
 
-      - if: success() && matrix.go == 'stable' && matrix.os == 'ubuntu-latest'
+      - if: success() && matrix.go == 'stable' && matrix.os == 'ubuntu-24.04'
         uses: codecov/codecov-action@v5
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

command.go

@@ -85,9 +85,9 @@ type Command struct {
 	Writer io.Writer `json:"-"`
 	// ErrWriter writes error output
 	ErrWriter io.Writer `json:"-"`
-	// ExitErrHandler processes any error encountered while running an App before
-	// it is returned to the caller. If no function is provided, HandleExitCoder
-	// is used as the default behavior.
+	// ExitErrHandler processes any error encountered while running a Command before it is
+	// returned to the caller. If no function is provided, HandleExitCoder is used as the
+	// default behavior.
 	ExitErrHandler ExitErrHandlerFunc `json:"-"`
 	// Other custom info
 	Metadata map[string]interface{} `json:"metadata"`

command_run.go

@@ -180,9 +180,9 @@ func (cmd *Command) run(ctx context.Context, osArgs []string) (_ context.Context
 		}
 		if !cmd.hideHelp() {
 			if cmd.parent == nil {
-				tracef("running ShowAppHelp")
-				if err := ShowAppHelp(cmd); err != nil {
-					tracef("SILENTLY IGNORING ERROR running ShowAppHelp %[1]v (cmd=%[2]q)", err, cmd.Name)
+				tracef("running ShowRootCommandHelp")
+				if err := ShowRootCommandHelp(cmd); err != nil {
+					tracef("SILENTLY IGNORING ERROR running ShowRootCommandHelp %[1]v (cmd=%[2]q)", err, cmd.Name)
 				}
 			} else {
 				tracef("running ShowCommandHelp with %[1]q", cmd.Name)
@@ -319,7 +319,11 @@ func (cmd *Command) run(ctx context.Context, osArgs []string) (_ context.Context
 
 	if err := cmd.checkAllRequiredFlags(); err != nil {
 		cmd.isInError = true
-		_ = ShowSubcommandHelp(cmd)
+		if cmd.OnUsageError != nil {
+			err = cmd.OnUsageError(ctx, cmd, err, cmd.parent != nil)
+		} else {
+			_ = ShowSubcommandHelp(cmd)
+		}
 		return ctx, err
 	}
 

command_test.go

@@ -4096,6 +4096,21 @@ func TestCheckRequiredFlags(t *testing.T) {
 	}
 }
 
+func TestCheckRequiredFlagsWithOnUsageError(t *testing.T) {
+	expectedError := errors.New("OnUsageError")
+	cmd := &Command{
+		Name: "foo",
+		Flags: []Flag{
+			&StringFlag{Name: "requiredFlag", Required: true},
+		},
+		OnUsageError: func(_ context.Context, _ *Command, _ error, _ bool) error {
+			return expectedError
+		},
+	}
+	actualError := cmd.Run(buildTestContext(t), []string{"requiredFlag"})
+	require.ErrorIs(t, actualError, expectedError)
+}
+
 func TestCommand_ParentCommand_Set(t *testing.T) {
 	cmd := &Command{
 		parent: &Command{
@@ -4296,6 +4311,9 @@ func TestCommandReadArgsFromStdIn(t *testing.T) {
 				},
 				&StringSliceFlag{
 					Name: "ssf",
+					Config: StringConfig{
+						TrimSpace: true,
+					},
 				},
 			}
 

docs/CONTRIBUTING.md

@@ -66,6 +66,18 @@ verify one's changes are harmonious in nature. The same steps are also run durin
 [continuous integration
 phase](https://github.com/urfave/cli/blob/main/.github/workflows/test.yml).
 
+`gfmrun` is required to run the examples, and without it `make all` will fail.
+
+You can find `gfmrun` here:
+
+- [urfave/gfmrun](https://github.com/urfave/gfmrun)
+
+To install `gfmrun`, you can use `go install`:
+
+```
+go install github.com/urfave/gfmrun/cmd/gfmrun@latest
+```
+
 In the event that the `v3diff` target exits non-zero, this is a signal that the public API
 surface area has changed. If the changes are acceptable, then manually running the
 approval step will "promote" the current `go doc` output:

docs/index.md

@@ -46,10 +46,12 @@ Go Modules are required when using this package. [See the go blog guide on using
 
 ### Using `v3` releases
 
-The latest `v3` release may be installed via the `/v3` suffix. The state of the [`main`
-branch](https://github.com/urfave/cli/tree/main) at any given time may correspond to a
-`v3` series release or pre-release.  Please see the [`v3` migration
-guide](./migrate-v2-to-v3.md) on using v3 if you are upgrading from v2.
+The latest `v3` release may be installed via the `/v3` suffix and is the
+recommended version for all new development. The state of the [`main`
+branch](https://github.com/urfave/cli/tree/main) at any given time **may**
+correspond to a `v3` series release or pre-release.  Please see the [`v3`
+migration guide](./migrate-v2-to-v3.md) on using v3 if you are upgrading from
+v2.
 
 ```sh
 go get github.com/urfave/cli/v3@latest
@@ -63,10 +65,11 @@ import (
 
 ### Using `v2` releases
 
-The `v2` series is the recommended version for new development. Ongoing
-maintenance is done on the [`v2-maint`
-branch](https://github.com/urfave/cli/tree/v2-maint) which receives **minor**
-improvements, bug fixes, and security fixes.
+:warning: The `v2` series is receiving **security and bug fixes only** via the
+[`v2-maint` branch](https://github.com/urfave/cli/tree/v2-maint) and **should
+not** be used in new development. Please see the [`v3` migration
+guide](./migrate-v2-to-v3.md) and feel free to open an issue or discussion if
+you need help with the migration to `v3`.
 
 ```sh
 go get github.com/urfave/cli/v2@latest
@@ -81,7 +84,7 @@ import (
 ### Using `v1` releases
 
 :warning: The `v1` series is receiving **security fixes only** via the
-[`v1-maint`](https://github.com/urfave/cli/tree/v1-maint) branch and **should
+[`v1-maint` branch](https://github.com/urfave/cli/tree/v1-maint) and **should
 not** be used in new development. Please see the [`v2` migration
 guide](./migrate-v1-to-v2.md) and feel free to open an issue or discussion if
 you need help with the migration to `v2`.

docs/v3/examples/arguments/advanced.md

@@ -7,7 +7,7 @@ search:
 
 The [Basics] showed how to access arguments for a command. They are all retrieved as strings which is fine
 but it we need to say get integers or timestamps the user would have to convert from string to desired type. 
-To ease the burden on users the `cli` library offers predefined `{Type}Arg` and `{Type}Args` structure to faciliate this
+To ease the burden on users the `cli` library offers predefined `{Type}Arg` and `{Type}Args` structure to faciliate this.
 The value of the argument can be retrieved using the `command.{Type}Arg()` function. For e.g
 
 <!-- {
@@ -152,9 +152,9 @@ func main() {
 
 Some things to note about multi value arguments
 
-1. They are of `{Type}Args` type rather than `{Type}Arg` to differentiate them from single value arguments
-2. The `Max` field needs to be defined to a non zero value without which it cannot be parsed
-3. `Max` field value needs to be greater than the `Min` field value
+1. They are of `{Type}Args` type rather than `{Type}Arg` to differentiate them from single value arguments.
+2. The `Max` field needs to be defined to a non zero value without which it cannot be parsed.
+3. `Max` field value needs to be greater than the `Min` field value.
 
 As with single value args the destination field can be set
 
@@ -221,4 +221,4 @@ the following to the end of the Arguments slice and retrieve them as a slice
 &StringArgs{
 	Max: -1,
 },
-```
+```