Skip to content

Commit

Permalink
feat: ✨ improve help message readablity
Browse files Browse the repository at this point in the history
  • Loading branch information
@Equationzhao
Equationzhao committed Jun 1, 2024
1 parent aa2da06 commit 36683cc
Show file tree
Hide file tree
Showing 5 changed files with 172 additions and 36 deletions.
4 changes: 2 additions & 2 deletions internal/cli/display.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -382,7 +382,7 @@ var displayFlag = []cli.Flag{
},
&cli.BoolFlag{
Name: "classic",
Usage: "Enable classic mode (no colors or icons)",
Usage: "enable classic mode (no colors or icons)",
DisableDefaultText: true,
Action: func(context *cli.Context, b bool) error {
if b {
Expand Down Expand Up @@ -415,7 +415,7 @@ var displayFlag = []cli.Flag{
Name: "ft",
Aliases: []string{"file-type"},
DisableDefaultText: true,
Usage: "likewise, except do not append '*'",
Usage: "like classify, except do not append '*'",
Category: "DISPLAY",
},
&cli.UintFlag{
Expand Down
2 changes: 1 addition & 1 deletion internal/cli/filtering.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ var filteringFlag = []cli.Flag{
&cli.UintFlag{
Name: "n",
Aliases: []string{"limitN", "limit", "topN", "top"},
Usage: "Limit display to a max of n items (n <=0 means unlimited)",
Usage: "limit display to a max of n items (n <=0 means unlimited)",
Value: 0,
DefaultText: "unlimited",
Category: "FILTERING",
Expand Down
194 changes: 165 additions & 29 deletions internal/cli/g.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,16 +71,10 @@ var G *cli.App
func init() {
itemFilterFunc = append(itemFilterFunc, &filter.RemoveHidden)
G = &cli.App{
Name: "g",
Usage: "a powerful ls",
UsageText: "g [options] [path]",
Version: Version,
Authors: []*cli.Author{
{
Name: "Equationzhao",
Email: "equationzhao@foxmail.com",
},
},
Name: "g",
Usage: "a powerful ls",
UsageText: "g [options] [path]",
Version: Version,
SliceFlagSeparator: ",",
HideHelpCommand: true,
Suggest: true,
Expand Down Expand Up @@ -253,35 +247,177 @@ func initHelpTemp() {
configDir = filepath.Join("$UserConfigDir", "g")
}
cli.AppHelpTemplate = fmt.Sprintf(
`NAME:
{{template "helpNameTemplate" .}}
USAGE:
{{if .UsageText}}{{wrap .UsageText 3}}{{else}}{{.HelpName}} {{if .VisibleFlags}}[global options]{{end}}{{if .Commands}} command [command options]{{end}} {{if .ArgsUsage}}{{.ArgsUsage}}{{else}}[arguments...]{{end}}{{end}}{{if .Version}}{{if not .HideVersion}}
`USAGE:
g [options] [files...]
VERSION:
{{.Version}}{{end}}{{end}}{{if .Description}}
DESCRIPTION:
{{template "descriptionTemplate" .}}{{end}}
{{.Version}}
CONFIG:
Configuration: %s
See More at: g.equationzhao.space
{{- if len .Authors}}
AUTHOR{{template "authorsTemplate" .}}{{end}}{{if .VisibleCommands}}
COMMANDS:{{template "visibleCommandCategoryTemplate" .}}{{end}}{{if .VisibleFlagCategories}}
GLOBAL OPTIONS:{{template "visibleFlagCategoryTemplate" .}}{{else if .VisibleFlags}}
GLOBAL OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}
`, filepath.Join(configDir, "g.yaml"),
%s
`, filepath.Join(configDir, "g.yaml"), optionsHelp,
)
}

const optionsHelp = `GLOBAL OPTIONS
--bug report bug
--duplicate, --dup show duplicate files
--no-config do not load config file
--no-path-transform, --np By default, .../a/b/c will be transformed to ../../a/b/c, and ~ will be replaced by homedir,
using this flag to disable this feature
--si use powers of 1000 for size format(default: false)
META
--check-new-version check if there's new release
--help, -h, -? show help
--version, -v print the version
DISPLAY
-# print entry Number for each entry
--CSV, --csv output in csv format
--TSV, --tsv output in tsv format
--byline, -1, --oneline print by line
--classic enable classic mode(no colors or icons)
--color WHEN/LEVEL set terminal colors [always|auto|never][basic|256|24bit](default: auto)
--colorless, --no-color without color
--depth NUM limit recursive/tree depth, negative -> infinity(default: infinity)
--format FORMAT across -x, commas -m, horizontal -x, long -l, single-column -1,
verbose -l, vertical -C, table -tb, markdown -md, csv -csv, tsv -tsv, json -j, tree -T(default: C)
--file-type like --classify, except do not append '*'
--md, --markdown output in markdown-table format
--tb, --table output in table format
--table-style STYLE set table style [ascii(default)/unicode]
--term-width COLS set screen width (default: auto)
--theme path/to/theme apply theme path/to/theme
--tree-style STYLE set tree style [ascii/unicode(default)/rectangle]
--zero, -0 end each output line with NUL, not newline
-C, --vertical list entries by columns(default)
-F, --classify append indicator (one of */=@|) to entries
-R, --recurse recurse into directories
-T, --tree recursively list in tree
-d, --directory, list directories themselves, not their contents
-j, --json output in json format
-m, --comma fill width with a comma separated list of entries
-x, --col, --across, --horizontal list entries by lines instead of by columns
FILTERING
--after TIME show items which was modified/access/created after given time, see --before
--before TIME show items which was modified/access/created before given time, the time field is determined by --time-type,
the time will be parsed using format:
MM-dd, MM-dd HH:mm, HH:mm, YYYY-MM-dd, YYYY-MM-dd HH:mm, and the format set by --time-style
--ext value show file which has target ext, eg: --ext=go,java
--git-ignore hide git ignored file/dir [if git is installed]
--no-dir, --file do not show directory
--no-ext value show file which doesn't have target ext
--only-mime value only show file with given mime type
--show-only-hidden, --hidden show only hidden files(overridden by --show-hidden/-a/-A)
-A, --almost-all do not list implied . and ..
-B, --ignore-backups do not list implied entries ending with ~
-D, --dir, --only-dir show directory only
-I GLOBS, --ignore GLOBS ignore Glob patterns
-M GLOBS, --match GLOBS match Glob patterns
-a, --show-hidden show hidden files
-n NUM, --limit NUM limit display to a max of n items(n <=0 means unlimited)(default: unlimited)
INDEX
--disable-index, --no-update disable updating index
--fuzzy, -f fuzzy search
--list-index, list index
--rebuild-index rebuild index
--remove-current-path remove current path from index
--remove-index value, --rm value remove paths from index
--remove-invalid-path, --rip remove invalid paths from index
SHELL
--init value show the init script for shell, support zsh, bash, fish, powershell, nushell
SORTING
--sort SORT_FIELD sort by field, default: ascending and case-insensitive,
available fields: nature(default),none(nosort),
name,.name(sorts by name without a leading dot),
size,time,owner,group,extension,inode,width,mime.
append '-descend' to sort descending
field beginning with an Uppercase letter is case-sensitive
--dir-first, --group-directories-first list directories before other files
--sort-by-mime sort by mimetype
--sort-by-mime-descend sort by mimetype, descending
--sort-by-mime-parent sort by mimetype parent
--sort-by-mime-parent-descend sort by mimetype parent
--sort-reverse, --reverse, -r reverse the order of the sort
--versionsort, --sort-by-version sort by version numbers, ascending(default: false)
--width sort by entry name width
-S, --sort-by-size, --sizesort sort by file size, largest first(descending)
-U, --nosort, --no-sort do not sort; list entries in directory order.
-X, --sort-by-ext sort alphabetically by entry extension
VIEW
--access, --ac, --accessed accessed time
--all show all info/use a long listing format
--birth birth time[macOS only]
--block, --blocks show block size
--charset show charset of text file in mime type field
--checksum, --cs show checksum of file with algorithm, see --checksum-algorithm
--checksum-algorithm value, --ca value show checksum of file with algorithm:
md5, sha1, sha224, sha256, sha384, sha512, crc32(default: sha1)
--create, --cr, --created created time
--dereference dereference symbolic links
--detect-size value set exact size for mimetype detection
eg:1M/nolimit/infinity(default: 1M)
--extended, -@ list each file's extended attributes and sizes in long listing
--footer add a footer row
--fp, --full-path, --fullpath show full path
--full-time like -all/l --time-style=full-iso
--gid show gid instead of groupname [sid in windows]
--git, --git-status show git status [if git is installed]
--git-repo-branch, --branch list root of git-tree branch [if git is installed]
--git-repo-status, --repo-status list root of git-tree status [if git is installed]
--group show group
--header, --title add a header row
--hyperlink value attach hyperlink to filenames [auto|always|never](default: auto)
--icon, --icons show icon
--inode, -i show inode[linux/darwin only]
--lh, --human-readable show human readable size
--mime, --mime-type, --mimetype show mime file type
--mime-parent, --mime-parent-type show mime parent type
--modify, --mod, --modified modified time
--mounts show mount details
--no-dereference do not follow symbolic links
--no-icon, --noicon, --ni disable icon(always override --icon)
--no-total-size disable total size(always override --total-size)
--numeric, --numeric-uid-gid list numeric user and group IDs instead of name [sid in windows]
--octal-perm, --octal-permission list each file's permission in octal format
--owner, --author show owner
--perm, --permission show permission
--recursive-size show recursive size of dir, only work with --size
--relative-to value show relative path to the given path (default: current directory)
--rt, --relative-time show relative time
--size show file/dir size
--size-unit value, --block-size value size unit: bit, b, k, m, g, t, auto
--smart-group only show group if it has a different name from owner
--statistic show statistic info
--time show time
--time-style TIME_TYPE time/date format with -l,
valid TIME_TYPE are :
default, iso, long-iso, full-iso, locale,
and custom +FORMAT like date(1).
(default: +%%d.%%b'%%y %%H:%%M ,like 02.Jan'06 15:04)
--time-type value time type, mod(default), create, access, all, birth[macOS only]
--total-size show total size
--uid show uid instead of username [sid in windows]
-G, --no-group in a long listing, don't print group names
-H, --link list each file's number of hard links
-N, --literal print entry names without quoting
-O, --no-owner in a long listing, don't print owner names
-Q, --quote-name enclose entry names in double quotes(overridden by --literal)
-g like -all, but do not list owner
-l, --long use a long listing format
-o like -all, but do not list group information`

func initVersionHelpFlags() {
cli.VersionPrinter = func(cCtx *cli.Context) {
_, _ = fmt.Fprintf(os.Stdout, `💡 g - a powerful ls
Expand Down
2 changes: 1 addition & 1 deletion internal/cli/sort.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,7 @@ var sortingFlags = []cli.Flag{
&cli.BoolFlag{
Name: "df",
Aliases: []string{"dir-first", "group-directories-first"},
Usage: "List directories before other files",
Usage: "list directories before other files",
DisableDefaultText: true,
Action: func(context *cli.Context, b bool) error {
if b {
Expand Down
6 changes: 3 additions & 3 deletions internal/cli/view.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,7 @@ var viewFlag = []cli.Flag{
&cli.StringFlag{
Name: "time-style",
Usage: `time/date format with -l,
Valid timestamp styles are default, iso, long-iso, full-iso, locale,
valid timestamp styles are default, iso, long-iso, full-iso, locale,
custom +FORMAT like date(1).
(default: +%d.%b'%y %H:%M ,like 02.Jan'06 15:04)`,
EnvVars: []string{"TIME_STYLE"},
Expand Down Expand Up @@ -267,7 +267,7 @@ var viewFlag = []cli.Flag{
&cli.BoolFlag{
Name: "numeric",
Aliases: []string{"numeric-uid-gid"},
Usage: " List numeric user and group IDs instead of name [sid in windows]",
Usage: "list numeric user and group IDs instead of name [sid in windows]",
DisableDefaultText: true,
Action: func(context *cli.Context, b bool) error {
if b {
Expand Down Expand Up @@ -646,7 +646,7 @@ var viewFlag = []cli.Flag{
},
&cli.StringFlag{
Name: "hyperlink",
Usage: "Attach hyperlink to filenames [auto|always|never]",
Usage: "attach hyperlink to filenames [auto|always|never]",
Category: "VIEW",
DefaultText: "auto",
Action: func(context *cli.Context, s string) error {
Expand Down

0 comments on commit 36683cc

Please sign in to comment.