- Use the Source, Luke
Home | Register | News | Forums | Guide | MyLinks | Bookmark

Sponsored Links

Latest News
  General News
  Press Releases
  Off Topic

Back to files

tagji - a way to organize (and locate) your documents through ----- the use of tags

Written by Manuel Arriaga (

Copyright (C) 2006 Manuel Arriaga Licensed under the GNU General Public License version 2. See the file COPYING for details.

Version: 1.1 (2006/Nov/13)


tagji is useless for you if you don't do all your work from within an X session. That is because tagging is done through a X dialog; if you are not running X, you won't get the dialog and hence won't tag any document you create.


  • Python (known to work with 2.5)
  • Linux >= 2.6.13 compiled with inotify support
  • Qt 4.2


  1. run

$ ./

then, as root,

# ./ install

You can also do a local installation in your home dir; just place the executable files (including tagji_gui/tagji) somewhere in your path.

2) create a file ~/.tagji-dirs listing the dirs on which you want tagji to operate. These paths can be either absolute or relative (to your home dir).

3) for convenience, create a script you will invoke to start X. If (like I do), you call startx from ~/.bash_profile or some other script which gets automatically run every time you log in, modify it instead. In any case, what you need is to invoke three commands

DISPLAY=:0.0 & startx -stop

You can, e.g., just throw them in a file called 'x', make it executable and invoke 'x' rather than 'startx'. Or just create a shell alias for startx.

The idea is simple: you need to start the file monitor before your X session begins, and stop it once the session ends. I tried doing this from ~/.xinitrc but didn't succeed (meaning that for some reason the file monitor was not being correctly shut down).


1 - the ampersand ('&') in the first command is important, otherwise X won't start.

2- it is important to set the env var DISPLAY correctly for tagji to work correctly. On my machine ':0.0' works; if it doesn't on yours, just use the value shown by running

$ set | grep DISPLAY

on an xterm.

4) You are hopefully done!

Running tagji

Every file you save inside one of the dirs listed in ~/.tagji-dirs will bring up a dialog prompting you to tag it. (You can also rename that document by pressing Alt-C.) When you are done, just press (or Alt-Q) "Done". This is the way for you to provide metadata about your docs at the time you save them.

An alternative, particularly useful for importing your documents into tagji, is simply to move files into a dir being watched by tagji. The dialog box prompting you to tag those files will also be shown on those occasions.

On my computer, I have just a handful of dirs being watched (e.g., "deliverables" for stuff I hand in/(e)mail to someone else; "notes" for notes I have taken"; etc). I save all my files to these dirs and then tag them.

Notice that tagji does not look for the creation of new files inside directories which lie underneath those listed in ~/.tagji-dirs (i.e., it watches those dirs but "not recursively"). This allows the treatment of a directory (and all its content) as if it were a single document: e.g., you can have an entire source code tree, or a directory full of pictures from the same occasion, be tagged (and come up in the search results for any of those tags) without having to manually tag all the files inside that dir. Furthermore, since tagji never introduces any changes to the contents of a dir stored "as a document", you can rest assured that, e.g., a source code tree will not be affected in any way by being stored inside a tagji dir.

To make use of this feature, just try moving a directory containing a set of pictures or source files into a directory watched by tagji. You will be prompted to tag the directory itself, not the individual files it contains. Suppose you tag the directory with 'tag1'. Now, when you run a search for files of type 'jpeg' and tagged with 'tag1' that dir will match, since (i) it is tagged with 'tag1' and (ii) it contains files with the extension 'jpeg'. (The latter, matching extensions within directories, is done automatically; when tagging a directory you do not need to specify which kinds of files it contains.)

ACTUALLY running tagji...

In general, you will only want to invoke a single command: 'tagji'.

If called without any arguments, it will bring up the (admittedly ugly!) GUI browser/document locator. When you have located the doc you wish to open in the "Matching docs" list, just highlight it and hit 'enter'/'return'. You will be prompted to enter the name of the app with which it should be opened. By default, if you just enter the name of an app (possibly followed by some command line arguments) the path of the file will be automatically appended to the command string you provide before it is executed. This works for most apps. If you need to execute a command where the filename of the document should show up somewhere other than at the end of the command, just replace it with a percentage sign. Eg, to copy the doc to /home/m/tmp, you would enter the command

cp % /home/m/tmp

(I am aware that this interface could be a lot friendlier; if you would like to help with it, just get in touch!)

More useful stuff to keep in mind while using this code:

  • If you call 'tagji' followed by a filepath, it will bring up a dialog which allows you to rename and/or retag that document.
  • To DEselect a tag, highlight it in the "selected tags" list and press either 'd' or the 'delete' key.
  • If you need to rename a tag (and have the metadata of all docs to which it has been attached updated), currently you can only do it from the command line using the 'tagji-rentag' command.

See the file tagji-search.txt for some guidance on how to perform searches from the CLI.

That is it!

How does it work

Tagji "attaches" tags to a document in the most trivial way: by inserting them into the document's filename. Yes, this places a limit on how many tags you can add to a document (and how long those tags can be). This is the only way I found of appending tags to a document which respects two simple design goals: (i) to keep the tags "with the document" as much as possible subject to (ii) never modifying the file itself. Basically, I didn't want to concentrate all metadata on a single, external file liable to deletion and/or corruption. The only alternative that I know of -- placing this metadata into file attributes, which some filesystems support -- was ruled out since this attributes currently are very fragile (both portability across filesystems as well as support from common archiving tools are issues). In my usage of tagji the restriction on filename length has never been a problem; your mileage may vary.

Also note that when you "tag" a document the file itself is never immediately renamed: we simply create a symlink to the original file using the new filename for that document. The file is only actually renamed when you quit your X session and the file monitor (tagji_filemon) is stopped; that occasion is assumed to be safe for the rename operation, meaning that we expect no applications to have that file open (and possibly notice that the file they were previously writing to no longer exists).

Other stuff

This code is admittedly ugly. Through a succession of historical accidents it is a mixture of mindless C++ and Python, the GUI just wrapping around command line utilities which iterate over all items in several directories every time the GUI asks for an update. One day I will get around to rewriting it, probably using Python together with one of its GUI toolkits.


tagji was written by me, Manuel Arriaga. Feel free to contact me at with questions, suggestions, bug reports or wathever else crosses your mind.

Sponsored Links

Discussion Groups
  Networking / Security

About | FAQ | Privacy | Awards | Contact
Comments to the webmaster are welcome.
Copyright 2006 All rights reserved.