--noTimes[=false]: Don't sync modification time of files
--pluralizeListTitles[=true]: Pluralize titles in lists using inflect
--preserveTaxonomyNames[=false]: Preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")
-s, --source="": filesystem path to read files relative from
--stepAnalysis=false: display memory and timing of different steps of the program
--uglyurls=false: if true, use /filename.html instead of /filename/
-v, --verbose=false: verbose output
-w, --watch=false: watch filesystem for changes and recreate as needed
--stepAnalysis[=false]: display memory and timing of different steps of the program
-t, --theme="": theme to use (located in /themes/THEMENAME/)
--uglyURLs[=false]: if true, use /filename.html instead of /filename/
-v, --verbose[=false]: verbose output
--verboseLog[=false]: verbose logging
-w, --watch[=false]: watch filesystem for changes and recreate as needed
### Defining your own usage
You can provide your own usage function or template for cobra to use.
You can provide your own usage function or template for Cobra to use.
The default usage function is
The default usage function is:
return func(c *Command) error {
```go
returnfunc(c*Command)error{
err:=tmpl(c.Out(),c.UsageTemplate(),c)
returnerr
}
}
```
Like help the function and template are over ridable through public methods.
Like help, the function and template are overridable through public methods:
command.SetUsageFunc(f func(*Command) error)
```go
command.SetUsageFunc(ffunc(*Command)error)
command.SetUsageTemplate(s string)
command.SetUsageTemplate(sstring)
```
## PreRun or PostRun Hooks
It is possible to run functions before or after the main `Run` function of your command. The `PersistentPreRun` and `PreRun` functions will be executed before `Run`. `PersistendPostRun` and `PostRun` will be executed after `Run`. The `Persistent*Run` functions will be inherrited by children if they do not declare their own. These function are run in the following order:
It is possible to run functions before or after the main `Run` function of your command. The `PersistentPreRun` and `PreRun` functions will be executed before `Run`. `PersistentPostRun` and `PostRun` will be executed after `Run`. The `Persistent*Run` functions will be inherrited by children if they do not declare their own. These function are run in the following order:
-`PersistentPreRun`
-`PreRun`
-`Run`
-`PostRun`
-`PersistenPostRun`
-`PersistentPostRun`
And example of two commands which use all of these features is below. When the subcommand in executed it will run the root command's `PersistentPreRun` but not the root command's `PersistentPostRun`
An example of two commands which use all of these features is below. When the subcommand is executed, it will run the root command's `PersistentPreRun` but not the root command's `PersistentPostRun`:
```go
packagemain
...
...
@@ -393,7 +685,7 @@ func main() {
varsubCmd=&cobra.Command{
Use:"sub [no options!]",
Short:"My subcommand",
Short:"My subcommand",
PreRun:func(cmd*cobra.Command,args[]string){
fmt.Printf("Inside subCmd PreRun with args: %v\n",args)
},
...
...
@@ -418,13 +710,55 @@ func main() {
}
```
## Alternative Error Handling
Cobra also has functions where the return signature is an error. This allows for errors to bubble up to the top, providing a way to handle the errors in one location. The current list of functions that return an error is:
* PersistentPreRunE
* PreRunE
* RunE
* PostRunE
* PersistentPostRunE
**Example Usage using RunE:**
```go
packagemain
import(
"errors"
"log"
"github.com/spf13/cobra"
)
funcmain(){
varrootCmd=&cobra.Command{
Use:"hugo",
Short:"Hugo is a very fast static site generator",
Long:`A Fast and Flexible Static Site Generator built with
love by spf13 and friends in Go.
Complete documentation is available at http://hugo.spf13.com`,
RunE:func(cmd*cobra.Command,args[]string)error{
// Do Stuff Here
returnerrors.New("some random error")
},
}
iferr:=rootCmd.Execute();err!=nil{
log.Fatal(err)
}
}
```
## Suggestions when "unknown command" happens
Cobra will print automatic suggestions when "unknown command" errors happen. This allows Cobra to behavior similarly to the `git` command when a typo happens. For example:
Cobra will print automatic suggestions when "unknown command" errors happen. This allows Cobra to behave similarly to the `git` command when a typo happens. For example:
```
$ hugo srever
unknown command "srever" for "hugo"
Error: unknown command "srever" for "hugo"
Did you mean this?
server
...
...
@@ -432,48 +766,54 @@ Did you mean this?
Run 'hugo --help' for usage.
```
Suggestions are automatic based on every subcommand registered and use an implementation of Levenshtein distance. Every registered command that matches a minimum distance of 2 (ignoring case) will be displayed as a suggestion.
Suggestions are automatic based on every subcommand registered and use an implementation of [Levenshtein distance](http://en.wikipedia.org/wiki/Levenshtein_distance). Every registered command that matches a minimum distance of 2 (ignoring case) will be displayed as a suggestion.
If you need to disable suggestions or tweak the string distance in your command, use:
command.DisableSuggestions = true
```go
command.DisableSuggestions=true
```
or
command.SuggestionsMinimumDistance = 1
```go
command.SuggestionsMinimumDistance=1
```
You can also explicitly set names for which a given command will be suggested using the `SuggestFor` attribute. This allows suggestions for strings that are not close in terms of string distance, but makes sense in your set of commands and for some which you don't want aliases. Example:
```
$ hugo delete
unknown command "delete" for "hugo"
$ kubectl remove
Error: unknown command "remove" for "kubectl"
Did you mean this?
remove
delete
Run 'hugo --help' for usage.
Run 'kubectl help' for usage.
```
## Generating markdown formatted documentation for your command
## Generating Markdown-formatted documentation for your command
Cobra can generate a markdown formatted document based on the subcommands, flags, etc. A simple example of how to do this for your command can be found in [Markdown Docs](md_docs.md)
Cobra can generate a Markdown-formatted document based on the subcommands, flags, etc. A simple example of how to do this for your command can be found in [Markdown Docs](doc/md_docs.md).
## Generating man pages for your command
Cobra can generate a man page based on the subcommands, flags, etc. A simple example of how to do this for your command can be found in [Man Docs](man_docs.md)
Cobra can generate a man page based on the subcommands, flags, etc. A simple example of how to do this for your command can be found in [Man Docs](doc/man_docs.md).
## Generating bash completions for your command
Cobra can generate a bash completions file. If you add more information to your command these completions can be amazingly powerful and flexible. Read more about [Bash Completions](bash_completions.md)
Cobra can generate a bash-completion file. If you add more information to your command, these completions can be amazingly powerful and flexible. Read more about it in [Bash Completions](bash_completions.md).
## Debugging
Cobra provides a ‘DebugFlags’ method on a command which when called will print
out everything Cobra knows about the flags for each command
Cobra provides a ‘DebugFlags’ method on a command which, when called, will print
out everything Cobra knows about the flags for each command.
### Example
command.DebugFlags()
```go
command.DebugFlags()
```
## Release Notes
***0.9.0** June 17, 2014
...
...
@@ -499,6 +839,12 @@ out everything Cobra knows about the flags for each command
***0.1.0** Sept 3, 2013
* Implement first draft
## Extensions
Libraries for extending Cobra:
*[cmdns](https://github.com/gosuri/cmdns): Enables name spacing a command's immediate children. It provides an alternative way to structure subcommands, similar to `heroku apps:create` and `ovrclk clusters:launch`.
## ToDo
* Launch proper documentation site
...
...
@@ -514,7 +860,9 @@ out everything Cobra knows about the flags for each command
Names in no particular order:
*[spf13](https://github.com/spf13)
*[spf13](https://github.com/spf13),
[eparis](https://github.com/eparis),
[bep](https://github.com/bep), and many more!
## License
...
...
@@ -522,4 +870,3 @@ Cobra is released under the Apache 2.0 license. See [LICENSE.txt](https://github
