oyepa - a tagging file system (a fake but working one)



Thanks to Johannes Madel, there is now a development Mercurial repository for oeyepa. If you want to hack on oyepa, best to grab the latest version at https://bitbucket.org/majo/oyepa.

more news...

I believe in filenames.

There, I said it.

I think we badly underutilize them as a reliable way to encode document metadata. Yes, we could move the filesystem into a database, or store all sorts of metadata in one (actually, I did the latter a couple of years ago). But we could also just devise simple tools which would help us make better use of filenames. This is my goal with oyepa.

What this page is about:

This is the homepage of oyepa. oyepa is a system which watches specific dirs for newly created documents and prompts you to tag them. You can then run queries on your document collection using a GUI document browser/locator.

Click on the pictures to zoom. In the first image you see the dialog that lets you tag (and rename) a document. It shows up automatically whenever you create a new document. (You have full control over which directories "trigger" this behavior.) The second image shows you the document browser, where you can search your document collection by entering/selecting tags (or any other filename elements). Yes, it looks like an accounting app for Win3.11! But it works pretty well. : )


  • works with documents of any type: text, spreadsheets, images, multimedia files, source code trees, etc
  • automatically prompts you to tag any document you create (but only if that doc is being created in one of the dirs you specified)
  • lets you store directory trees as single documents (think of, e.g., a source code tree, or a set of pictures taken at the same occasion: you just tag the directory itself, not all the files it contains)
  • tag information is stored in the filename, which ensures portability (as long as you don't move your files to filesystems which only support very short filenames) and low risk of losing your documents' metadata (since filesystems don't 'corrupt'/'accidentally delete' the name of a file that often)

  • In case you are wondering:

    I am aware that you don't need this code to insert 'tags' in your filenames and then run searches on them. If you are happier using 'find', stick with it. :-) Actually, this project started out as a simple wrapper around that same command. : ) My goal is to provide an alternative interface to achieve the same effect.

    How to get it running on your computer:

    oyepa was written by Manuel Arriaga and is available as free software: it is distributed under the terms of the GPL v2.

    Version 3.2 can be downloaded from here. <== DOWNLOAD FROM HERE

    Alternatively, you can now get a development version from the Mercurial repository kindly set up by Johannes Madel over here.

    To become the fourth fifth sixth (!) oyepa user on the planet you'll need:

    If you wish to be automatically prompted to tag new documents the moment you create them, you will also need to have installed:



    Thanks to Johannes Madel, there is now a development Mercurial repository for oeyepa. If you want to hack on oyepa, best to grab the latest version at https://bitbucket.org/majo/oyepa.


    Version 3.2 released! Fixed a bug in the code that handles filetype icons and which, on occasion, triggered a segfault.


    Version 3.1 released! The much-improved document browser now shows an icon indicating the type of each document as well as the date of the last modification. (By editing the configuration file cfg.py you can choose to use the "date of last access" instead.) You can also sort the list of results either by document name or by date.


    Version 3.0 released! Added code generously contributed by Tigor Csogor that provides support for recursively watching all dirs underneath a given dir on which you are running oyepa. To achieve that, just finish the dir name (in the file ~/.oyepa-dirs) with '/*'. When oyepa finds that suffix at the end of a dir name, it will watch both that dir as well as all directories underneath it.


    Version 2.9 released! The code in oyepa-filemon.py has been updated so that it works with the most recent releases of pyinotify (>=0.8).


    Version 2.8 released! A new configuration option, DONT_QUIT_INSTEAD_RUN_CMD, allows you to configure which action is triggered by the "leave" button (in search mode). This is neat when you are using oyepa as a music jukebox and want the "Leave" button not to close the application but instead to hibernate the machine (using, as I do, the excellent Tux On Ice).


    Version 2.7 released!

    - Fixed a bug in the install script (new file cfg.py wasn't getting installed).

    - Fixed a bug in the new MusicExtensionsWidget (part of the support for jukebox functionality), in which the getExtensions() method was returning a string as a list of chars rather than as a one-item list of strings.

    - Added a check to the music player (mp.py) so that the user cannot accidentally start multiple instances at the same time.


    Version 2.6 released! This exciting release adds full support for document types which are actually directories on-disk (eg, you can define a ".album" document type and assign an app to open any directory whose name ends in ".album"). Also, many previously hard-coded options have been made configurable (just tweak them in the file cfg.py).

    Finally, a tiny wrapper around the excellent MPlayer has been added as an optional helper to run a oyepa-based (i.e., metadata-in-the-filepaths) jukebox. It works great, and everything you need to run it is oyepa and the awesome MPlayer.


    Version 2.5 released! Fixed a bug which made it impossible to rename tags, improved the wnote applet and made two other minor changes.


    Version 2.4 released! Fixed one bug (which was preventing the document retagging/renaming feature from working) and made several "under-the-hood" improvements. Among the latter: (i) exceptions are now reported through the GUI; (ii) simplified the setup of the file monitor; and (iii) nicer shutdown procedure for the file monitor.


    Version 2.3 released! GUI made friendlier through (i) the use of a status bar (replacing those obtrusive message boxes), (ii) support for deselecting a tag by double-clicking on it (without needing to access the pop-up menu) and (iii) when the user selects a doc, the default app for that document type is listed on the status bar.


    Version 2.2 released! Small fix so that no defunct/zombie processes are left lying around through the continued usage of oyepa.


    Version 2.1 released! Fixed a minor bug which kept the note creation applet from running if the note title contained non-ASCII characters.


    Version 2.0 released! Rewritten almost from scratch, many more features (and a new, just as unpronounceable name, too!).


    Version 1.1 released! Now includes a primitive GUI document locator.


    To ask questions, offer feedback or report bugs just email me (email address found at the bottom of the page).

    Manuel Arriaga - Email me at marriaga followed by @ stern . nyu . edu