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

Apparix allows fast command-line file system navigation 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.

3 Mar 11

The bash code (not shipped with apparix, obtain from 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






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.

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.

Use clog proj to edit the ChangeLog file for the project bookmarked proj.

Apparix shell functions

Apparix can be invoked with the option --shell-examples to get basic functions for bookmarking and jumping. However, I've added a few other functions that people may find useful, and changes to these functions occur more often than changes to apparix itself. The extended set of bash functions is available here. It is recommended to name this file for example .bash_apparix in your $HOME directory and to put the line source $HOME/.bash_apparix in your $HOME/.bashrc file.

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.

I've had requests for ZSH apparix support. If someone writes it, please let me know. The same applies to any shell, of course.


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.