[kolyshkin]

Using text/template disables linker dead code elimination of exported methods for the whole program (golang/go#72895), which can noticeably increase the binary size.

This adds urfave_cli_no_template build tag, which renders the default help and fish completion without text/template, producing the same output.

Custom templates are not supported in this mode:

• RootCommandHelpTemplate, CommandHelpTemplate, SubcommandHelpTemplate and FishCompletionTemplate are short string constants, only used to tell which help is requested, so modifying them is a compile error;
• if the default help printer is used with a custom template (such as CustomRootCommandHelpTemplate or CustomHelpTemplate), it panics. A custom template handled by a custom HelpPrinter is fine.

With this tag, examples/example-cli is 3.2 MB instead of 5.1 MB, and runc is 10.5 MB instead of 12.4 MB (with opencontainers/runc#5486 applied, which fixes the only other reason DCE is disabled in runc); all 19 help pages of runc are byte-for-byte identical.

Testing:

• the existing test suite is run with this tag in CI (skipping custom template tests);
• a new golden test (TestHelpOutput) renders various help pages and fish completion, making sure both modes produce the exact same output;
• TestNoTemplateTagDCE makes sure there are no <ReflectMethod> symbols (which disable DCE) in examples/example-cli built with this tag;
• make check-binary-size now also shows the size with this tag.

Closes #2277.

An alternative, in which the template-less rendering code is generated from the templates, was proposed in #2442 (now closed).

[kolyshkin]

Added the forth commit to modify check-binary-size CI job to show size with the new tag; here's the output:

2.2MB is the current binary size
0.7MB is the current binary size with urfave_cli_no_template build tag
  ✅ 1.5MB is the target min size
  ✅ 2.2MB is the target max size

[kolyshkin]

@ldez @seanamos @abitrolly PTAL

[ldez]

I wanted to create a PR based on the issue but I was waiting for feedback from urfave/cli maintainers before opening it because this is significant change.

I will review and test the 2 PRs as soon as possible.

[kolyshkin]

@dearchap @Juneezee PTAL

[Juneezee]

Thanks for writing both versions, it makes the trade-off easy to see.

I checked both branches locally with Go 1.27.1:

• Tests pass with and without the tag.
• examples/example-cli: 5.58 MB -> 3.28 MB (#2441) and 3.30 MB (#2442).
• With the tag, go build -ldflags=-dumpdep ./examples/example-cli shows no <ReflectMethod> symbols (27 without the tag), so DCE is back.
• Help output was byte-for-byte identical in both modes for extra commands outside the golden test (wrap widths, flag categories, persistent flags, subcommand UsageText/Category, pointer and value authors).

Which approach

I prefer #2441. The default templates change a few times a year (9 commits to template.go since 2024). The golden test covers almost all of the hand-written renderer, and the tagged CI run catches drift. Both need a second step when a template changes (go generate vs. a hand edit), so the real difference is the generator itself. It is nicely done, but it adds a 576-line template compiler (internal/genhelp/main.go) and 352 generated lines (help_notemplate_gen.go), where #2441 has one 341-line file of plain Go (help_notemplate.go).

Side note: the two descriptions disagree. #2441 says "I prefer this PR" and #2442 says "my preference is this one". Could you update whichever is stale?

Custom templates fail silently (both PRs)

With the tag, a custom or modified template prints no help, Run returns nil, and nothing is logged unless CLI_TEMPLATE_ERROR_DEBUG is set:

cli/help_notemplate.go

Lines 63 to 73 in 628df91

	switch templ {
	case defaultRootCommandHelpTemplate:
	h.root()
	case defaultCommandHelpTemplate:
	h.command()
	case defaultSubcommandHelpTemplate:
	h.subcommand()
	default:
	handleTemplateError(errNoTemplate)
	return
	}

cli/help.go

Lines 361 to 371 in d1d8108

	func handleTemplateError(err error) {
	if err != nil {
	tracef("error encountered during template parse: %[1]v", err)
	// If the writer is closed, t.Execute will fail, and there's nothing
	// we can do to recover.
	if os.Getenv("CLI_TEMPLATE_ERROR_DEBUG") != "" {
	_, _ = fmt.Fprintf(ErrWriter, "CLI TEMPLATE ERROR: %#v\n", err)
	}
	return
	}
	}

Example:

package main

import (
	"context"

	"github.com/urfave/cli/v3"
)

func main() {
	cmd := &cli.Command{Name: "app", CustomRootCommandHelpTemplate: "NAME: {{.Name}}\n"}
	_ = cmd.Run(context.Background(), []string{"app", "--help"})
}

go run . prints NAME: app. go run -tags urfave_cli_no_template . prints nothing. The same happens with cli.RootCommandHelpTemplate += "...".

This can bite a binary author who adds the tag without knowing that a dependency customizes the templates. ToFishCompletion already returns errNoTemplate, so help could report it too. Replacing both handleTemplateError(errNoTemplate) calls in DefaultPrintHelpCustom with

_, _ = fmt.Fprintln(ErrWriter, errNoTemplate)

works, and both test suites pass on both PRs after skipping TestPrintHelpCustomTemplateError with the tag. That test is about template parse errors. With the tag it only passes because data is not a *Command, so it hits the errNoTemplate path:

cli/help_test.go

Lines 2314 to 2328 in d1d8108

	t.Setenv("CLI_TEMPLATE_ERROR_DEBUG", "true")
	for _, tmpl := range tmpls {
	oldtmpl := *tmpl
	// safety mechanism in case something fails
	defer func(stmpl *string) { *stmpl = oldtmpl }(tmpl)
	errBuf := &bytes.Buffer{}
	ErrWriter = errBuf
	buf := &bytes.Buffer{}
	*tmpl = "{{junk"
	DefaultPrintHelpCustom(buf, "", "", nil)
	assert.Contains(t, errBuf.String(), "CLI TEMPLATE ERROR")

TestNoTemplate_CustomHelpTemplate could then also check the error output.

Nits

TestNoTemplateTagDeps only looks for text/template. Checking the go build -ldflags=-dumpdep ./examples/example-cli output for <ReflectMethod> would also catch other packages that turn DCE off (html/template, a direct MethodByName call). It is cheap, about 0.4s here with a warm cache.

cli/dce_test.go

Lines 12 to 20 in 628df91

	// Using text/template disables linker's dead code elimination of exported
	// methods, so make sure it is not linked in with urfave_cli_no_template tag.
	func TestNoTemplateTagDeps(t *testing.T) {
	out, err := exec.Command("go", "list", "-deps", "-tags", "urfave_cli_no_template", ".").Output()
	require.NoError(t, err)
	deps := strings.Fields(string(out))
	require.NotEmpty(t, deps)
	require.False(t, slices.Contains(deps, "text/template"), "text/template is linked in with urfave_cli_no_template tag")
	}

(#2441 only) The golden test has no subcommand with UsageText, so this branch is never compared against the template:

cli/help_notemplate.go

Lines 142 to 144 in 628df91

	if c.UsageText != "" {
	h.WriteString(h.wrap(c.UsageText, 3))
	} else {

Looking for more input from other users and reviewers.

[kolyshkin]

@Juneezee thanks for the thorough review! Addressed everything (rebased on top of main, too):

• Custom (or modified) templates are no longer silently ignored: an error is printed to the root command's ErrWriter (or global ErrWriter if data is not a *Command) instead of help. TestNoTemplate_CustomHelpTemplate now checks this, and I've added tests for a modified RootCommandHelpTemplate and non-*Command data. TestPrintHelpCustomTemplateError is skipped with the tag. Docs updated accordingly.
• TestNoTemplateTagDeps is replaced by TestNoTemplateTagDCE, which builds examples/example-cli with -ldflags=-dumpdep and checks there are no <ReflectMethod> symbols with the tag (and, as a sanity check, that there are some without it).
• The golden test now has a subcommand with UsageText and Category.
• Added a link to proposal: text/template,html/template: Template.ExecuteLite skip resolution to methods to allow DCE golang/go#72895 to the docs.
• Closed Add urfave_cli_no_template build tag (generated code) #2442 and updated the description.

[Juneezee]

@kolyshkin Thanks for the quick update. Everything from the first review is addressed. Verified locally at commit a6313e2:

• Tests pass with and without the tag, also when merged into current main.
• A custom template now prints the error to ErrWriter, and TestNoTemplateTagDCE checks <ReflectMethod> directly.
• The golden test now covers the subcommand UsageText branch.

The fail-early idea in commit a6313e2 is useful, but the current implementation has two drawbacks.

1. Run fails even when a custom printer handles the template

checkNoCustomTemplates rejects any CustomRootCommandHelpTemplate or CustomHelpTemplate in the command tree before the action or help runs:

cli/command_run.go

Lines 113 to 116 in a6313e2

	if cmd.parent == nil {
	if err := checkNoCustomTemplates(cmd); err != nil {
	return ctx, err
	}

This breaks programs that render help themselves. The docs describe that as a full override via cli.HelpPrinter:

cli/docs/v3/examples/help/generated-help-text.md

Lines 13 to 17 in 58ec406

	All of the help text generation may be customized, and at multiple levels. The templates
	are exposed as variables `RootCommandHelpTemplate`, `CommandHelpTemplate`, and
	`SubcommandHelpTemplate` which may be reassigned or augmented, and full override is
	possible by assigning a compatible func to the `cli.HelpPrinter` variable, e.g.:

Example:

package main

import (
	"context"
	"fmt"
	"io"
	"os"

	"github.com/urfave/cli/v3"
)

func main() {
	// A help printer that does not use text/template.
	cli.HelpPrinter = func(w io.Writer, templ string, data any) {
		fmt.Fprintf(w, "custom help for %s\n", data.(*cli.Command).Name)
	}
	cmd := &cli.Command{
		Name:                          "app",
		CustomRootCommandHelpTemplate: "rendered by the custom printer",
		Action: func(context.Context, *cli.Command) error {
			fmt.Println("action ran")
			return nil
		},
	}
	if err := cmd.Run(context.Background(), os.Args); err != nil {
		fmt.Println("error:", err)
	}
}

With -tags urfave_cli_no_template, at 6d1b921 app prints action ran and app --help prints custom help for app. At a6313e2 both print:

error: command "app": custom templates are not supported when built with urfave_cli_no_template tag

It also fails programs that set a custom template but never show it. ExampleCommand_Suggest_command passed with the tag before this commit, and had to move to examples_template_test.go.

For comparison, the ErrWriter message from the earlier commit only fires when the default printer actually receives a custom template, so it does not affect these cases.

2. The default template text is gone from the API docs

The templates are now unexported constants, and the exported variables are initialized from them:

cli/help_template.go

Lines 15 to 18 in a6313e2

	// RootCommandHelpTemplate is the text template for the Default help topic.
	// cli.go uses text/template to render templates. You can
	// render custom help text by setting this variable.
	var RootCommandHelpTemplate = rootCommandHelpTemplate

As a result, the API docs no longer show the default template text, for every user and not only those using the tag. From the repository root, go doc RootCommandHelpTemplate on main (58ec406) prints the full template (30 lines, truncated here):

var RootCommandHelpTemplate = `NAME:
   {{template "helpNameTemplate" .}}

USAGE:
...

At a6313e2 it prints only:

var RootCommandHelpTemplate = rootCommandHelpTemplate
    RootCommandHelpTemplate is the text template for the Default help topic.
    cli.go uses text/template to render templates. You can render custom help
    text by setting this variable.

CommandHelpTemplate, SubcommandHelpTemplate and FishCompletionTemplate change the same way, as the godoc-current.txt diff in this commit shows. The docs/v3/examples/help/generated-help-text.md docs linked above tell users to reassign or augment these variables, so the default text is what they start from.

Summary

Failing early has real value, for example the compile error for cli.RootCommandHelpTemplate += "..." with the tag. It is worth weighing whether that justifies the drawbacks above, or whether a different implementation could avoid them.

Looking for more input from other users and reviewers.

[kolyshkin]

@Juneezee thanks again!

1. You're right, the check in Run is wrong: there are too many ways to customize help (HelpPrinter, HelpPrinterCustom, ShowRootCommandHelp, ShowCommandHelp) to reliably tell whether a custom template will end up in the default printer.

   I've dropped it, so the last commit (now 0443c43) only makes the default templates constants with the tag. A custom template set via Custom*Template is handled as before (an error is printed to ErrWriter if it reaches the default printer), ExampleCommand_Suggest_command is back in examples_test.go, and I've added TestNoTemplate_CustomHelpPrinter based on your example.

2. I don't think this is an issue. The template text is still one click away in the source, and it's not shown on pkg.go.dev anyway:

   var RootCommandHelpTemplate = `` /* 873-byte string literal not displayed */

[kolyshkin]

Update: the template constants with the tag are now just short strings ("root", "command", etc.), since templates are not used in this mode anyway. As a result, the template variables (without the tag) are back to how they were, and the API docs are unchanged from main.

[kolyshkin]

Reworked the patchset (and rebased on top of main). Changes since my last comment:

• The series is now 4 commits, with no back-and-forth: the first commit moves everything that only makes sense with text/template (including RootCommandHelpTemplate etc.) to help_template.go, and the second one adds the tag in its final form.
• With the tag, using a custom template with the default help printer now panics instead of printing an error to ErrWriter, same as a broken custom template already does without the tag (via template.Must). A custom HelpPrinter still works fine.
• Removed the test checking that modifying the template constants is a compile error, since it only tests the Go language.
• Docs: the tag and its limitations are now described in README (as build tags used to be), binary-size.md only covers the dead code elimination aspect and links to README, and the v2-to-v3 migration guide mentions the new tag.
• Updated the PR description. Note that for runc, the binary size gain also needs libct: don't use reflect to log CRIU options opencontainers/runc#5486.

[Juneezee]

@kolyshkin LGTM, thanks! Verified locally at 04c7fd4: tests pass with and without the tag, and with the tag examples/example-cli has no <ReflectMethod> symbols.

Two optional follow-ups, not blocking:

1. With the tag, a custom HelpPrinter receives "root", "command" or "subcommand" as templ instead of the template text:

cli/help_notemplate.go

Lines 17 to 28 in 04c7fd4

	// With urfave_cli_no_template tag, templates are not used, and these are
	// only used to tell which help is requested.
	const (
	// RootCommandHelpTemplate identifies the help for the root command.
	RootCommandHelpTemplate = "root"
	// CommandHelpTemplate identifies the help for a command.
	CommandHelpTemplate = "command"
	// SubcommandHelpTemplate identifies the help for a command with subcommands.
	SubcommandHelpTemplate = "subcommand"
	// FishCompletionTemplate is not used.
	FishCompletionTemplate = "fish"
	)

The README line "Replacing cli.HelpPrinter works as usual" could mention that:

cli/README.md

Lines 42 to 48 in 04c7fd4

	- `RootCommandHelpTemplate`, `CommandHelpTemplate`, `SubcommandHelpTemplate`
	and `FishCompletionTemplate` are constants;
	- if the default help printer is used with a custom template (such as
	`CustomRootCommandHelpTemplate` or `CustomHelpTemplate`), it panics;
	- custom template functions other than `wrap` and `wrapAt` are ignored.
	Replacing `cli.HelpPrinter` works as usual.

2. The errNoTemplate panic could include the command name, to make it easier to find which command has the custom template:

cli/help_notemplate.go

Lines 65 to 74 in 04c7fd4

	switch templ {
	case RootCommandHelpTemplate:
	h.root()
	case CommandHelpTemplate:
	h.command()
	case SubcommandHelpTemplate:
	h.subcommand()
	default:
	panic(errNoTemplate)
	}

@ldez since the build tag approach was your idea in #2277 (comment), it would be great to hear your thoughts before this is merged.

[kolyshkin]

@Juneezee thanks! Addressed both:

1. README now says that a custom HelpPrinter receives "root", "command" or "subcommand" as templ with the tag.
2. The panic now includes the command name, e.g. command "foo bar": custom templates are not supported when built with urfave_cli_no_template tag.

[kolyshkin]

@ldez ptal 🙏🏻

[ldez]

The implementation seem right, I tested it and it works as expected.

My only concern is about customization.

Replacing cli.HelpPrinter works as usual, except it receives "root",
"command" or "subcommand" as templ instead of the template text.

This doesn't allow the hack around cli.HelpPrinter to provide a custom help because the name of a subcommand can be identical for several commands.

But this is a detail, we can ignore it for now, at least, I think we cannot provide a better solution without breaking changes.

---

Off topic: I don't think GitHub is able to close automatically and issue when using the word Addresses inside the issue description, you should uses fixes or closes or resolves.

https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword

[kolyshkin]

The implementation seem right, I tested it and it works as expected.

My only concern is about customization.

Replacing cli.HelpPrinter works as usual, except it receives "root",
"command" or "subcommand" as templ instead of the template text.

This doesn't allow the hack around cli.HelpPrinter to provide a custom help because the name of a subcommand can be identical for several commands.

I think you are mixing things up here. The command (*Command) is still passed on in data, what we do not pass when the new build tag is set is the full template itself (instead of templates for root, command, subcommand we pass a simple string).

There is even a (weak) test, added by this PR, TestNoTemplate_CustomHelpPrinter, which checks data.(*Command).Name is as expected (for command only).

I have now added another test, TestNoTemplate_CustomHelpPrinterTempl, which checks the command name is actually passed (and also that root/command/subcommand works as documented).

Off topic: I don't think GitHub is able to close automatically and issue when using the word Addresses inside the issue description, you should uses fixes or closes or resolves.

Thanks, fixed (although I think @Juneezee manually linked the issue to this PR).

[ldez]

I think you are mixing things up here.

I missed that a command has a Root() method, so we can have the parent of the subcommand.

Not easy to use but it can work.