Apparix: augmenting the command-line with directory bookmarks, distant listing, and distant editing

A pure shell implementation of apparix is now available.


Apparix allows fast command-line file system navigation in both bash and zsh by bookmarking directories and jumping to a bookmark directly, supported by tab completion. In its most powerful form it is used like this:

to mcl e<TAB>

The apparix command for jumping to a bookmark is called to. In this example the bookmark mcl is specified. It is possible to change directory to the path associated with this bookmark directly. However, in the above invocation a further subdirectory of the bookmark is specified using tab-completion, for example expanding to to mcl example. Once selected (by pressing <ENTER>) the result is a change of directory to /path/associated/with/bookmark/mcl/example.

A common way of organising files is to have projects and sub-projects associated with certain locations in the file system. Such a location might then have subdirectories such as bin, data, archive, doc, examples, et cetera. Apparix works particularly well in such a layout in conjunction with cyclic tab completion, in bash achieved by bind '"\t":menu-complete'. Bookmarks can be used as entry points into other parts of the filesystem, with tab completion working completely transparently. It is possible to navigate to sibling directories of a bookmark. The following completes on directories that are at the same level as the one bookmarked by mcl and have a name starting with z.

to mcl ../z<TAB>

By default to can use both bookmarks and regular directory names and path names as targets. All three modes, bookmarks, regular directories, and subdirectories of bookmarks, allow tab completion on the query string. Additionally, apparix supplies commands ae (apparix edit) and als (apparix ls) that can be used to invoke distant edit or listing commands on files and subdirectories in bookmarked locations. Most importantly, is is easy to create small custom shell scripts such as ae and als yourself, using the principle of embrace and extend. Examples:

to mcl

Change directory to the location bookmarked by mcl, say /nfs/cvs/mic/mcl/.

to mcl doc

Change directory to a subdirectory of that, /nfs/cvs/mic/mcl/doc.

to mcl doc/test

Change directory to a further subdirectory, /nfs/cvs/mic/mcl/doc/test.

to mcl <TAB> to mcl d<TAB> to mcl doc/te<TAB>

The first will generate directory completions for /nfs/cvs/mic/mcl/, the second for /nfs/cvs/mic/mcl/d, the third for /nfs/cvs/mic/mcl/doc/te.

als mcl als mcl doc

List the contents of /nfs/cvs/mic/mcl, /nfs/cvs/mic/mcl/doc, respectively. Tab completion acts as for to.

ae mcl TODO

Edit /nfs/cvs/mic/mcl/TODO. Tab completion generates all files in the target directory matching the query pattern.

ae mcl doc/TODO

Edit /nfs/cvs/mic/mcl/doc/TODO.

todo mcl todo mcl doc clog mcl

Edit /nfs/cvs/mic/mcl/TODO, /nfs/cvs/mic/mcl/TODO, /nfs/cvs/mic/mcl/ChangeLog, respectively. It depends on the user appreciation and needs whether such custom edit commands are useful or not.

Finally, the portal command can be used to add all subdirectories of a given directory as locations bookmarked by their relative name. It is described in the apparix manual page.

29 Jul 18

There is now a pure-shell implementation of apparix. It is a lot easier to use as it requires only a single file of bash/zsh code. Follow the link to download it, and for more information go here.

6 Jun 18

The world stood still as zsh completion for apparix was finally created. After some fast-paced development by Izaak van Dongen, an elegant solution was obtained. You can look at the upstream ZSH completion code here. This code is maximally clean, but may (very rarely) not work out of the box on systems with very old bash (completion) versions due to the use of the _filedir completion function. This slightly modified version has a larger chance of working on very old systems. In either case, follow the few instructions at the top of the file.

Izaak additionally rewrote the bash completion code using more idiomatic bash compgen code. As a result completion on files with for example ae (apparix editing of distant files) works as it should without producing a trailing slash on the file to be edited.

Another recent improvement (July 2018) is that apparix should work additionally when spaces are present in directory names or file names. All these changes are entirely in the apparix shell completion function, independent of apparix itself.

3 Mar 11

The shell code (not shipped with apparix, obtain from github here) now makes avaiable a function called whence. Use it for bookmarks that have multiple definitions from which you wish to choose one other than the default (which is the one last defined). This is typically used for a bookmark called now, as discussed above. Issuing whence now will present you with a menu from which to choose your destination. It is possible to bypass the menu by issuing whence now N where N is an index as would be presented by the menu. This functionality depends on a new apparix option, hence a version of apparix as recent as 11-062 is required.

15 Jul 09

The als function (distant listing with apparix) was updated. You can now use shell expansion characters in the string optionally specified after the bookmark:

(/homes/svd) als a 'src/*.c' /homes/svd/apparix/apparix/src/apparix.c

It is necessary to quote patterns containing shell wildcards in order to prevent the current shell from trying to expand them. Find the als function here, and note that its definition is quite simple. It is easy to further customize apparix by deriving or creating your own variants of als-type bash functions.

Get apparix

Download the apparix source code

Download the file with shell functions for both bash and zsh - instructions are included. Use these (newer) definitions rather than the output obtained from apparix --shell-examples (which is what the manual recommends). The upcoming release of apparix will update the built-in shell functions, but for now use the link above.



Get the most out of apparix

Bookmark projects, use subdirectory specification as in to proj data.

For subdirectory specification use tab completion.

Use now to bookmark sudden hotspots of activity and unexpected projects. Keep all now bookmarks, they mark the occasions which put you off track and will help you find those off-track locations later.

Use apparix as a clipboard for directories, avoiding cumbersome pwd invocations followed by copy/paste. It is common to have two terminals, one in the destination directory, one in the source directory. In the destination terminal issue bm dst, then in the source terminal issue cp somefile $(a dst).

to foo .. and to foo ../bar work and change to the parent directory and sibling directory respectively.

Use todo proj to edit the TODO file for the project bookmarked proj.

Apparix shell functions

As of 6 June 2018 apparix supports both bash and zsh. The easiest method for installing shell functions for either is to download this apparix shell function file and follow the instructions at the top. The file works for both bash and zsh.

The functionality for CSH-like shells is much more limited in comparison, mainly because of its deficiencies as a scripting language, or perhaps because of my lack of ability. It is available here.


Apparix was inspired by cdargs. The HISTORY section in the manual has a few more remarks on that. The CDargs homepage lists two more cd-related applications. These are

wcd — wherever CD. This utility will scan any filesystem you throw at it. It is then possible to change/search directory by pattern and do a hundred things more. It was pointed out to me that on some Unix/Linux flavours locate does to a very large extent the same thing as wcd does - in creating a database describing file systems. Combine the locate resources with standard UNIX utilities such as grep in a small script such as goto, throw in CDargs or apparix, and your setup is small, adaptible, powerful, and uses existing resources. Still, I've tried wcd and it delivers what it promises.

kcdk CD. Seems similar to CDargs. I've not been able to track the meaning of k. Possibly it is just the first initial of the author, Kriang Lerdsuwanakij. Hopefully it is not in the long and lamentable tradition of KDE kapplikations with klunky knames.

See also Sitaram Chamarty's bash goto functions.

cd -

takes you to the previous directory. The apparix equivalent is to - and does the same.

cd `pwd`

erases any symlink side-effects that your path may suffer from. Well, that's what I thought. I've now found a a more correct statement is pwd may erase symlink side-effects that your path suffers from.

Pattern-based cd with goto

Sitaram Chamarty wrote a bash goto function that leverages the locate database or a user-created dump of file system locations. This is very useful for a) browsing and searching (new) file systems b) visiting locations in a hugely branched file hierarchy or when you want to range over many destinations (so that the bookmark approach is not a good fit) c) on systems where you somehow have such a minimal presence that you do not want to bother installing whatever file system navigation tools you normally use.

It is possible to ask for locations by directory name pattern and file name pattern, and it is possible to restrict matches to a specified directory that will act as root for the query.

goto can be thought of as a very convenient chimera of find and cd. It is complementary to bookmarking in that the latter provides unambiguous and instantaneous change of directory to what is presumably an oft-visited hotspot, where the mark is independent of its associated destination. goto can take you anywhere but may require zooming in by means of a selection menu, depending on the distinctiveness of the query string. The latter is used to match destinations directly.

Go to Sitaram's goto page.