Let's look at an example of one type of completion, filename completion. Other types of completion work in generally the same way.

Filename completion is one of the most common types. You can type the initial part of a filename and then press the TAB key. (In the C shell, first enable completion by setting the variable filec (Section 30.9) or complete, then press ESC.) If the shell can figure out the complete filename from the part that you've typed, it will fill in the rest of the name. If not, it will fill in as much of the name as is unambiguous and then let you type some more. For example:

$ ls
alpha.c    alpha.o   beta.c
$ cc b TAB
$ cc beta.c        Shell fills in the filename automatically

(With tcsh and csh, your terminal will beep if more than one file matches the name you've typed. If all this beeping drives you crazy, you can set the nobeep shell variable to turn it off.) In this case, only one filename begins with b, so the shell can fill in the entire name. This works with pathnames (Section 1.16) too: each time you press TAB, the shell completes the name up to the next slash (/) if it can.

If you type part of a filename and then type CTRL-d (in bash, type TAB twice), the shell lists all the files that match whatever you've typed. It then redisplays your command line and lets you continue typing. For example:

% cc a CTRL-d
alpha.c    alpha.o
% cc alpha.

Two files begin with the letter "a"; the shell lists them. It then redisplays the cc command, letting you finish the filename.

That last example shows a problem with filename completion: it's matching the ".o file," (Section 1.12) named alpha.o. It's a type of file that most users wouldn't want to manipulate from the command line; they'd rather the shell ignore all .o files. Section 28.7 explains the fignore list; it solves this problem in most cases. Section 31.10 shows an interesting shortcut to filename completion: cding to a directory by typing its "initials."

The filename completion section showed how completion works by default: press TAB, and the shell completes as much as it can and then waits for you either to press TAB again (to see all possible completions) or to type enough of the word to make it unambigious.

tcsh and zsh let you customize completion even farther: specific completion instructions for each Unix command you define. For instance, the mail command wants email addresses on its command line, and you can declare a list of addresses that are available to complete (this could be a list of friends and associates you send a lot of mail to). You might use the ssh and telnet commands (Section 1.21) to connect to particular remote hosts, and you'd like to be able to complete the hostnames for those particular hosts. (The bash hostname completion feature reads hostnames from a file like /etc/hosts -- but it only completes hostnames if the string starts with an @ character or if you use a special editor command for completing hostnames.)

The tcsh command complete defines these custom completions. The syntax is hairy, so I won't try to explain all of it here. Instead, let's look at an overall example from the MH email system (Section 6.2). You use MH commands directly from a shell prompt instead of first starting an email command interpreter and entering commands at the interpreter's own prompt, as you do with most other email packages. Most MH programs accept a mail folder name as one of their command-line arguments. A mail folder name starts with a + (plus sign)[85] and can appear anywhere in a command line.

[85]An MH folder name can also start with an @ (at sign), but that use is less common. Besides, this is just an example!

MH mail folders can be stored anywhere on the filesystem -- even on a networked filesystem on a remote computer. Here are the four lines that I put in my .tcshrc setup file (Section 3.3):

{ } Section 28.4

# Set up MH folder name completion for "folder", "refile", "scan", "show":
folders -fast -recurse | \
     sed -e '/DELETE$/d' -e 's/^/+/' > $HOME/Mail/folderlist
complete {folder,refile,scan,show} 'C@*@`cat $HOME/Mail/folderlist`@'

The first command builds a file named folderlist with a list of strings (in this case, folder names) to complete. I don't want completion to include folder names I'll never look in, so I filtered the folder output with sed (Section 34.1) to exclude the names I don't want -- in this case, folder names ending with DELETE. (This list is also useful in other places, it turns out, not just in tcsh completion.) A + is prepended to each folder name because folders doesn't add the plus signs, but we need them for tcsh matching. So the first few lines of folderlist look like this:

+drafts
+inbox
+jobs
+jobs/bay-area
+jobs/miscellaneous
   ...

The second command, complete, starts with a list in braces of the commands that should complete folder names. The next argument is complex and has lots of possible variations; this one matches any pattern included with backquotes (Section 28.14) from the cat (Section 12.2) command, which gives us the contents of folderlist. There are lots of variations! The bottom line is how this works... here's an example of completing a folder name:

tcsh> scan +j TAB
tcsh> scan +jobs/m TAB
tcsh> scan +jobs/miscellaneous last:20

After completing the folder name (in two steps), tcsh leaves a space; I type the rest of the command line and press ENTER to run it.

Some shells have customizable, built-in command-line editors that use key bindings to control how and where completion takes place. For example, in tcsh, pressing TAB invokes the complete-word function, but you can change TAB to do menu completion (as explained above) by binding the editor function complete-word-fwd to TAB key.

In bash, TAB does basic completion with the editor's complete function. But the bash editor has many more bindings than tcsh does. For instance, typing M-/ runs complete-filename, which treats the text before the cursor as a filename and does filename completion on it. Typing M-$ runs complete-variable, which treats the text before the cursor as a shell variable and does variable completion on it. There are plenty of variations -- like C-x $, which invokes the possible-variable-completions function to list all shell variable names that could be completed. Section 28.4 has an example of M-{, the curly-brace completion function.

For details on your particular shell, check its manual page.

--JP, ML, and SJC