diff --git a/README.md b/README.md index 9d942c7c..1ade1081 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ have children commands and optionally run an action. 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 @@ -95,8 +95,12 @@ import "github.com/spf13/cobra" ``` # 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 diff --git a/cobra/README.md b/cobra/README.md index dcaf0c5f..eed09c11 100644 --- a/cobra/README.md +++ b/cobra/README.md @@ -3,41 +3,78 @@ 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. -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 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 -the right structure so you can immediately enjoy all the benefits of Cobra. It -will also automatically apply the license you specify to your application. +the right structure so you can immediately enjoy all the benefits of Cobra. +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 -or you can specify a relative path to an existing project. If the directory does not exist, it will be created for you. +With the introduction of Go modules, the Cobra generator has been simplified to +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. -As such `--pkg-name` is required. +#### Initalizing a module -**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 ` + +e.g. ``` -mkdir -p newApp && cd newApp -cobra init --pkg-name github.com/spf13/newApp +cd $HOME/code +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: * app serve @@ -52,6 +89,14 @@ cobra add config 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. Otherwise, you will encounter errors. For example, `cobra add add-user` is incorrect, but `cobra add addUser` is valid.* @@ -62,9 +107,10 @@ the following: ``` ▾ app/ ▾ cmd/ - serve.go config.go create.go + serve.go + root.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 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 -for you to give them their tasks. Have fun! +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 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 @@ -86,6 +135,7 @@ An example ~/.cobra.yaml file: ```yaml author: Steve Francia license: MIT +viper: true ``` You can also use built-in licenses. For example, **GPLv2**, **GPLv3**, **LGPL**, diff --git a/user_guide.md b/user_guide.md index ad478890..923392b7 100644 --- a/user_guide.md +++ b/user_guide.md @@ -32,67 +32,7 @@ func main() { 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. -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. - -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 ` - -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 `. - -#### 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` +For complete details on using the Cobra generator, please read [The Cobra Generator README](https://github.com/spf13/cobra/blob/master/cobra/README.md) ## Using the Cobra Library