aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--CHANGELOG.md6
-rw-r--r--doc.go1
-rw-r--r--subcmd.go44
-rw-r--r--subcmd_test.go41
4 files changed, 92 insertions, 0 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 350132a..65cc397 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+
+- `ManHelpCommand(prefix)` - a help command that opens man pages instead of
+ printing inline help. Uses the prefix to construct page names (e.g.,
+ `prefix` for the main page, `prefix-subcommand` for subcommand pages).
+
## [0.2.0] - 2025-10-13
### Changed
diff --git a/doc.go b/doc.go
index 9371bdb..eccb871 100644
--- a/doc.go
+++ b/doc.go
@@ -58,6 +58,7 @@
// The package provides several built-in commands:
//
// - HelpCommand() - Display help for all commands or a specific command
+// - ManHelpCommand(prefix) - Open man pages for commands (e.g., "myapp" and "myapp-subcommand")
// - CommandsCommand() - List all available command names
// - FlagsCommand() - List all top-level flags
//
diff --git a/subcmd.go b/subcmd.go
index a8ed787..56f778b 100644
--- a/subcmd.go
+++ b/subcmd.go
@@ -8,6 +8,7 @@ import (
"fmt"
"io"
"os"
+ "os/exec"
"sort"
"strings"
)
@@ -231,6 +232,49 @@ func (h *helpCommand) Execute(ctx context.Context, f *flag.FlagSet, args ...any)
return ExitSuccess
}
+// manHelpCommand implements a help command that opens man pages.
+type manHelpCommand struct {
+ prefix string
+}
+
+// ManHelpCommand returns a help command that opens man pages.
+//
+// The prefix is used to construct man page names: "prefix" for
+// the main page, "prefix-subcommand" for subcommand pages. This
+// is a common convention e.g. git(1), git-commit(1), ...
+func ManHelpCommand(prefix string) Command {
+ return &manHelpCommand{prefix: prefix}
+}
+
+func (m *manHelpCommand) Name() string { return "help" }
+func (m *manHelpCommand) Synopsis() string { return "show manual page" }
+func (m *manHelpCommand) Usage() string {
+ return "help [<subcommand>]\n\nOpen the manual page for a subcommand.\n"
+}
+func (m *manHelpCommand) SetFlags(f *flag.FlagSet) {}
+func (m *manHelpCommand) Execute(ctx context.Context, f *flag.FlagSet, args ...any) ExitStatus {
+ page := m.prefix
+ if f.NArg() > 0 {
+ for _, arg := range f.Args() {
+ page = page + "-" + arg
+ }
+ }
+
+ cmd := execCommand("man", page)
+ cmd.Stdin = os.Stdin
+ cmd.Stdout = os.Stdout
+ cmd.Stderr = os.Stderr
+ if err := cmd.Run(); err != nil {
+ return ExitFailure
+ }
+ return ExitSuccess
+}
+
+// execCommand is a thin wrapper around exec.Command to ease testing.
+var execCommand = func(name string, args ...string) *exec.Cmd {
+ return exec.Command(name, args...)
+}
+
// commandsCommand implements the built-in commands listing command.
type commandsCommand struct {
registry *Registry
diff --git a/subcmd_test.go b/subcmd_test.go
index 6841f9e..57b86c2 100644
--- a/subcmd_test.go
+++ b/subcmd_test.go
@@ -5,6 +5,7 @@ import (
"context"
"flag"
"os"
+ "os/exec"
"strings"
"testing"
@@ -250,6 +251,46 @@ func TestHelpCommand_UnknownCommand(t *testing.T) {
check.Contains(t, buf.String(), "Unknown command: unknown")
}
+func TestManHelpCommand_NoArgs(t *testing.T) {
+ var calledName string
+ var calledArgs []string
+ oldExecCommand := execCommand
+ execCommand = func(name string, args ...string) *exec.Cmd {
+ calledName = name
+ calledArgs = args
+ return exec.Command("true")
+ }
+ defer func() { execCommand = oldExecCommand }()
+ help := ManHelpCommand("myapp")
+ fs := flag.NewFlagSet("help", flag.ExitOnError)
+ fs.Parse([]string{})
+
+ status := help.Execute(context.Background(), fs)
+
+ check.Equal(t, status, ExitSuccess)
+ check.Equal(t, calledName, "man")
+ check.Equal(t, len(calledArgs), 1)
+ check.Equal(t, calledArgs[0], "myapp")
+}
+
+func TestManHelpCommand_WithSubcommand(t *testing.T) {
+ var calledArgs []string
+ oldExecCommand := execCommand
+ execCommand = func(name string, args ...string) *exec.Cmd {
+ calledArgs = args
+ return exec.Command("true")
+ }
+ defer func() { execCommand = oldExecCommand }()
+ help := ManHelpCommand("myapp")
+ fs := flag.NewFlagSet("help", flag.ExitOnError)
+ fs.Parse([]string{"build"})
+
+ status := help.Execute(context.Background(), fs)
+
+ check.Equal(t, status, ExitSuccess)
+ check.Equal(t, calledArgs[0], "myapp-build")
+}
+
func TestCommandsCommand(t *testing.T) {
var buf bytes.Buffer
r := newTestRegistry(