3 A tool for bash writing bash completion in go, and bash completion for the go command line.
5 [![Build Status](https://travis-ci.org/posener/complete.svg?branch=master)](https://travis-ci.org/posener/complete)
6 [![codecov](https://codecov.io/gh/posener/complete/branch/master/graph/badge.svg)](https://codecov.io/gh/posener/complete)
7 [![golangci](https://golangci.com/badges/github.com/posener/complete.svg)](https://golangci.com/r/github.com/posener/complete)
8 [![GoDoc](https://godoc.org/github.com/posener/complete?status.svg)](http://godoc.org/github.com/posener/complete)
9 [![Go Report Card](https://goreportcard.com/badge/github.com/posener/complete)](https://goreportcard.com/report/github.com/posener/complete)
11 Writing bash completion scripts is a hard work. This package provides an easy way
12 to create bash completion scripts for any command, and also an easy way to install/uninstall
13 the completion of the command.
15 ## go command bash completion
17 In [gocomplete](./gocomplete) there is an example for bash completion for the `go` command line.
19 This is an example that uses the `complete` package on the `go` command - the `complete` package
20 can also be used to implement any completions, see [Usage](#usage).
24 1. Type in your shell:
26 go get -u github.com/posener/complete/gocomplete
32 Uninstall by `gocomplete -uninstall`
36 - Complete `go` command, including sub commands and all flags.
37 - Complete packages names or `.go` files when necessary.
38 - Complete test names after `-run` flag.
50 Assuming you have program called `run` and you want to have bash completion
51 for it, meaning, if you type `run` then space, then press the `Tab` key,
52 the shell will suggest relevant complete options.
54 In that case, we will create a program called `runcomplete`, a go program,
55 with a `func main()` and so, that will make the completion of the `run`
56 program. Once the `runcomplete` will be in a binary form, we could
57 `runcomplete -install` and that will add to our shell all the bash completion
63 import "github.com/posener/complete"
67 // create a Command object, that represents the command we want
69 run := complete.Command{
71 // Sub defines a list of sub commands of the program,
72 // this is recursive, since every command is of type command also.
73 Sub: complete.Commands{
75 // add a build sub command
76 "build": complete.Command {
78 // define flags of the build sub command
79 Flags: complete.Flags{
80 // build sub command has a flag '-cpus', which
81 // expects number of cpus after it. in that case
82 // anything could complete this flag.
83 "-cpus": complete.PredictAnything,
88 // define flags of the 'run' main command
89 Flags: complete.Flags{
90 // a flag -o, which expects a file ending with .out after
91 // it, the tab completion will auto complete for files matching
93 "-o": complete.PredictFiles("*.out"),
96 // define global flags of the 'run' main command
97 // those will show up also when a sub command was entered in the
99 GlobalFlags: complete.Flags{
101 // a flag '-h' which does not expects anything after it
102 "-h": complete.PredictNothing,
106 // run the command completion, as part of the main() function.
107 // this triggers the autocompletion when needed.
108 // name must be exactly as the binary that we want to complete.
109 complete.New("run", run).Run()
113 ### Self completing program
115 In case that the program that we want to complete is written in go we
116 can make it self completing.
118 Here is an [example](./example/self/main.go)