Repository navigation
feat: fields for VisibleFlags name/alias and Usage #2016
Description
Checklist
- Are you running the latest v3 release? The list of releases is here.
- Did you check the manual for your release? The v3 manual is here.
- Did you perform a search about this feature? Here's the GitHub guide about searching.
What problem does this solve?
When customizing the AppHelpTemplate, it would be preferable to change how the first and second column are formatted, ie - the description of the flag on a separate line, tabbed out, and restricted to a width of 80 characters. In the current state of .VisiableFlags, there is no way to separate the two columns beyond a slice of strings. Each flag has its name and description (.Usage) clumped together as a single string which is difficult or nearly impossible to parse using go's template actions.
Solution description
The two columns should be exposed as separate fields.
For the first column, .Name does not truly suffice as it both contains the long Name, Aliases, and has the input values marked by the respective name or alias. A fitting name for this could be .Names or .Flags.
For the second column, something equivalent to .Usage is sufficient.
Describe alternatives you've considered
I've tried to loop through .VisiableFlags and coerce each flag to its original type such as StingFlag and then create a custom template to load which would effectively recreate the first column. But this served to be very tedious, and admittedly, I'm not good enough in golang to do this with ease.
I also thought of potentially hand writing this part of the help template. But this deemed tedious as well and goes against the spirit of urfave/cli as it does not autogenerate based on the visible flags.
Activity
dearchap commentedon Nov 28, 2024
@midirhee12 you could cast the Flag to a DocGenerationFlag to extract further information if you'd like. Admittingly its not elegant but might work ?
midischwarz12 commentedon Nov 28, 2024
How would this be casted and used within the
AppHelpTemplate?midischwarz12 commentedon Nov 29, 2024
@dearchap From what I know, you would have to map the function into the template before being evaluated. Is there a way this is being exposed?
midischwarz12 commentedon Nov 29, 2024
Either way, even if it is possible, I think there should be a more straightforward and clean way to access this since formatting the templates could be quite frequent among users.
midischwarz12 commentedon Dec 1, 2024
@dearchap Actually, on second thought. Is it possible to expose
.VisibleFlagTemplateand such instead?dearchap commentedon Dec 1, 2024
@midirhee12 yes. you want to make a PR ?
IslamElsayed commentedon Sep 24, 2026
@dearchap I'd like to pick this up, but the thread ends on two different proposals and I want to build the one you said yes to rather than guess.
Reading it back, your "yes. you want to make a PR?" answers @midischwarz12's "Is it possible to expose
.VisibleFlagTemplateand such instead?" — not the original ask for separate name/alias/usage fields. So I'd implement the exposure, not new fields. Please correct me if I have that backwards.Why the current state blocks people. The top-level templates are exported and overridable —
RootCommandHelpTemplate,CommandHelpTemplate,SubcommandHelpTemplate,FishCompletionTemplate. The pieces they compose from are not:So someone can restructure the help layout wholesale, but cannot change how the flag list itself renders, because that
{{wrap $e.String 6}}lives in an unexported var they can neither override nor reference. That is the actual wall, and it explains why the workaround you suggested didn't land — there is nowhere to put it.Why exposure alone may be the whole fix.
text/templateresolves methods against the dynamic value, not the static one. So inside{{range .VisibleFlags}}, even though the element's static type isFlag, a user-supplied template can call{{$e.GetUsage}}and{{$e.Names}}directly, since the built-in flags implementDocGenerationFlag. If that holds, this needs no new interface method, no funcMap helper and no wrapper type — just exporting the vars. I'd pin it with a test rather than assert it, since a flag type that doesn't implementDocGenerationFlagwould fail at execution time instead of compile time, and that failure mode is worth a documented note either way.Three questions before I write anything:
visibleFlagTemplate,visiblePersistentFlagTemplate,visibleFlagCategoryTemplate— or the whole set includingvisibleCommandTemplate,visibleCommandCategoryTemplate,versionTemplateandcopyrightTemplate? Exporting all seven is more consistent; exporting three keeps the new surface to what was actually asked for. I lean to the three.make v3approvefor the godoc surface diff, and is adding exported vars acceptable mid-v3, or does it need to wait for a version boundary? That is the part most likely to make this a no, so I'd rather hear it now.@midischwarz12 you were the one asked to open the PR — are you still planning to? Happy to leave it with you if so.
Disclosure: I use AI assistance when working on patches, and I check and test everything before submitting.