_    _
  ___ | | _| |_ __ _  __ _ ___
 / _ \| |/ / __/ _` |/ _` / __|
| (_) |   <| || (_| | (_| \__ \
 \___/|_|\_\\__\__,_|\__, |___/
                     |___/

NAME

oktags - manage tags on plain old files

SYNOPSIS

Usage: oktags [options]
    -a, --add-tags TAGS FILE         Add comma-separated TAGS to FILE
    -d TAG FILE,                     Delete TAG from FILE
        --delete-tag-from-file
    -i FILE,                         Auto-complete tags and add them to FILE
        --add-tags-interactively
    -l, --list [PATH]                List file tags (optional PATH)
    -r, --rename-tag OLD_TAG NEW_TAG Rename OLD_TAG to NEW_TAG(S) recursively for all files
    -s TAGS [PATH],                  Search files which include (comma-separated) tags recursively (optional PATH)
        --search-files-with-tags

DESCRIPTION

oktags helps you organize your files by managing tags on them. It works by adding/removing at the end of the filename. Given a file cat.jpg, when adding the tags tag1 and tag2, the filename will become cat--[tag1,tag2].jpg. The implementation is OS-agnostic, so it should work on Linux, macOS and Windows.

EXAMPLES

Add tags to a file. Tags are always unique.

$ touch foobar
$ oktags -a tag1 foobar
$ ls foobar*
foobar--[tag1]
$ oktags -a tag2 foobar--\[tag1\]
$ ls foobar*
foobar--[tag1,tag2]
$ oktags -a tag3,tag2 foobar--[tag1,tag2].pdf
$ ls foobar*
foobar--[tag1,tag2,tag3].pdf

Delete a tag from a file.

$ find . | grep business_card | head -n 1
./archiv/Reto_Huber--[business_card,somedia,seo].pdf
$ oktags -d seo ./archiv/Reto_Huber--[business_card,somedia,seo].pdf
$ find . | grep business_card | head -n 1
./archiv/Reto_Huber--[business_card,somedia].pdf

Interactively add tags (with auto-completion through readline) to a file.

$ oktags -i foo
> t[TAB]
tag1  tag2  tag3
> tag2, new tag
$ ls foo* | grep new
foo--[new_tag,tag2]

List all tags in the current folder.

$ touch foo
$ touch bar.txt
$ touch foobar--[tag1,tag2].pdf
$ touch baz--[tag1].txt
$ oktags -l
tag1(2)
tag2(1)

List all tags for a given path glob (assuming the same data set as above).

$ oktags -l '*txt'
tag1(1)

Rename tag.

$ oktags -l
200ok_expense(8)
business_card(4)
$ oktags -r 200ok_expense 200ok,expense
$ oktags -l
expense(8)
200ok(8)
business_card(4)

Search files with tags.

$ oktags -s somedia,seo,business_card
archiv/Reto_Huber--[business_card,seo,somedia].pdf
archiv/Reto_Huber--[business_card,seo,somedia].txt
$ oktags -s business_card '**/*pdf'
archiv/Reto_Huber--[business_card,seo,somedia].pdf
archiv/Stefan_Schmidt--[business_card,lawoon].pdf

INSTALLATION

oktags is implemented in Ruby and can be installed as a gem.

gem install oktags

DEVELOPMENT

oktags is implemented in Ruby, dependencies are managed with bundler.

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To publish a new version, update the version number in version.rb, and then run bundle exec rake publish, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

TESTS

Tests are implemented with RSpec and can be run with bundle exec rspec spec.

NOTES

Software systems come and go. It is easy to lose important data in (proprietary) legacy systems. Plain old files are boring and are therefore here to stay; at least they have been around since 1961. Additional benefits of using plain old files are:

• They are (mostly) platform independent.
• They can be accessed by a wide array of software
  • They do not require a specific UI.
  • They do not require the use a database (apart from the filesystem itself, of course).
• They can be transported independently from the software that captured/created them.
• They are not proprietary.

oktags is decidedly built to be just as boring as plain old files. It’s written in a language that’s been proven for shell scripts (Ruby) rather than using something more ‘cool’/’interesting’. It also only uses Ruby built-ins and has no dependencies when run as a CLI or library. oktags is therefore boring and here to stay. The idea is to tag your files once and for all, so you will not loose your important data in something that will become an unsupported legacy system at some point.

At 200ok, we develop various Free Software projects that work on plain old files:

• organice: An implementation of Org mode without the dependency of Emacs - built for mobile and desktop browsers.
• okdoc: A document scanning and archiving solution (which works well with oktags).

SEE ALSO

tmsu, tagspaces