Skip to content

Commit cf87fc4

Browse files
spf13spf13
committed
Updating generator documentation and links
Merging the updated documentation from the user_guide into the cobra/README.md. Adding links as appropriate to both guides.
1 parent c97b7ec commit cf87fc4

File tree

3 files changed

+76
-82
lines changed

3 files changed

+76
-82
lines changed

‎README.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ have children commands and optionally run an action.
6666

6767
In the example above, 'server' is the command.
6868

69-
[More about cobra.Command](https://godoc.org/github.com/spf13/cobra#Command)
69+
[More about cobra.Command](https://pkg.go.dev/github.com/spf13/cobra#Command)
7070

7171
## Flags
7272

@@ -95,8 +95,12 @@ import "github.com/spf13/cobra"
9595
```
9696

9797
# Usage
98+
Cobra provides its own program that will create your application and add any
99+
commands you want. It's the easiest way to incorporate Cobra into your application.
98100

99-
See [User Guide](user_guide.md).
101+
For complete details on using the Cobra generator, please read [The Cobra Generator README](https://github.com/spf13/cobra/blob/master/cobra/README.md)
102+
103+
For complete details on using the Cobra library, please read the [The Cobra User Guide](user_guide.md).
100104

101105
# License
102106

‎cobra/README.md‎

Lines changed: 69 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -3,41 +3,78 @@
33
Cobra provides its own program that will create your application and add any
44
commands you want. It's the easiest way to incorporate Cobra into your application.
55

6-
In order to use the cobra command, compile it using the following command:
6+
Install the cobra generator with the command `go install github.com/spf13/cobra/cobra`.
7+
Go will automatically install it in your `$GOPATH/bin` directory which should be in your $PATH.
78

8-
go get github.com/spf13/cobra/cobra
9+
Once installed you should have the `cobra` command available. Confirm by typing `cobra` at a
10+
command line.
911

10-
This will create the cobra executable under your `$GOPATH/bin` directory.
12+
There are only two operations currently supported by Cobra generator:
1113

1214
### cobra init
1315

1416
The `cobra init [app]` command will create your initial application code
1517
for you. It is a very powerful application that will populate your program with
16-
the right structure so you can immediately enjoy all the benefits of Cobra. It
17-
will also automatically apply the license you specify to your application.
18+
the right structure so you can immediately enjoy all the benefits of Cobra.
19+
It can also apply the license you specify to your application.
1820

19-
Cobra init is pretty smart. You can either run it in your current application directory
20-
or you can specify a relative path to an existing project. If the directory does not exist, it will be created for you.
21+
With the introduction of Go modules, the Cobra generator has been simplified to
22+
take advantage of modules. The Cobra generator works from within a Go module.
2123

22-
Updates to the Cobra generator have now decoupled it from the GOPATH.
23-
As such `--pkg-name` is required.
24+
#### Initalizing a module
2425

25-
**Note:** init will no longer fail on non-empty directories.
26+
__If you already have a module, skip this step.__
2627

28+
If you want to initialize a new Go module:
29+
30+
1. Create a new directory
31+
2. `cd` into that directory
32+
3. run `go mod init <MODNAME>`
33+
34+
e.g.
2735
```
28-
mkdir -p newApp && cd newApp
29-
cobra init --pkg-name github.com/spf13/newApp
36+
cd $HOME/code
37+
mkdir myapp
38+
cd myapp
39+
go mod init github.com/spf13/myapp
3040
```
3141

32-
or
42+
#### Initalizing an Cobra CLI application
43+
44+
From within a Go module run `cobra init`. This will create a new barebones project
45+
for you to edit.
46+
47+
You should be able to run you new application immediately. Try it with
48+
`go run main.go`.
49+
50+
You will want to open up and edit 'cmd/root.go' and provide your own description and logic.
3351

52+
e.g.
3453
```
35-
cobra init --pkg-name github.com/spf13/newApp path/to/newApp
54+
cd $HOME/code/myapp
55+
cobra init
56+
go run main.go
3657
```
3758

38-
### cobra add
59+
Cobra init can also be run from a subdirectory such as how the [cobra generator itself is organized](https://github.com/spf13/cobra).
60+
This is useful if you want to keep your application code separate from your library code.
61+
62+
#### Optional flags:
63+
You can provide it your author name with the `--author` flag.
64+
e.g. `cobra init --author "Steve Francia spf@spf13.com"`
65+
66+
You can provide a license to use with `--license`
67+
e.g. `cobra init --license apache`
68+
69+
Use the `--viper` flag to automatically setup [viper](https://github.com/spf13/viper)
70+
71+
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.
72+
73+
### Add commands to a project
74+
75+
Once a cobra application is initialized you can continue to use cobra generator to
76+
add additional commands to your application. The command to do this is `cobra add`.
3977

40-
Once an application is initialized, Cobra can create additional commands for you.
4178
Let's say you created an app and you wanted the following commands for it:
4279

4380
* app serve
@@ -52,6 +89,14 @@ cobra add config
5289
cobra add create -p 'configCmd'
5390
```
5491

92+
`cobra add` supports all the same optional flags as `cobra init` does mentioned above.
93+
94+
You'll notice that this final command has a `-p` flag. This is used to assign a
95+
parent command to the newly added command. In this case, we want to assign the
96+
"create" command to the "config" command. All commands have a default parent of rootCmd if not specified.
97+
98+
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.
99+
55100
*Note: Use camelCase (not snake_case/kebab-case) for command names.
56101
Otherwise, you will encounter errors.
57102
For example, `cobra add add-user` is incorrect, but `cobra add addUser` is valid.*
@@ -62,18 +107,22 @@ the following:
62107
```
63108
▾ app/
64109
▾ cmd/
65-
serve.go
66110
config.go
67111
create.go
112+
serve.go
113+
root.go
68114
main.go
69115
```
70116

71117
At this point you can run `go run main.go` and it would run your app. `go run
72118
main.go serve`, `go run main.go config`, `go run main.go config create` along
73119
with `go run main.go help serve`, etc. would all work.
74120

75-
Obviously you haven't added your own code to these yet. The commands are ready
76-
for you to give them their tasks. Have fun!
121+
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.
122+
123+
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).
124+
125+
Have fun!
77126

78127
### Configuring the cobra generator
79128

@@ -86,6 +135,7 @@ An example ~/.cobra.yaml file:
86135
```yaml
87136
author: Steve Francia <spf@spf13.com>
88137
license: MIT
138+
viper: true
89139
```
90140
91141
You can also use built-in licenses. For example, **GPLv2**, **GPLv3**, **LGPL**,

‎user_guide.md‎

Lines changed: 1 addition & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -32,67 +32,7 @@ func main() {
3232
Cobra provides its own program that will create your application and add any
3333
commands you want. It's the easiest way to incorporate Cobra into your application.
3434

35-
Install the cobra generator with the command `go install github.com/spf13/cobra/cobra`.
36-
Go will automatically install it in your $GOPATH/bin directory which should be in your $PATH.
37-
38-
Once installed you should have the `cobra` command available. Confirm by typing `cobra` at a
39-
command line.
40-
41-
There are only two operations currently supported by Cobra generator.
42-
43-
### 1. Initializing a new project
44-
45-
The Cobra generator works from within a Go module.
46-
47-
If you haven't yet setup your project as a Go module:
48-
49-
1. Create a new directory
50-
2. `cd` into that directory
51-
3. run `go mod init <MODNAME>`
52-
53-
From within a Go module run `cobra init`. This will create a new barebones project
54-
for you to edit.
55-
56-
You should be able to run you new application immediately. Try it with
57-
`go run main.go`.
58-
59-
You will want to open up and edit 'cmd/root.go' and provide your own description and logic.
60-
61-
#### Optional flags:
62-
You can provide it your author name with the `--author` flag.
63-
e.g. `cobra init --author "Steve Francia spf@spf13.com"`
64-
65-
You can provide a license to use with `--license`
66-
e.g. `cobra init --license apache`
67-
68-
Use the `--viper` flag to automatically setup [viper](https://github.com/spf13/viper)
69-
70-
Viper is a companion to Cobra intended to provide easy handling of environment variables and config files
71-
and seamlessly connecting them to the application flags.
72-
73-
### 2. Add a command to a project
74-
75-
Once a cobra application is initialized you can continue to use cobra generator to
76-
add additional commands to your application. The command to do this is `cobra add`.
77-
78-
As an example, if I was designing a todo application I would want to have my base `todo` command list the items.
79-
I would then add additional commands to display, create, mark complete and delete items.
80-
81-
To add a command to an existing application, make sure you are in the directory with the main.go file and run:
82-
`cobra add <cmdname>`.
83-
84-
#### Optional flags:
85-
86-
`cobra add` supports all the same optional flags as `cobra init` does.
87-
88-
Additionally you can provide a parent command for your new command. This defaults to rootCmd if not provided.
89-
If you want to place your command under a different command, just provide the name of the command.
90-
91-
A todo is a bit too simple to really need a sub sub command. So let's use git as an example.
92-
93-
If I wanted to create a new git stash command I would do the following:
94-
`cobra add stash`
95-
`cobra add pop --parent=stash`
35+
For complete details on using the Cobra generator, please read [The Cobra Generator README](https://github.com/spf13/cobra/blob/master/cobra/README.md)
9636

9737
## Using the Cobra Library
9838

0 commit comments

Comments
 (0)