2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-14 06:42:33 +00:00
clap/examples/git.md
Ed Page 36bc641648 fix(help): Remove extraneous text from built-ins
This is an intermediate solution for .  As there were no agreeed
upon goals, I went with what I felt read well and that I saw commonly
used on non-clap commands.

- "information" isn't really a necessary word.
- I originally favored `Print this help` but realied that doesn't read
  correctly in completions.
- Besides being shorter, the reason for the flipped short/long hint is
  it gives people the context they need for scanning, emphasizing
  "summary" and "more".

Fixes 
2023-01-03 11:02:26 -06:00

2.5 KiB

Git is an example of several common subcommand patterns.

Help:

$ git
? failed
A fictional versioning CLI

Usage: git[EXE] <COMMAND>

Commands:
  clone  Clones repos
  diff   Compare two commits
  push   pushes things
  add    adds things
  stash  
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

$ git help
A fictional versioning CLI

Usage: git[EXE] <COMMAND>

Commands:
  clone  Clones repos
  diff   Compare two commits
  push   pushes things
  add    adds things
  stash  
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

$ git help add
adds things

Usage: git[EXE] add <PATH>...

Arguments:
  <PATH>...  Stuff to add

Options:
  -h, --help  Print help

A basic argument:

$ git add
? failed
adds things

Usage: git[EXE] add <PATH>...

Arguments:
  <PATH>...  Stuff to add

Options:
  -h, --help  Print help

$ git add Cargo.toml Cargo.lock
Adding ["Cargo.toml", "Cargo.lock"]

Default subcommand:

$ git stash -h
Usage: git[EXE] stash [OPTIONS]
       git[EXE] stash <COMMAND>

Commands:
  push   
  pop    
  apply  
  help   Print this message or the help of the given subcommand(s)

Options:
  -m, --message <MESSAGE>  
  -h, --help               Print help

$ git stash push -h
Usage: git[EXE] stash push [OPTIONS]

Options:
  -m, --message <MESSAGE>  
  -h, --help               Print help

$ git stash pop -h
Usage: git[EXE] stash pop [STASH]

Arguments:
  [STASH]  

Options:
  -h, --help  Print help

$ git stash -m "Prototype"
Pushing Some("Prototype")

$ git stash pop
Popping None

$ git stash push -m "Prototype"
Pushing Some("Prototype")

$ git stash pop
Popping None

External subcommands:

$ git custom-tool arg1 --foo bar
Calling out to "custom-tool" with ["arg1", "--foo", "bar"]

Last argument:

$ git diff --help
Compare two commits

Usage: git[EXE] diff [OPTIONS] [COMMIT] [COMMIT] [-- <PATH>]

Arguments:
  [COMMIT]  
  [COMMIT]  
  [PATH]    

Options:
      --color[=<WHEN>]  [default: auto] [possible values: always, auto, never]
  -h, --help            Print help

$ git diff
Diffing stage..worktree  (color=auto)

$ git diff ./src
Diffing stage..worktree ./src (color=auto)

$ git diff HEAD ./src
Diffing HEAD..worktree ./src (color=auto)

$ git diff HEAD~~ -- HEAD
Diffing HEAD~~..worktree HEAD (color=auto)

$ git diff --color
Diffing stage..worktree  (color=always)

$ git diff --color=never
Diffing stage..worktree  (color=never)