tcsh Completion: Diagnose Command, Variable, and Filename Candidates

tcsh completion is an interactive parser feature: the shell examines the command line around the cursor, decides whether the current word is a command, variable, or filename, and tries to extend that word when it finds a unique match. The same keystroke can therefore consult PATH, shell variables, or the filesystem depending on the word’s position and surrounding operators.

When completion appears wrong, first determine what category tcsh assigned to the word. A filename completion failure is not fixed by changing PATH, and a command-name completion failure is not necessarily a filesystem permission issue. Then inspect the matching candidates and the shell variables that influence listing, suffix handling, and matching behavior.

Understand how tcsh classifies the current word

The first word in the command line and the first word after a command separator or pipeline operator are treated as commands. A word beginning with a dollar sign is treated as a variable. Other words are generally treated as filenames. The completion parser also accounts for filename substitutions such as home-directory references and directory-stack substitutions.

% ec<Tab>
% echo $pa<Tab>
% ls /usr/lo<Tab>

The examples illustrate three different completion contexts: command lookup, variable-name lookup, and path completion. The exact candidates depend on the current command path, variables, filesystem, and tcsh options. Do not assume a completion result is merely visual text; it becomes part of the command line and may be executed when Enter is pressed.

Completion can operate in the middle of an input line, not only at the end. The shell replaces the word being completed and leaves text to the right of the cursor. If the result looks partially duplicated, inspect the cursor position and the characters that remain after it. A completion that inserted a directory separator or a trailing space can also change how the next keystroke behaves.

Distinguish completing from listing

When a prefix has one unique match, the completion editor can extend the word. When it is ambiguous, tcsh may ring the terminal bell or list choices depending on configuration. The ^D key is commonly bound to delete-char-or-list-or-eof: on an incomplete word it lists possibilities, in the middle of a line it may delete a character, and on an empty line it can signal end-of-file unless the shell is configured to ignore it.

% set autolist = ambiguous
% set addsuffix
% set complete = enhance

The autolist setting can list choices when completion fails; the ambiguous value narrows listing to cases where no new characters can be added. addsuffix controls whether a completed directory gets a slash or another completed word receives a trailing space. Setting complete to enhance changes matching behavior, including case and punctuation handling. These options affect interactive behavior, so test them in a disposable session before adding them to a shared startup file.

Use completion editor commands deliberately. ^D may have an EOF role on an empty line, while a dedicated list-choices binding can list possibilities in more positions. bindkey can assign editor commands to keys, but changing a familiar binding affects muscle memory and may interfere with terminal or remote-session key handling.

Filter noisy filename candidates with fignore

The fignore variable contains filename suffixes that completion should ignore when selecting candidates. It does not remove those files from directory listings. This is useful when editor backups or build products make an otherwise unique source filename ambiguous, but it should not hide a suffix that an operator sometimes needs to select explicitly.

% set fignore = (.o \~)
% ls main<Tab>

With this configuration, object files ending in .o and backup files ending in a tilde can be ignored during completion. The backslash protects the tilde from being interpreted as a home-directory prefix when the variable is assigned. Verify the exact result in a scratch directory containing both a source file and ignored suffixes. Use listing to confirm that ignored candidates still exist and were not deleted.

fignore is a preference, not a cleanup policy. It does not make a wildcard operation safer and does not stop a command from matching ignored files when the user types an explicit pattern. Do not use completion filtering to conceal files that must be reviewed before a destructive operation.

Improve matching without changing the filesystem

The complete variable can enable enhanced matching. In the documented enhance mode, completion ignores case and treats periods, hyphens, and underscores as word separators in specified ways. This can help with long package or command names, but a fuzzy match can produce a candidate different from the string an operator typed. Review the completed spelling before running a command that changes state.

The recexact setting can prefer a shortest exact match even when longer names share that prefix. autoexpand can run history expansion before completion, while spelling-correction variables can alter the word being completed. These features interact with the command line and should be tested independently. Do not enable multiple fuzzy or automatic transformations at once and then attribute a surprising result to only one setting.

Completion is sensitive to the active PATH for command names and to the active working directory for filenames. A command can be installed but absent from the current shell’s path. A file can be visible in a different directory than the one tcsh is completing. Inspect path, pwd, and the exact word position before changing completion preferences.

Keep prompt and remote environments predictable

Completion depends on the tcsh process’s current state. A remote shell can have a different PATH, home directory, locale, and startup sequence than a local terminal. A shell launched by a restricted account or a service may not support interactive completion at all. Do not put completion key bindings or terminal control sequences into code that runs in noninteractive jobs.

Interactive startup files can initialize completion behavior, but a long-running shell will not automatically refresh every cached or session value when a package is installed. Start a fresh shell and compare the result. If a function or alias changes a command name, test how the parser treats the command word after alias expansion and avoid assuming that a completion result matches an external executable.

Keep startup configuration minimal and readable. A failed completion setup should not prevent a user from starting a useful shell. If a custom key binding depends on a terminal capability or program, guard it and provide a fallback. Do not print debugging output from .tcshrc to stdout where a calling tool might expect machine-readable results.

Test completion in an isolated directory

Create a temporary test directory with names that exercise ambiguity: a unique prefix, two names sharing a prefix, a directory, a filename with spaces, a backup suffix, and a case variant. Use a harmless command such as echo or ls to inspect the completed text. Test command-name, variable-name, and filename contexts separately so that one class does not mask another.

Test the same key in the middle and at the end of an input line. Verify whether the shell inserts a slash or space, whether it lists alternatives, and what happens when no candidate exists. If ^D is involved, test an empty line in a disposable shell so an unexpected EOF does not close a valuable session.

After changing .tcshrc, launch a new tcsh process and inspect its variables and bindings. Avoid repeatedly sourcing the full file in a live session because configuration can register duplicate key bindings or rerun side effects. Keep a known-good terminal available while testing a new completion configuration.

Operational checklist

Determine whether the current word is a command, variable, or filename before debugging. Check PATH, working directory, variables, and matching suffixes; then inspect autolist, addsuffix, fignore, and complete settings. Change one option at a time and test in a scratch directory with harmless commands. Treat completed text as untrusted input until it is reviewed.

tcsh completion is predictable once its parser context and candidate source are clear. Its settings can make interactive work more efficient, but they also alter how text enters the command line. Preserve familiar key semantics, keep startup changes scoped, and verify the final command before executing a side effect.

Related:

Sources: