32.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 (see How display-buffer works).

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 ‘=’.

You can declare dired-listing-switches as a connection-local variable in order to adjust its value to match what a remote system expects (see Per-Connection Local Variables).

When a file name contains a newline character, Dired displays it by default as a literal newline, so the display of this file name occupies more than one line in the Dired buffer. If you invoke a Dired operation on such a file listing, in many cases it will fail and signal an error. For this reason, when Dired displays a file name containing a literal newline, Emacs recognizes this and automatically pops up a buffer with an informative warning. For such file names, Dired offers an alternative display, using the ls switch ‘-b’, in which newline characters are represented by ‘\n’ and the Dired listing of the file occupies one line as usual, so you can execute all applicable Dired operations on it.²⁴

Emacs provides two different ways to make Dired use the ‘-b’ switch:

• You can add ‘-b’ to dired-listing-switches before invoking dired. Since this variable is a user option, you can alter its value persistently either by using the Customization interface (see Saving Customizations) or by using the setopt macro in your initialization file (see Examining and Setting Variables).²⁵ You can also add ‘-b’ just for the next dired invocation by typing C-u C-x d.
• If you enable the user option dired-auto-toggle-b-switch, then when you visit a directory containing a file whose name has a newline, Emacs will automatically add the ‘-b’ switch and redisplay the directory in Dired to show ‘\n’ in the file name. If you edit the file name and remove the ‘\n’ character, then on completing the edit Emacs automatically removes the ‘-b’ switch and redisplays the Dired buffer, so that file names with tab or space characters now show literal spaces without a backslash. If you enable or disable dired-auto-toggle-b-switch after visiting a directory containing a file name with a newline, Emacs will add or remove the ‘-b’ switch as appropriate and automatically redisplay the Dired buffer.

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. See How display-buffer works.

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