Collection of useful dired additions. I don't want this to become
another dired+, so I'm splitting all the functionality into separate
mutually independent packages. All shared functionality and helpers
will be extracted into a single package dired-hacks-utils, so that
will be the only dependence.
In addition, all the packages require dash.el
Please note that only the packages that are listed in this readme are "finished" (means in package repositories, with usable UI etc.). All the other files are work-in-progress packages you could probably use, but it would be a bit more painful.
If you want to support this project, you can do it in the following ways:
- Contribute code. Since this collection comes from my own config, it mostly contains stuff I use or find useful. If you have an idea that is not yet implemented and will benefit this project, feel free to implement it and submit a pull request. If you have any concerns whether your contribution will be accepted, ask beforehand. You can email the author or start an issue on the tracker.
- Contribute ideas. Even if you can't code Emacs Lisp, you can still contribute valuable ideas for other programmers to implement. Simply start new issue on the tracker and submit your suggestion.
- You can make a financial donation through PayPal or Patreon. If you like dired-hacks and can spare a modest amount on a donation, feel free to do so. These donations are expressions of your gratitude and are used for my personal "rewards" (books, games, music etc.). You can also gift me a game on Steam or buy something on Amazon. Regardless of the donations, dired-hacks will always be free both as in beer and as in speech.
Set of utility functions used in all the dired-hacks packages.
This package also provides these interactive functions:
dired-hacks-next-file- go to next file, skipping empty and non-file linesdired-hacks-previous-file- go to previous file, skipping empty and non-file linesdired-utils-format-information-line-mode- Format the information (summary) line file sizes to be human readable (e.g. 1GB instead of 1048576).
The filtering system is designed after ibuffer: every dired buffer has associated "filter stack" where user can push filters (predicates). These filters are by default logically "anded", meaning, only the files satsifying all the predicates are shown.
Some filters take additional input from the user such as part of name, regexp or extension, other filters only use a predefined predicate such as "show only directories" or "omit dot files".
In addition, there are two "metafilters", the or filter and the
not filter. These take other filters as arguments and change
their logical interpretation. The or filter takes the two
filters on top of the stack, pops them and pushes a filter that
matches files satisfying one or the other (or both) filters. The
not filter pops the top filter and pushes its logical negation.
To enable or disable the filters, toggle minor mode
dired-filter-mode. Toggling this mode preserves the filter
stack, so you can use it to quickly hide/unhide files filtered by
the current filter setup.
All the provided interactive functions are available from
dired-filter-map. You can customize dired-filter-prefix to set a
prefix for this map or bind it manually to a prefix of your choice
using:
(define-key dired-mode-map (kbd "some-key") dired-filter-map)
The bindings follow a convention where the filters are mapped on
lower-case letters or punctuation, operators are mapped on symbols
(such as !, |, * etc.) and group commands are mapped on upper-case
letters. The exception to this is p which is bound to
dired-filter-pop, which is a very common operation and warrants a
quick binding.
In addition to filtering, you can also use the same predicates to
only mark files without removing the rest. All the filtering
functions of the form dired-filter-by-* have their marking
counterpart dired-filter-mark-by-*. These are available from
dired-filter-mark-map. You can customize
dired-filter-mark-prefix a prefix for this map or bind it
manually to a prefix of your choice using:
(define-key dired-mode-map (kbd "some-key") dired-filter-mark-map)
The marking operations are not placed on stack, instead, the marks are
immediately updated by "OR"-ing them together. To remove marks that
would otherwise be selected by a filter, use prefix argument (usually
bound to C-u). To logically negate the meaning of the filter, you
can call the function with a double prefix argument (usually C-u
C-u)
You can use saved filters to mark files by calling
dired-filter-mark-by-saved-filters.
To remove the filter from the stack, use dired-filter-pop or
dired-filter-pop-all
To break a metafilter apart, you can use dired-filter-decompose
to decompose the parts of the metafilter and push them back to
the stack.
You can transpose the filters on the top of the stack using
dired-filter-transpose
Here's a list of built-in filters:
dired-filter-by-namedired-filter-by-regexpdired-filter-by-extensiondired-filter-by-dot-filesdired-filter-by-omitdired-filter-by-garbagedired-filter-by-predicatedired-filter-by-filedired-filter-by-directorydired-filter-by-modedired-filter-by-symlinkdired-filter-by-executable
You can see their documentation by calling M-x describe-function.
Specifically, dired-filter-by-omit removes the files that would
be removed by dired-omit-mode, so you should not need to use
both---in fact it is discouraged, as it would make the read-in
slower.
When called with negative prefix argument, some filters can read multiple values. The resulting predicate is often much faster than having the filter repeated with single argument. Read the documentation to learn more about the calling conventions. Currently, these filters support reading multiple arguments:
dired-filter-by-extension
To define your own filters, you can use the macro
dired-filter-define. If you define some interesting filter,
please consider contributing it to the upstream.
In addition to the built-in filters and your own custom filters,
this package provides an option to save complex compound filters
for later use. When you set up a filter stack you would like to
save, call dired-filter-save-filters. You will be prompted for a
name under which this stack will be saved.
The saved filter will be added to dired-filter-saved-filters
variable, which you can also customize via the customize interface
or manually add entries with push or add-to-list. If you use
customize, calling dired-filter-save-filters will automatically
save the new value into your customize file.
You can delete saved filters with dired-filter-delete-saved-filters.
To use a saved filter, you can use either
dired-filter-add-saved-filters or
dired-filter-load-saved-filters. The first pushes the saved
filter on top of the currently active stack, the second clears
current filter stack before loading the saved filter configuration.
An example use is to create filters for "logical groups" of files, such as media files, image files or files used when programming in certain environment (for example, show files with .h and .c extensions). Saved filters save you the time of setting up the filters each time you want this specific view.
As a concrete example of above, author uses a saved filter "media" with value:
(extension "ogg" "flv" "mpg" "avi" "mp4" "mp3")
;; show all files matching any of these extensions
Furthermore, instead of only filtering the dired buffer by removing lines you are not interested in, you can also group lines together by filters. That is, lines (files, directories...) satisfying a filter will be moved together under a common drawer. This mechanism works in analogy with ibuffer filter groups.
The variable dired-filter-group-saved-groups contains
definitions of filter groups. You can create and save multiple
filter groups (views) and switch between them by setting the
dired-filter-group variable.
To enable or disable the filter groups toggle minor mode
dired-filter-group-mode. Toggling this mode preserves the active
filter group so you can use it to quickly group and ungroup the
files.
Here is a screenshot with an active filter group. Notice that regular filtering works also with filter groups.
Placing the point on the drawer header and hitting RET folds it.
Hitting RET again expands it.
The dired-filter-group-saved-groups used in the above screenshot is the following:
(("default"
("PDF"
(extension . "pdf"))
("LaTeX"
(extension "tex" "bib"))
("Org"
(extension . "org"))
("Archives"
(extension "zip" "rar" "gz" "bz2" "tar"))))You can of course be more imaginative and use filtering based on other criteria than just extensions ;)
You can clone the currently visible dired buffer by calling
dired-filter-clone-filtered-buffer.
Adds avfs support for seamless archive
browsing. This extension therefore depends on the presence of avfsd
on your system. In debian-derived distributions you can usually do
apt-get install avfs
avfs is probably also available for Mac OS. You're out of luck on
Windows, sorry.
Once the daemon is installed, run it with mountavfs and everything
"Should Just Work™".
While emacs already has the auto-mode-alist, this is often
insufficient. Many times, you want to open media files, pdfs or
other documents with an external application. There's remedy for
that too, namely dired-guess-shell-alist-user, but that is still
not as convenient as just hitting enter.
This package adds a mechanism to add "hooks" to dired-find-file that
will run before emacs tries its own mechanisms to open the file, thus
enabling you to launch other application or code and suspend the
default behaviour.
By default, two additional methods are enabled,
dired-open-by-extension and dired-open-subdir.
This package also provides other convenient hooks:
dired-open-xdg- try to open the file usingxdg-opendired-open-guess-shell-alist- try to open the file by launching applications fromdired-guess-shell-alist-userdired-open-call-function-by-extension- call an elisp function based on extension.
These are not used by default.
You can customize the list of functions to try by customizing
dired-open-functions.
To fall back to the default dired-find-file, you can provide the
prefix argument (usually C-u) to the dired-open-file function.
This is useful for example when you configure html files to be
opened in browser and you want to edit the file instead of view it.
Note also that this package can handle calls when point is not on a
line representing a file---an example hook is provided to open a
subdirectory under point if point is on the subdir line, see
dired-open-subdir.
If you write your own handler, make sure they do not throw errors but instead return nil if they can't proceed. Please, don't forget to submit interesting handlers!
This package adds more customizable highlighting for files in dired
listings. The group dired-faces provides only nine faces and
isn't very fine-grained.
The definitions are added by several macros, currently available are:
dired-rainbow-define- add face by file extensiondired-rainbow-define-chmod- add face by file permissions
You can display their documentation by calling (substituting the desired macro name):
M-x describe-function RET dired-rainbow-define RET
Here are some example uses:
(defconst my-dired-media-files-extensions
'("mp3" "mp4" "MP3" "MP4" "avi" "mpg" "flv" "ogg")
"Media files.")
(dired-rainbow-define html "#4e9a06" ("htm" "html" "xhtml"))
(dired-rainbow-define media "#ce5c00" my-dired-media-files-extensions)
; boring regexp due to lack of imagination
(dired-rainbow-define log (:inherit default
:italic t) ".*\\.log")
; highlight executable files, but not directories
(dired-rainbow-define-chmod executable-unix "Green" "-[rw-]+x.*")Putting it all together, the following is a basic setup (essentially a pseudo-port of LS_COLORS obtained by inspecting a terminal and approximating colors with Tailwind CSS).
(use-package dired-rainbow
:config
(progn
(dired-rainbow-define-chmod directory "#6cb2eb" "d.*")
(dired-rainbow-define html "#eb5286" ("css" "less" "sass" "scss" "htm" "html" "jhtm" "mht" "eml" "mustache" "xhtml"))
(dired-rainbow-define xml "#f2d024" ("xml" "xsd" "xsl" "xslt" "wsdl" "bib" "json" "msg" "pgn" "rss" "yaml" "yml" "rdata"))
(dired-rainbow-define document "#9561e2" ("docm" "doc" "docx" "odb" "odt" "pdb" "pdf" "ps" "rtf" "djvu" "epub" "odp" "ppt" "pptx"))
(dired-rainbow-define markdown "#ffed4a" ("org" "etx" "info" "markdown" "md" "mkd" "nfo" "pod" "rst" "tex" "textfile" "txt"))
(dired-rainbow-define database "#6574cd" ("xlsx" "xls" "csv" "accdb" "db" "mdb" "sqlite" "nc"))
(dired-rainbow-define media "#de751f" ("mp3" "mp4" "MP3" "MP4" "avi" "mpeg" "mpg" "flv" "ogg" "mov" "mid" "midi" "wav" "aiff" "flac"))
(dired-rainbow-define image "#f66d9b" ("tiff" "tif" "cdr" "gif" "ico" "jpeg" "jpg" "png" "psd" "eps" "svg"))
(dired-rainbow-define log "#c17d11" ("log"))
(dired-rainbow-define shell "#f6993f" ("awk" "bash" "bat" "sed" "sh" "zsh" "vim"))
(dired-rainbow-define interpreted "#38c172" ("py" "ipynb" "rb" "pl" "t" "msql" "mysql" "pgsql" "sql" "r" "clj" "cljs" "scala" "js"))
(dired-rainbow-define compiled "#4dc0b5" ("asm" "cl" "lisp" "el" "c" "h" "c++" "h++" "hpp" "hxx" "m" "cc" "cs" "cp" "cpp" "go" "f" "for" "ftn" "f90" "f95" "f03" "f08" "s" "rs" "hi" "hs" "pyc" ".java"))
(dired-rainbow-define executable "#8cc4ff" ("exe" "msi"))
(dired-rainbow-define compressed "#51d88a" ("7z" "zip" "bz2" "tgz" "txz" "gz" "xz" "z" "Z" "jar" "war" "ear" "rar" "sar" "xpi" "apk" "xz" "tar"))
(dired-rainbow-define packaged "#faad63" ("deb" "rpm" "apk" "jad" "jar" "cab" "pak" "pk3" "vdf" "vpk" "bsp"))
(dired-rainbow-define encrypted "#ffed4a" ("gpg" "pgp" "asc" "bfe" "enc" "signature" "sig" "p12" "pem"))
(dired-rainbow-define fonts "#6cb2eb" ("afm" "fon" "fnt" "pfb" "pfm" "ttf" "otf"))
(dired-rainbow-define partition "#e3342f" ("dmg" "iso" "bin" "nrg" "qcow" "toast" "vcd" "vmdk" "bak"))
(dired-rainbow-define vc "#0074d9" ("git" "gitignore" "gitattributes" "gitmodules"))
(dired-rainbow-define-chmod executable-unix "#38c172" "-.*x.*")
))Note: the 256 color cheat
sheet includes conversion from
the Xterm colors used by LS_COLORS to the HEX codes used by
dired-rainbow. Using that conversion an enterprising individual with a grasp of sed/awk could put together a
real port of LS_COLORS to dired-rainbow.
There is a related package called diredfl which extracts the extra fontification rules from Dired+ and packages them in a modern Emacsy way. They enhance things like the date face, permissions face and similar. Check it out!
The basic command to work with subdirectories in dired is i,
which inserts the subdirectory as a separate listing in the active
dired buffer.
This package defines function dired-subtree-insert which instead
inserts the subdirectory directly below its line in the original
listing, and indent the listing of subdirectory to resemble a
tree-like structure (somewhat similar to tree(1) except the pretty
graphics). The tree display is somewhat more intuitive than the
default "flat" subdirectory manipulation provided by i.
There are several presentation options and faces you can customize to change the way subtrees are displayed.
You can further remove the unwanted lines from the subtree by using
k command or some of the built-in "focusing" functions, such as
dired-subtree-only-* (see list below).
If you have the package dired-filter, you can additionally filter
the subtrees with global or local filters.
A demo of basic functionality is available on youtube: https://www.youtube.com/watch?v=z26b8HKFsNE
Here's a list of available interactive functions. You can read
more about each one by using the built-in documentation facilities
of emacs. It is adviced to place bindings for these into a
convenient prefix key map, for example C-,
dired-subtree-insertdired-subtree-removedired-subtree-toggledired-subtree-cycledired-subtree-revertdired-subtree-narrowdired-subtree-updired-subtree-downdired-subtree-next-siblingdired-subtree-previous-siblingdired-subtree-beginningdired-subtree-enddired-subtree-mark-subtreedired-subtree-unmark-subtreedired-subtree-only-this-filedired-subtree-only-this-directory
If you have package dired-filter, additional command
dired-subtree-apply-filter is available.
This package implements useful features present in the ranger file manager which are missing in dired.
A feature present in most orthodox file managers is a "two-stage" copy/paste process. Roughly, the user first selects some files, "copies" them into a clipboard and then pastes them to the target location. This workflow is missing in dired.
In dired, user first marks the files, then issues the
dired-do-copy command which prompts for the destination. The
files are then copied there. The dired-dwim-target option makes
this a bit friendlier---if two dired windows are opened, the other
one is automatically the default target.
With the multi-stage operations, you can gather files from multiple dired buffers into a single "clipboard", then copy or move all of them to the target location. Another huge advantage is that if the target dired buffer is already opened, switching to it via ido or ibuffer is often faster than selecting the path.
Call dired-ranger-copy to add marked files (or the file under
point if no files are marked) to the "clipboard". With non-nil
prefix argument, add the marked files to the current clipboard.
Past clipboards are stored in dired-ranger-copy-ring so you can
repeat the past pastes.
Call dired-ranger-paste or dired-ranger-move to copy or move
the files in the current clipboard to the current dired buffer.
With raw prefix argument (usually C-u), the clipboard is not
cleared, so you can repeat the copy operation in another dired
buffer.
Use dired-ranger-bookmark to bookmark current dired buffer. You
can later quickly revisit it by calling
dired-ranger-bookmark-visit.
A bookmark name is any single character, letter, digit or a symbol.
A special bookmark with name dired-ranger-bookmark-LRU represents
the least recently used dired buffer. Its default value is `. If
you bind dired-ranger-bookmark-visit to the same keybinding,
hitting `` will instantly bring you to the previously used dired
buffer. This can be used to toggle between two dired buffers in a
very fast way.
These bookmarks are not persistent. If you want persistent bookmarks use the bookmarks provided by emacs, see (info "(emacs) Bookmarks").
This package provides live filtering of files in dired buffers. In
general, after calling the respective narrowing function you type a
filter string into the minibuffer. After each change the changes
automatically reflect in the buffer. Typing C-g will cancel the
narrowing and restore the original view, typing RET will exit the live
filtering mode and leave the dired buffer in the narrowed state. To
bring it back to the original view, you can call revert-buffer
(usually bound to g).
During the filtering process, several special functions are available.
You can customize the binding by changing dired-narrow-map.
dired-narrow-next-file(<down> or C-n) - move the point to the next filedired-narrow-previous-file(<up> or C-p) - move the point to the previous filedired-narrow-enter-directory(<right> or C-j) - descend into the directory under point and immediately go back to narrowing mode
You can customize what happens after exiting the live filtering mode
by customizing dired-narrow-exit-action.
dired-narrow-exit-action may be executed automatically,
when there is only one file left while narrowing.
In order to enable this feature, add (setq dired-narrow-exit-when-1-left t) to your config.
It makes sense when you use find-file as your exit action, e.g.
(setq dired-narrow-exit-action 'dired-narrow-find-file).
A chosen file will be quickly highlighted before executing dired-narrow-exit-action.
This behavior is controlled by variables dired-narrow-enable-blinking,
dired-narrow-blink-time and by a face dired-narrow-blink.
These narrowing functions are provided:
dired-narrowdired-narrow-regexpdired-narrow-fuzzy
You can also create your own narrowing functions quite easily. To
define new narrowing function, use dired-narrow--internal and
pass it an apropriate filter. The filter should take one argument
which is the filter string from the minibuffer. It is then called
at each line that describes a file with point at the beginning of
the file name. If the filter returns nil, the file is removed from
the view. As an inspiration, look at the built-in functions
mentioned above.
Produce a file listing with a shell incantation and make a dired out of it!
This package provides one principal function, dired-list which
can be used to produce dired buffers from shell programs outputing
text roughly in the format of la -ls.
For most standard output formats the default filter and sentinel should work, but you can also provide your own if the situation requires it.
Most of the time you can pipe a zero-delimited list of files to ls
through xargs(1) using
| xargs -I '{}' -0 ls -l '{}'
which creates a compatible listing. For more information read the
documentation of dired-list, for example by invoking
C-h f dired-list RET
in emacs.
In addition to the generic interface this package implements common listings (patches and extensions welcome!), these are:
dired-list-mpcdired-list-git-ls-filesdired-list-hg-locatedired-list-locatedired-list-find-filedired-list-find-namedired-list-grep
Often times we find ourselves in a situation where a single file or directory is nested in a chain of nested directories with no other content. This is sometimes due to various mandatory layouts demanded by packaging tools or tools generating these deeply-nested "unique" paths to disambiguate architectures or versions (but we often use only one anyway). If the user wants to access these directories they have to quite needlessly drill-down through varying number of "uninteresting" directories to get to the content.
This minor mode is in main inspired by how GitHub renders these paths: if there is a chain of directories where each one only has one child, they are concatenated together and shown on the first level in this collapsed form. When the user clicks this collapsed directory they are immediately brought to the deepest directory with some actual content.
To enable or disable this functionality use dired-collapse-mode to
toggle it for the current dired buffer. To enable the mode globally
in all dired buffers, use global-dired-collapse-mode.
If the deepest directory contains only a single file this file is
displayed instead of the last directory. This way we can get
directly to the file itself. This is often helpful with config
files which are stored in their own directories, for example in
~/.config/foo/config and similar situations.
The files or directories re-inserted in this manner will also have updated permissions, file sizes and modification dates so they truly correspond to the properties of the file being shown.
The path to the deepest file is dimmed with the
dired-collapse-shadow face so that it does not distract but at the
same time is still available for inspection.
The mode is integrated with dired-rainbow so the nested files
are properly colored according to user's rules.
The directory without collapsed path might look something like this:
After collapsing:
