30.1 Entering Dired

To invoke Dired, type C-x d ( dired). This reads a directory’s name using the minibuffer, and opens a Dired buffer listing the files in that directory. You can also supply a wildcard file name pattern as the minibuffer argument, in which case the Dired buffer lists all files matching that pattern. A wildcard may appear in the directory part as well. For instance,

C-x d  ~/foo/*.el  RET
C-x d  ~/foo/*/*.el  RET

The former lists all the files with extension ‘ .el’ in directory ‘ foo’. The latter lists the files with extension ‘ .el’ in all the subdirectories of ‘ foo’.

On Posix systems, when the system shell supports globstar, a recursive globbing feature, and that support is enabled, you can use recursive globbing in Dired:

C-x d  ~/foo/**/*.el  RET

This command produces a directory listing with all the files with extension ‘ .el’, descending recursively in all the subdirectories of ‘ foo’. Note that there are small differences in the implementation of globstar between different shells. Check your shell manual to know the expected behavior.

If the shell supports globstar, but that support is disabled by default, you can still let Dired use this feature by customizing dired-maybe-use-globstar to a non- nil value; then Dired will enable globstar for those shells for which it knows how (see dired-enable-globstar-in-shell for the list of those shells).

The usual history and completion commands can be used in the minibuffer; in particular, M-n puts the name of the visited file (if any) in the minibuffer (see Minibuffer History).

You can also invoke Dired by giving C-x C-f ( find-file) a directory’s name.

You can ask Emacs to invoke Dired on the default-directory (see default-directory) of any buffer, by typing C-x C-j ( dired-jump). If the buffer visits a file, this command will move point to that file’s line in the Dired buffer it shows; otherwise, point will end up on the first file in the directory listing. As an exception, if you type C-x C-j in a Dired buffer, Emacs displays the directory listing of the parent directory and places point on the line that corresponds to the directory where you invoked dired-jump. Typing C-x 4 C-j ( dired-jump-other-window has the same effect, but displays the Dired buffer in a new window.

The variable dired-listing-switches specifies the options to give to ls for listing the directory; this string must contain ‘ -l’. If you use a prefix argument with the dired command, you can specify the ls switches with the minibuffer before you enter the directory specification. No matter how they are specified, the ls switches can include short options (that is, single characters) requiring no arguments, and long options (starting with ‘ --’) whose arguments are specified with ‘ =’.

Dired does not handle files that have names with embedded newline characters well. If you have many such files, you may consider adding ‘ -b’ to dired-listing-switches. This will quote all special characters and allow Dired to handle them better. (You can also use the C-u C-x d command to add ‘ -b’ temporarily.)

Dired displays in the mode line an indication of what were the switches used to invoke ls. By default, Dired will try to determine whether the switches indicate sorting by name or date, and will say so in the mode line. If the dired-switches-in-mode-line variable is as-is, the switches will be shown verbatim. If this variable’s value is an integer, the switch display will be truncated to that length. This variable can also be a function, which will be called with dired-actual-switches as the only parameter, and should return a string to display in the mode line.

If your ls program supports the ‘ --dired’ option, Dired automatically passes it that option; this causes ls to emit special escape sequences for certain unusual file names, without which Dired will not be able to parse those names. The first time you run Dired in an Emacs session, it checks whether ls supports the ‘ --dired’ option by calling it once with that option. If the exit code is 0, Dired will subsequently use the ‘ --dired’ option; otherwise it will not. You can inhibit this check by customizing the variable dired-use-ls-dired. The value unspecified (the default) means to perform the check; any other non- nil value means to use the ‘ --dired’ option; and nil means not to use the ‘ --dired’ option.

On MS-Windows and MS-DOS systems, and also on some remote systems, Emacs emulates ls. See Emulation of ls on MS-Windows, for options and peculiarities of this emulation.

To display the Dired buffer in another window, use C-x 4 d ( dired-other-window). C-x 5 d ( dired-other-frame) displays the Dired buffer in a separate frame.

Typing q ( quit-window) buries the Dired buffer, and deletes its window if the window was created just for that buffer.