Tagging

The tagging system in fidx is simple (and limited), but it has one particular quirk which can cause some confusion: Tags are internally associated with hashes, not file entries. This is done based off the assumption that the tags are used to describe the contents of a file, which has two benefits:

  • If a file is renamed1 (without changing its contents) it will not lose its tags.
  • If several files share the same contents, only one will need to be tagged but all of the files will gain the tag(s).

Tags are stored in the fidx tree database, and thus are local to the tree.

Managing tags

In order to tag files there needs to be tags in the database. To add tags use the subcommand add-tag (more than one tag can be added at a time):

$ fidx add-tag some-tag another

(Each tag must be unique).

Once there are tags in the database, use the subcommand list-tags to list them:

$ fidx list-tags
    2 another
    1 some-tag

A tag can be renamed using the rename-tag subcommand. The following would rename a tag called from-name to to-name:

$ fidx rename-tag from-name to-name

(Only one tag can be renamed at a time)

Tags can be removed using the remove-tag subcommand:

$ fidx remove-tag some-tag another

Tagging/Untagging files

Note: It is important to only manage tagging/untagging in a tree which has not been modified since last database update since it associates tags with hashes. Always run and update before managing tag associations in a tree.

To attach one or more tags to a file use the subcommand tag, which takes as its first argument the name of the file to tag, and the remaining arguments are tag names:

$ fidx tag fossil-repos-2020.tar scm fossil source-archives

To inspect what tags a file is associated with use the subcommand tags:

$ fidx tags fossil-repos-2020.tar
list tags for fossil-repos-2020.tar
   2 fossil
   6 scm
   7 source-archives

Removing tags from a file can be done using the untag subcommand, which has the same format as tag; first argument is the file name and the following arguments are the tags to disassociate with that file:

$ fidx untag fossil-repos-2020.tar scm

To search for a file based on tags use the subcommand search:

$ fidx search some-tag another

The search is very basic, and only supports implicit AND boolean searches, meaning that only files with all matching tags will be returned.

1 fidx has no concept of a file/directory rename; it treats renames as a deletion and a new file, where the deletion would cause the tag association to disappear if tags where associated with file entries rather than their contents.