vinchent/cobra
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updating generator documentation and links

Browse Source 
Merging the updated documentation from the user_guide into the cobra/README.md.
Adding links as appropriate to both guides.
This commit is contained in:
Steve Francia
2021-07-02 10:58:34 -04:00
parent c97b7ece0b
commit cf87fc4e30
3 changed files with 76 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -66,7 +66,7 @@ have children commands and optionally run an action.
In the example above, 'server' is the command. In the example above, 'server' is the command.
[More about cobra.Command](https://godoc.org/github.com/spf13/cobra#Command) [More about cobra.Command](https://pkg.go.dev/github.com/spf13/cobra#Command)
## Flags ## Flags
@ -95,8 +95,12 @@ import "github.com/spf13/cobra"
``` ```
# Usage # Usage
Cobra provides its own program that will create your application and add any
commands you want. It's the easiest way to incorporate Cobra into your application.
See [User Guide](user_guide.md). For complete details on using the Cobra generator, please read [The Cobra Generator README](https://github.com/spf13/cobra/blob/master/cobra/README.md)
For complete details on using the Cobra library, please read the [The Cobra User Guide](user_guide.md).
# License # License

88
cobra/README.md
View File

@ -3,41 +3,78 @@
Cobra provides its own program that will create your application and add any Cobra provides its own program that will create your application and add any
commands you want. It's the easiest way to incorporate Cobra into your application. commands you want. It's the easiest way to incorporate Cobra into your application.
In order to use the cobra command, compile it using the following command: Install the cobra generator with the command `go install github.com/spf13/cobra/cobra`.
Go will automatically install it in your `$GOPATH/bin` directory which should be in your $PATH.
go get github.com/spf13/cobra/cobra Once installed you should have the `cobra` command available. Confirm by typing `cobra` at a
command line.
This will create the cobra executable under your `$GOPATH/bin` directory. There are only two operations currently supported by Cobra generator:
### cobra init ### cobra init
The `cobra init [app]` command will create your initial application code The `cobra init [app]` command will create your initial application code
for you. It is a very powerful application that will populate your program with for you. It is a very powerful application that will populate your program with
the right structure so you can immediately enjoy all the benefits of Cobra. It the right structure so you can immediately enjoy all the benefits of Cobra.
will also automatically apply the license you specify to your application. It can also apply the license you specify to your application.
Cobra init is pretty smart. You can either run it in your current application directory With the introduction of Go modules, the Cobra generator has been simplified to
or you can specify a relative path to an existing project. If the directory does not exist, it will be created for you. take advantage of modules. The Cobra generator works from within a Go module.
Updates to the Cobra generator have now decoupled it from the GOPATH. #### Initalizing a module
As such `--pkg-name` is required.
**Note:** init will no longer fail on non-empty directories. __If you already have a module, skip this step.__
If you want to initialize a new Go module:
1. Create a new directory
2. `cd` into that directory
3. run `go mod init <MODNAME>`
e.g.
``` ```
mkdir -p newApp && cd newApp cd $HOME/code
cobra init --pkg-name github.com/spf13/newApp mkdir myapp
cd myapp
go mod init github.com/spf13/myapp
``` ```
or #### Initalizing an Cobra CLI application
From within a Go module run `cobra init`. This will create a new barebones project
for you to edit.
You should be able to run you new application immediately. Try it with
`go run main.go`.
You will want to open up and edit 'cmd/root.go' and provide your own description and logic.
e.g.
``` ```
cobra init --pkg-name github.com/spf13/newApp path/to/newApp cd $HOME/code/myapp
cobra init
go run main.go
``` ```
### cobra add Cobra init can also be run from a subdirectory such as how the [cobra generator itself is organized](https://github.com/spf13/cobra).
This is useful if you want to keep your application code separate from your library code.
#### Optional flags:
You can provide it your author name with the `--author` flag.
e.g. `cobra init --author "Steve Francia spf@spf13.com"`
You can provide a license to use with `--license`
e.g. `cobra init --license apache`
Use the `--viper` flag to automatically setup [viper](https://github.com/spf13/viper)
Viper is a companion to Cobra intended to provide easy handling of environment variables and config files and seamlessly connecting them to the application flags.
### Add commands to a project
Once a cobra application is initialized you can continue to use cobra generator to
add additional commands to your application. The command to do this is `cobra add`.
Once an application is initialized, Cobra can create additional commands for you.
Let's say you created an app and you wanted the following commands for it: Let's say you created an app and you wanted the following commands for it:
* app serve * app serve
@ -52,6 +89,14 @@ cobra add config
cobra add create -p 'configCmd' cobra add create -p 'configCmd'
``` ```
`cobra add` supports all the same optional flags as `cobra init` does mentioned above.
You'll notice that this final command has a `-p` flag. This is used to assign a
parent command to the newly added command. In this case, we want to assign the
"create" command to the "config" command. All commands have a default parent of rootCmd if not specified.
By default `cobra` will append `Cmd` to the name provided and uses this to name for the internal variable name. When specifying a parent, be sure to match the variable name used in the code.
*Note: Use camelCase (not snake_case/kebab-case) for command names. *Note: Use camelCase (not snake_case/kebab-case) for command names.
Otherwise, you will encounter errors. Otherwise, you will encounter errors.
For example, `cobra add add-user` is incorrect, but `cobra add addUser` is valid.* For example, `cobra add add-user` is incorrect, but `cobra add addUser` is valid.*
@ -62,9 +107,10 @@ the following:
``` ```
▾ app/ ▾ app/
▾ cmd/ ▾ cmd/
serve.go
config.go config.go
create.go create.go
serve.go
root.go
main.go main.go
``` ```
@ -72,8 +118,11 @@ At this point you can run `go run main.go` and it would run your app. `go run
main.go serve`, `go run main.go config`, `go run main.go config create` along main.go serve`, `go run main.go config`, `go run main.go config create` along
with `go run main.go help serve`, etc. would all work. with `go run main.go help serve`, etc. would all work.
Obviously you haven't added your own code to these yet. The commands are ready You now have a basic Cobra-based application up and running. Next step is to edit the files in cmd and customize them for your application.
for you to give them their tasks. Have fun!
For complete details on using the Cobra library, please read the [The Cobra User Guide](https://github.com/spf13/cobra/blob/master/user_guide.md#using-the-cobra-library).
Have fun!
### Configuring the cobra generator ### Configuring the cobra generator
@ -86,6 +135,7 @@ An example ~/.cobra.yaml file:
```yaml ```yaml
author: Steve Francia <spf@spf13.com> author: Steve Francia <spf@spf13.com>
license: MIT license: MIT
viper: true
``` ```
You can also use built-in licenses. For example, **GPLv2**, **GPLv3**, **LGPL**, You can also use built-in licenses. For example, **GPLv2**, **GPLv3**, **LGPL**,

62
user_guide.md
View File

@ -32,67 +32,7 @@ func main() {
Cobra provides its own program that will create your application and add any Cobra provides its own program that will create your application and add any
commands you want. It's the easiest way to incorporate Cobra into your application. commands you want. It's the easiest way to incorporate Cobra into your application.
Install the cobra generator with the command `go install github.com/spf13/cobra/cobra`. For complete details on using the Cobra generator, please read [The Cobra Generator README](https://github.com/spf13/cobra/blob/master/cobra/README.md)
Go will automatically install it in your $GOPATH/bin directory which should be in your $PATH.
Once installed you should have the `cobra` command available. Confirm by typing `cobra` at a
command line.
There are only two operations currently supported by Cobra generator.
### 1. Initializing a new project
The Cobra generator works from within a Go module.
If you haven't yet setup your project as a Go module:
1. Create a new directory
2. `cd` into that directory
3. run `go mod init <MODNAME>`
From within a Go module run `cobra init`. This will create a new barebones project
for you to edit.
You should be able to run you new application immediately. Try it with
`go run main.go`.
You will want to open up and edit 'cmd/root.go' and provide your own description and logic.
#### Optional flags:
You can provide it your author name with the `--author` flag.
e.g. `cobra init --author "Steve Francia spf@spf13.com"`
You can provide a license to use with `--license`
e.g. `cobra init --license apache`
Use the `--viper` flag to automatically setup [viper](https://github.com/spf13/viper)
Viper is a companion to Cobra intended to provide easy handling of environment variables and config files
and seamlessly connecting them to the application flags.
### 2. Add a command to a project
Once a cobra application is initialized you can continue to use cobra generator to
add additional commands to your application. The command to do this is `cobra add`.
As an example, if I was designing a todo application I would want to have my base `todo` command list the items.
I would then add additional commands to display, create, mark complete and delete items.
To add a command to an existing application, make sure you are in the directory with the main.go file and run:
`cobra add <cmdname>`.
#### Optional flags:
`cobra add` supports all the same optional flags as `cobra init` does.
Additionally you can provide a parent command for your new command. This defaults to rootCmd if not provided.
If you want to place your command under a different command, just provide the name of the command.
A todo is a bit too simple to really need a sub sub command. So let's use git as an example.
If I wanted to create a new git stash command I would do the following:
`cobra add stash`
`cobra add pop --parent=stash`
## Using the Cobra Library ## Using the Cobra Library