complete built-in command for tcsh: List completions


complete [command [word/pattern/list[:select]/[[suffix]/] …]]


complete, without arguments, lists all completions. With command, complete lists completions for command. With command and word etc., complete defines completions.


command can be a full command name or a glob-pattern. See File name substitution. It can begin with – to indicate that completion should be used only when command is ambiguous.
word specifies which word relative to the current word is to be completed, and can be one of the following:
Current-word completion. pattern is a glob-pattern which must match the beginning of the current word on the command line. pattern is ignored when completing the current word.
Like c, but includes pattern when completing the current word.
Next-word completion. pattern is a glob-pattern which must match the beginning of the previous word on the command line.
Like n, but must match the beginning of the word two before the current word.
Position-dependent completion. pattern is a numeric range, with the same syntax used to index shell variables, which must include the current word.
The list of possible completions, which can be one of the following:
Bindings (editor commands)
Directories which begin with the supplied path prefix
Environment variables
File names
File names which begin with the supplied path prefix
Group names
Shell variables
Plain (text) files
Plain (text) files which begin with the supplied path prefix
Any variables
User names
Like n, but prints select when list-choices is used
Words from the variable var
Words from the given list
Words from the output of command
select is an optional glob-pattern. If given, only words from list which match select are considered and the fignore shell variable is ignored. The last three types of completion might not have a select pattern, and x uses select as an explanatory message when the list-choices editor command is used.
suffix is a single character to be appended to a successful completion. If null, no character is appended. If omitted (in which case the fourth delimiter can also be omitted), a slash is appended to directories and a space to other words.


  1. Some commands take only directories as arguments, so there is no point in completing plain files. For example:
    > complete cd 'p/1/d/'
    completes only the first word following cd (p/1) with a directory.
  2. p-type completion can be used to narrow down command completion. For example:
            > co[‸D]
            complete compress
            > complete -co* 'p/0/(compress)/'
            > co[‸D]
            > compress
    This completion completes commands (words in position 0, p/0) which begin with co (thus matching co*) to compress (the only word in the list). The leading - indicates that this completion is to be used only with ambiguous commands.
  3. This is an example of n-type completion. Any word following find and immediately following -user is completed from the list of users.
    > complete find 'n/-user/u/'
  4. This demonstrates c-type completion. Any word following cc and beginning with -I is completed as a directory. -I is not taken as part of the directory because we used lowercase c.
    > complete cc 'c/-I/d/'
  5. Different lists are useful with different commands:
            > complete alias 'p/1/a/'
            > complete man 'p/*/c/'
            > complete set 'p/1/s/'
            > complete true 'p/1/x:Truth has no options./' 
    These complete words following alias with aliases, man with commands, and set with shell variables. true doesn't have any options, so x does nothing when completion is attempted and prints 'Truth has no options.' when completion choices are listed.

    The man example, and several other examples that follow, could just as well have used c/* or n/* as p/*.

  6. Words can be completed from a variable evaluated at completion time,
            > complete ftp 'p/1/$hostnames/'
            > set hostnames = (
            > ftp [‸D]
            > ftp [‸C]
            > set hostnames = (
            > ftp [‸D]
    or from a command run at completion time:
            > complete kill 'p/*/'ps | awk \{print\ \$1\}'/'
            > kill -9 [‸D]
            23113 23377 23380 23406 23429 23529 23530 PID
    The complete command does not itself quote its arguments, so the braces, space and $ in {print $1} must be quoted explicitly.
  7. One command can have multiple completions:
            > complete dbx 'p/2/(core)/' 'p/*/c/'
    This example completes the second argument to dbx with the word core and all other arguments with commands. The positional completion is specified before the next-word completion. Since completions are evaluated from left to right, if the next-word completion were specified first it would always match and the positional completion would never be executed. This is a common mistake when defining a completion.
  8. The select pattern is useful when a command takes only files with particular forms as arguments. For example,
            > complete cc 'p/*/f:*.[cao]/'
    completes cc arguments only to files ending in .c, .a, or .o. select can also exclude files, using negation of a glob-pattern as described under File name substitution.
  9. One might use
            > complete rm 'p/*/f:‸*.{c,h,cc,C,tex,1,man,l,y}/'
    to exclude precious source code from rm completion. Of course, one could still type excluded names manually or override the completion mechanism using the complete-word-raw or list-choices-raw editor command.
  10. The D, F and Tlists are like d, f and t respectively, but they use the select argument in a different way: to restrict completion to files beginning with a particular path prefix. For example, the Elm mail program uses = as an abbreviation for one's mail directory. One might use
            > complete elm c@=@F:$HOME/Mail/@ 
    to complete elm -f = as if it were elm -f ~/Mail/. We used @ instead of / to avoid confusion with the select argument, and we used $HOME instead of ~ because home directory substitution only works at the beginning of a word.
  11. suffix is used to add a nonstandard suffix (not space or '/' for directories) to completed words. For example,
            > complete finger 'c/*@/$hostnames/' 'p/1/u/@'
    completes arguments to finger from the list of users, appends an @, and then completes after the @ from the hostnames variable. Note the order in which the completions are specified.
  12. A more complex example:
            complete find \
            'n/-name/f/' 'n/-newer/f/' 'n/-{,n}cpio/f/' \
            'n/-exec/c/' 'n/-ok/c/' 'n/-user/u/' \
            'n/-group/g/' 'n/-fstype/(nfs 4.2)/' \
            'n/-type/(b c d f l p s)/' \
            'c/-/(name newer cpio ncpio exec ok user \
            group fstype type atime ctime depth inum \
            ls mtime nogroup nouser perm print prune \
            size xdev)/' \
    This completes words following -name, -newer, -cpio or ncpio (note the pattern which matches both) to files, words following -exec or -ok to commands, words following user and group to users and groups respectively and words following -fstype or -type to members of the given lists. It also completes the switches themselves from the given list (note the use of c-type completion) and completes anything not otherwise completed to a directory.

    Programmed completions are ignored if the word being completed is a tilde substitution (beginning with ~) or a variable (beginning with $). complete is an experimental feature, and the syntax might change in future versions of the shell. See also the uncomplete built-in command.

Related information

tcsh, uncomplete