readme.md
1# complete
2
3A tool for bash writing bash completion in go, and bash completion for the go command line.
4
5[](https://travis-ci.org/posener/complete)
6[](https://codecov.io/gh/posener/complete)
7[](http://godoc.org/github.com/posener/complete)
8[](https://goreportcard.com/report/github.com/posener/complete)
9
10Writing bash completion scripts is a hard work. This package provides an easy way
11to create bash completion scripts for any command, and also an easy way to install/uninstall
12the completion of the command.
13
14## go command bash completion
15
16In [gocomplete](./gocomplete) there is an example for bash completion for the `go` command line.
17
18This is an example that uses the `complete` package on the `go` command - the `complete` package
19can also be used to implement any completions, see [Usage](#usage).
20
21### Install
22
231. Type in your shell:
24```
25go get -u github.com/posener/complete/gocomplete
26gocomplete -install
27```
28
292. Restart your shell
30
31Uninstall by `gocomplete -uninstall`
32
33### Features
34
35- Complete `go` command, including sub commands and all flags.
36- Complete packages names or `.go` files when necessary.
37- Complete test names after `-run` flag.
38
39## complete package
40
41Supported shells:
42
43- [x] bash
44- [x] zsh
45- [x] fish
46
47### Usage
48
49Assuming you have program called `run` and you want to have bash completion
50for it, meaning, if you type `run` then space, then press the `Tab` key,
51the shell will suggest relevant complete options.
52
53In that case, we will create a program called `runcomplete`, a go program,
54with a `func main()` and so, that will make the completion of the `run`
55program. Once the `runcomplete` will be in a binary form, we could
56`runcomplete -install` and that will add to our shell all the bash completion
57options for `run`.
58
59So here it is:
60
61```go
62import "github.com/posener/complete"
63
64func main() {
65
66 // create a Command object, that represents the command we want
67 // to complete.
68 run := complete.Command{
69
70 // Sub defines a list of sub commands of the program,
71 // this is recursive, since every command is of type command also.
72 Sub: complete.Commands{
73
74 // add a build sub command
75 "build": complete.Command {
76
77 // define flags of the build sub command
78 Flags: complete.Flags{
79 // build sub command has a flag '-cpus', which
80 // expects number of cpus after it. in that case
81 // anything could complete this flag.
82 "-cpus": complete.PredictAnything,
83 },
84 },
85 },
86
87 // define flags of the 'run' main command
88 Flags: complete.Flags{
89 // a flag -o, which expects a file ending with .out after
90 // it, the tab completion will auto complete for files matching
91 // the given pattern.
92 "-o": complete.PredictFiles("*.out"),
93 },
94
95 // define global flags of the 'run' main command
96 // those will show up also when a sub command was entered in the
97 // command line
98 GlobalFlags: complete.Flags{
99
100 // a flag '-h' which does not expects anything after it
101 "-h": complete.PredictNothing,
102 },
103 }
104
105 // run the command completion, as part of the main() function.
106 // this triggers the autocompletion when needed.
107 // name must be exactly as the binary that we want to complete.
108 complete.New("run", run).Run()
109}
110```
111
112### Self completing program
113
114In case that the program that we want to complete is written in go we
115can make it self completing.
116
117Here is an [example](./example/self/main.go)
118
){kind=link}
){kind=link}
){kind=link}