Tagging a file happens when we copy that file under the store/ directory. The path we copy the file in tells which tags are applied to the file. More than one tag can be applied to a file at the same time and the same file can be tagged twice or more.

As a first test, we use the movie "First Contact" and tag it as startrek by copying it inside the proper tag. The command is:

$ cp first_contact.avi ~/myfiles/store/startrek/@/

Split the path in its logical components to understand what is happening. We have:

1. ~/myfiles: this is the mountpoint
2. store/: this clearly says we are tagging something
3. startrek/: this is the list (a one element list) of tags we are applying to the file. This is also called the query part.
4. @/: a conventional marker to end the query

Now let's check our file is where we put it:

$ ls ~/myfiles/store/startrek/@/
first_contact.avi

The @/ element is always used at the end of the tag list (the query) when we are asking Tagsistant to locate a file or to tag a file. Without the @/ mark, Tagsistant will assume that we are still building the query. A query without a @/ mark is called an incomplete query and can't be processed for looking up files.

This is a schema of the query:

To make a little more meaningful the role of @/, we'll now use the file we have just tagged with a media player:

$ mplayer ~/myfiles/store/startrek/@/first_contact.avi

Try to imagine how the path would look without the @/ mark. How could Tagsistant know that first_contact.avi is a filename and not another tag? It just can't. That's why a query must be completed by @/ to locate a file.

In the next example we use more than one tag:

$ cp the_wrath_of_khan.avi ~/myfiles/store/startrek/video/@

Translated in English this sounds like tag the movie "The Wrath of Khan" as both 'startrek' and 'video'. In this query the parts of our list are:

1. ~/myfiles: this is the mountpoint
2. store/: this clearly says we are tagging something
3. startrek/video/: two tags are being applied to the same file at once
4. @/: a conventional marker to end the query

And this is the query schema:

You will now find the file "the_wrath_of_khan.avi" inside store/video/@/, store/startrek/@/, store/video/startrek/@/ and store/startrek/video/@/. The last two queries are totally equivalent. But wait! We taught Tagsistant that scifi/ includes startrek/, so we expect to see that file in store/scifi/@/ too:

$ ls ~/myfiles/store/scifi/@/
first_contact.avi the_wrath_of_khan.avi

Yes, both startrek movies are there! That's because Tagsistant has an internal reasoner which uses the relations you provide to include files not directly tagged (remember? this is what we called inherent tagging). Now let's tag something else:

$ cp the_empire_strikes_back.avi ~/myfiles/store/starwars/@/
$ ls ~/myfiles/store/scifi/@/
first_contact.avi  the_wrath_of_khan.avi  the_empire_strikes_back.avi

No files are directly tagged as scifi/ but since that tag includes both startrek/ and starwars/ now it features three files. The real benefits of using relations are:

1. reducing the length of your queries
2. avoid re-tagging and over-tagging your files

Both save your time.