Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Wrap CLI --help output to terminal width #28751
- What I did
Line wrapped the output of
- How I did it
spf13/pflag#105 contains the bulk of the functional changes by enhancing the pflag package with a new function to provide a wrapped version of the help for a FlagsSet. With that in place here we just adjust the templates used for
This temporarily vendors pflag from my fork until the fate of spf13/pflag#105 is known, we should hold off merging this PR until it is merged.
- How to verify it
- Description for the changelog
Output of docker CLI --help is now wrapped to the terminal width.
Nov 23, 2016
With this change; on a 80-chars console;
And on a 60-chars console;
And without this change;
Note that even with this change, "resizing" the console doesn't re-wrap the output, but at least it's useful when asking the CLI to print
I also noticed that 1.13 now outputs
I'm not really a fan of this change. If you want to view help text without wrapping use
--help | less and scroll over.
for the Cobra changes
There are no Cobra changes, just pflag, which we haven't forked until this PR.
Can we do the same for
I'm not aware of any terminal and CLI app pairing which would correctly semantically (i.e. correctly indenting continuation lines as this PR does) re-wrap the output of an already completed command in the terminal scroll back. I think it simply isn't possible given how these things work (although I'd be happy to be proven wrong!)
I'll update spf13/pflag#105 to drop the commented out code and update this PR with the result.
I can have a look at
referenced this pull request
Jan 5, 2017
@dnephin, I think the point is that people do want wrapping, but the naive approach taken by many (most?) terminal emulators (which is basically equivalent to blindly inserting a
This PR improves this by wrapping in a way which understands that wrapping is best done on whitespace but also understands the flag name and its help text are distinct and tries to indent the wrapping of the latter in a sensible and readable way.
I think almost every CLI command I've ever come across does something like this (for the better IMHO) although most of them hardcode wrapping at 80 columns, I think, rather than trying to be more dynamic like I've done here.
Updated spf13/pflag#105 to remove the commented code and pushed an updated vendoring here.
I'm considering whether I should rebase since this is an older PR. It looks like the merge is currently clean so unless one of the CI tests fails or someone asks me to do otherwise I'll probably not bother.
CI failures look to be real, both are:
looks like a test depends on the specific output formatting. I'll take a look.
I dropped the problematic test since this output is now expected to be wrapped (that's the point!).
Unfortunately that's where the trail ends. It seems like the thinking has changed in the intervening and AIUI the short descriptions are proving to be too terse in practice (in particular we'd like to include longer lists of the possible values etc which would easily blow 80 columns). Hence wrapping is now desired.
@thaJeztah if I'm going to squash then I think it would make sense to squash
Or perhaps folks would prefer the revendoring to spf13/pflag#master to be in