complete-shell - Modern Tab Completion Everywhere
# Install the complete-shell software: git clone https://github.com/complete-shell/complete-shell source /path/to/complete-shell/.rc # Turn on the cool modern features (off by default): complete-shell config modern_settings true # Try tab completion: complete-shell <tab><tab> # Search for existing complete-shell packages: complete-shell search # Install the packages you like: complete-shell install this-cmd complete-shell install another-cmd this-cmd <TAB><TAB> # Completion should work! # Write your own compdef files. (See below) # Add your compdef files: complete-shell add ./src/foo.comp # Learn the other complete-shell commands: complete-shell -h # Quick reference complete-shell help # Complete documentation
WARNING: THIS FRAMEWORK IS VERY NEW.
Only works on Bash so far
Only tested on Mac and Ubuntu Linux so far
Pull Requests welcome!
CompleteShell adds command completion for everything, everywhere. It provides a framework to define command completion in a simple, single file format.
CompleteShell works in:
zsh (coming soon)
Fish (coming soon)
People can easily write complete-shell files for commands that don't yet have completion and share them with the world. They can also write their own custom files, or fine tune existing ones to their liking.
CompleteShell also does Bash completion like you've never seen it. It can show you completion descriptions, show command usage, show hints to help you along, and turn on the more modern Bash completion options (like pressing TAB once instead of twice). These things are configurable by you.
Run these commands:
# clone the Git repo: git clone https://github.com/complete-shell/complete-shell # `source` the `.rc` file in your shell startup configuration file: source /path/to/complete-shell/.rc
You should also really try turning on the cool modern settings:
complete-shell config modern_settings true
- Bash 3.2+
Even if you don't use Bash as your shell,
complete-shellneeds it because it is written in Bash. Fortunately most computers have Bash 3.2+ installed.
Git is used for getting compdef repos to install and also is used for its (totally awesome) command line options parsing facility.
- Completion Subsystem
CompleteShell attempts to fit into your Shell's existing Completion system.
For Bash, there is system that almost everyone uses. It can usually be found in
/etc/bash_completion*(older systems and Mac). CompleteShell will check to make sure this subsystem is in place.
For Zsh and Fish, completion facilities are first class parts of the shell. CompleteShell will compile to code that fits right in.
Display the complete-shell manpage. Same as
-hoption will display a quick reference help guide.
complete-shell config [<key> [<value>]]
With no arguments, show all settings. With 1 argument, print the value for a key. With 2 arguments, set a key to a value.
Config values are stored in
See "Configuration Options" below.
complete-shell search [<search string>]
Find registered completion packages that are available online.
List all your installed completion packages.
complete-shell show <compdef-name>
Show information about a completion definition.
complete-shell install <package>
Installs compdef files from git repos online. You can find these repos using the
searchcommand or use other ones that you know about.
compdef-targetcan be a simple name (found in search) or a git repo URL.
complete-shell add <compdef-filepath>
Adds a local compdef file path to your installed completions. It will be enabled by default.
complete-shell delete <compdef-name>
Delete a compdef file from your configuration.
complete-shell disable <compdef-name>
Disable a compdef (but don't delete it). Use this to turn off a specific command completion temporarily. Use the
enablecommand to turn it back on.
complete-shell enable <compdef-name>
Enable a compdef. Usually only after you have disabled it.
complete-shell update <compdef-name>
Update specific compdef to their latest version.
complete-shellinstallation to the latest version.
complete-shell compile <compdef-name-or-path>
Compdef files are themselves valid shell files. (A common subset of Bash, Zsh and Fish!). They get compiled into leaner shell-specific files that are tuned for the tab completion facilities of the particular shell.
- `complete-shell alias <compdef-name> <alias-name>
This command will create an alias completion for an existing alias of a command. command completion. Try making the alias
csfor the command
alias cs=complete-shell complete-shell alias complete-shell cs
These options all default to
false. To turn on an option:
complete-shell config <option> true
Disable CompleteShell tab completion altogether.
An umbrella option to always use the most modern CompleteShell settings. Effectively set these to true:
Only require a single TAB press to trigger completion. By default, Bash requires you to press TAB twice.
Disable prompt for more than 100 completions. When text is too big for the screen it will start a pager.
CompleteShell completions can have short descriptions. Set this option if you want to see them.
Some commands have a defined usage, which is helpful to have when writing the command. Turn this on to see them.
CompleteShell can give you hints about certain things when it thinks they'll be useful. Use this to enable them.
Recent Bash versions allow for completions to be sorted horizontally, which is usually better. We turn that on for you if available. Use this to keep the Bash default.
Use fzf selector (if installed) when appropriate. Avoids the terrible Bash completion pager for large result sets.
CompleteShell has environment variables that you can use to customize various things. Usually you don't need to worry about these at all.
The location of the complete-shell software being used.
This variable is required and set automatically for you at shell startup.
If you use
source /path/to/complete-shell/.rcto enable complete-shell, it is set to
The directory where your completions are installed and your configuration lives.
Defaults to the last directory in
A colon separated path variable for finding installed completions.
Your config file, managed by
complete-shell config ....
Directory where installed completions go.
Directory where completion source repositories are installed (cloned) into.
Directory where completions are compiled into (for Bash).
Your shell. ('bash', 'zsh', 'fish').
A complete-shell "command completion definition" ("compdef" for short) file is a minimal DSL that allows people to specify how command completion should work for a given command:
Here is a simple example. Define a file called
# Required header declaring the API version: CompleteShell v0.2 # Command name: N foo 0.0.1 ..The mighty foo CLI # Command options: O --aaa ..The aaa option O --bbb =file \ ..The bbb option # Sub-commands: C bar +str ..Do the bar C baz +num +dir ..Do the baz
complete-shell add foo.comp
Now you have command completion for the
complete-shell command itself comes with a compdef file that you can find in
compdef File Guidelines
compdef files are named
The name should be either:
The name of the CLI command for which it adds support
The name of a project that has multiple commands
Shell specific functions go in
<name>.shis POSIX shell code that works in Bash or Zsh
A compdef file can define completions for one or more commands
A compdef Git repo contains one or more compdef files
A set of compdef files is called a package
A compdef file uses the syntax described in the next section
The compdef files are written in a simple DSL. The DSL has a set of simple commands that are usually a single capital letter. Blank lines and
# comments are supported.
The DSL happens to a common subset of the Bash, Zsh and Fish shell languages, but compdef files should not contain any statements that are not documented by the DSL.
The DSL is versioned and can change over time. It is designed to be forward and backward compatible. ie People can use compdef files of any DSL version, and authors can not worry about their compdefs breaking with future
complete-shell releases. Users will need to upgrade
complete- shell to at least the version of the most modern compdef file's API version that they want to use.
compdef v0.2 Syntax
A compdef files consists of comments, blank lines and single-line command statements.
Note: the single-line commands can actually span multiple lines by using
This is a list of the compdef statement commands:
The first statement in every compdef file must be
CompleteShelland must have a version argument as shown above. The version is used to invoke the appropriate compiler and runtime for that file.
N <name> [<version-number>] [..<description>]
The name of the statement for which completion is being defined. This is the second statement in the file. All other statements apply to this
nameuntil the end of file or another
Ncommand starts a new definition. Version numbers must be of the form
This defines an option that applies to the CLI command.
Ois also used to define options that are specific to a sub-command (when they follow the sub- command's
This defines the arguments and their types. An arg type always starts with a
+character. For example,
+file-pathcalled a function named
file- pathto list the completions that can happen for that argument.
Acan be used for a normal command, or for sub-commands.
C <subcommand name>
This defines a subcommand that applies to the CLI command.
V @<var-name> = <set of command words>
For the purposes of reusing common definitions,
Vlets you define variables. The variables always begin with a
Sharing compdef files is simple. Create a Git repo for your compdef files:
ReadMe # Describe your repo foo.comp # compdef for the foo command foo.sh # Helper shell functions for `foo` completion bars.comp # compdef for the (several) bar commands
Then push it to a public Git host, like GitHub or BitBucket.
If you want it to be found in the
complete-shell search command, then register it with complete-shell:
Add your repo to the
Commit and push
Create a GitHub Pull Request
Copyright and License
Copyright 2019. Ingy döt Net <email@example.com>.
CompleteShell is released under the MIT license.
See the file LICENSE for more details.