NAME

tagit - File tagger


SYNOPSIS

tagit [OPTIONS] [FILE] [TAGS]


DESCRIPTION

TagIT maintains a list of file and tag associations.


OPTIONS

-C
Make -s and -S case insensitive.

-d
Delete the specified tag(s) from an entry.

-D
Delete the specified tag(s) from the database.

-f FILE
Work with FILE.

-F NEW OLD
Reassign a file. The old file can be specified with -i. Use this if a file is moved or -u can't find it. See Updating below.

-h
The command line help text.

-i ID
Work with the file with ID. See File IDs below.

-I
Display the ID when listing files. See File IDs below.

-l
List files matching the specified tag(s) or all files. See Listing Files below.

-m TAG
Add a single tag to multiple files.

-n NOTE
Add or replaces a NOTE on a file.

-N
Delete the note from a file.

-p
Display the full path when listing files.

-q
Quiet. Only print warnings.

-r OLD NEW
Rename a tag. This will also merge tags.

-R
Replace a files tag(s) with those specified.

-s REGEXP
Search for a file, including path with -p, matching a pattern. See Searching below.

-S REGEXP
Search for files with notes matching a pattern. See Searching below.

-t
List all known tags and the number of files they apply to. See Listing Tags below.

-T
The same as -t but sort by file count instead of tag name. See Listing Tags below.

-u
Update the database. Use this if files have been renamed. See Updating below.

-v
Print the current version and exit.

-x
Remove the file from the database.

-Z FILE
Use FILE as the database. Defaults to '$DB_FILE'.

Tags

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.

Taging Files

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.

File IDs

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.

Listing Files

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.

Listing Tags

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.

Searching

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.

Updating

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.


FILES

.tagit.db
The TagIT database. This is a Berkeley DB.

.tagit.lck
The lock file for the database. This always contains the PID and UID of the TagIT instance that used it and date and time it was used.

Database Format

File:
FILE_{ID} -> device#inode#mode#Path#Name#Tags IDs

% is replaced with %% and # is replaced with %+.

File Index:
INDEX_{File Path} -> File ID

File Inode:
INODE_{device#inode} -> File ID

Note:
NOTE_{File ID} -> Note Text

Tag ID:
TAG_{ID} -> Name

Tag Name:
NAME_{Name} -> ID:File IDs

Counters:
FILEID -> Next file ID.

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.


PORTABILITY

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.


HOME

http://lorance.freeshell.org/tagit/


COPYRIGHT

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.


AUTHOR

Written by Lorance Stinson <LoranceStinson+tagit@gmail.com>