tagit - File tagger
tagit [OPTIONS] [FILE] [TAGS]
TagIT maintains a list of file and tag associations.
tag(s) from an entry.
tag(s) from the database.
tag(s) or all files.
See Listing Files below.
tag(s) with those specified.
Tags can be any text you like. There is no built in restriction on the characters a tag can be composed of. Some care in choosing tag names should be exercised though. Picking spaces or any character that has to be quoted can quickly lead to option fatigue. If the tag database is to be shared amongst users be considerate of their use and any characters their shell may consider special.
To tag a file, or add more tags to it, give TagIT the file name then the tags you want to associate with the file. The file will be added to the database and associated with all tags specified. Deleting tags from a file or replacing the tags associated with a file are done the same way but using either -d or -R respectively.
Multiple files can be added and tagged at once by using the -m option. For
example tagit -m Text *.txt will tag all files ending in .txt with the
tag Text.
Since TagIT has the ability to tag multiple files with the same name it works internally with the absolute path of each file. To work with a file you must specify the full or relative path to the file or the file needs to be in the current directory. To make life easier each file has a unique ID. Use the option -I to display each file's ID when listing or searching files. To work with a specific file by its ID use the option -i.
With no options, tags or a file TagIT will display all of the files in the database along with the tags associated with them. With a file name it will list only that file. And with a tag or tags it will list all files associated with that tag or tags.
Note: TagIT will attempt to figure out what you mean on it's own. If the first non option word matches a file it will assume you are working with that file. If you really meant to list tags use the -l option to override this behavior. This can be worse on Mac OS X since the file system is case insensitive.
TagIT will list the files in a directory that are in the database, and the
tags associated with them, if the file name # is given. This also works
with the -l option. To override this behavior and tread # as a file to
operate on use the -f option. For example the command line tagit ~/#
will list all the files in your home directory that are in the database and
tagit # will do the same for the current directory. This will only list
files that are present in the current directory and can be found in the
database. If a file was deleted, moved or renamed and not corrected in the
database the file will not be listed.
The options -t and -T list the tags in the database and the number of files associated with them. -t sorts the results by name and -T sorts the results by file count. If tags are given on the command line the only those tags are listed.
By default search results from -s and -S are sorted then printed. If one
of the options -d, -n, -N, -x or -R is used the search results
are not sorted and the action defined by the option are applied to the
resulting files. This also applies to any tags that are specified on the
command line. For example the command line
tagit -C -s foo -n 'Do I really need all these foo files?'
will add the note ``Do I really need all these foo files'' to all files that
match /foo/i. And tagit -C -s foo Foo_Files Delete will add the tags
Foo_FileS and Delete to all files that match /foo/i.
Searches use the built-in Perl regular expressions. To search for plain text use the quoting operator \Q. If you wish to utilize any of the i, m, s or x modifiers use the (?) operator, see the perlre man page for more information. Case insensitivity can also be specified with the -C option.
TagIT will do it's best to keep up with files. It stores the device id and
inode along with the full path to the file. If a files inode changes it will
update the database any it's entry is touched. If a files name changes but
it's inode stays the same it's name in the database will be updated. This one
is a bit trickier. It relies on the file being operated on. Using the option
-u will always fix either for all files if it can. If a file is changed and
TagIT can no longer identify it simple use the -F option, eg tagit -F
new.file old.file and it will replace the old file entry with the new file.
% is replaced with %% and # is replaced with %+.
TAGID -> Next tag ID.
FILES -> The number of files in the database.
TAGS -> The number of tags in the database.
Option -Y will dump the database in a text format. Use this if you want to hack TagIT and need to know more about the database.
I have attempted to make TagIT as portable as possible. Most directory and file routines use portable functions and avoid manipulating paths. The only exception to this is the part that expands a '~' into a path. First it tries the perl function glob. If that fails it tries some Unix centric code taken from the Perl Cookbook. Avoid using the '~' as the first character in a path if it does not make sense on your system. It might cause problem.
TagIT has only been tested on Mac OS X Panther, Linux and Windows running cygwin.
note: While path handling is done in a portable way it is stored in a native format in the database. Using a database on a system with a different path scheme than the system it was created on will not work. This may be addressed in the future should it prove to be a problem.
http://lorance.freeshell.org/tagit/
Copyright (C) 2007 Lorance Stinson All rights reserved. This script is free software. It may be copied or modified according to the same terms as Perl itself.
Written by Lorance Stinson <LoranceStinson+tagit@gmail.com>