https://github.com/200ok-ch/oktags
Manage tags on plain old files
https://github.com/200ok-ch/oktags
commandline filesystem ruby tagging
Last synced: 11 months ago
JSON representation
Manage tags on plain old files
- Host: GitHub
- URL: https://github.com/200ok-ch/oktags
- Owner: 200ok-ch
- License: agpl-3.0
- Created: 2020-10-14T12:38:59.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2025-01-06T10:07:27.000Z (over 1 year ago)
- Last Synced: 2025-07-04T14:38:17.997Z (12 months ago)
- Topics: commandline, filesystem, ruby, tagging
- Language: Ruby
- Homepage: https://200ok.ch
- Size: 89.8 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.org
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
#+begin_example
_ _
___ | | _| |_ __ _ __ _ ___
/ _ \| |/ / __/ _` |/ _` / __|
| (_) | <| || (_| | (_| \__ \
\___/|_|\_\\__\__,_|\__, |___/
|___/
#+end_example
#+html: 
#+html: 
* NAME
=oktags= - manage tags on plain old files
* SYNOPSIS
#+begin_example
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
#+end_example
* 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.
#+begin_example
$ 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
#+end_example
Delete a tag from a file.
#+begin_example
$ 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
#+end_example
Interactively add tags (with auto-completion through readline) to a file.
#+begin_example
$ oktags -i foo
> t[TAB]
tag1 tag2 tag3
> tag2, new tag
$ ls foo* | grep new
foo--[new_tag,tag2]
#+end_example
List all tags in the current folder.
#+begin_example
$ touch foo
$ touch bar.txt
$ touch foobar--[tag1,tag2].pdf
$ touch baz--[tag1].txt
$ oktags -l
tag1(2)
tag2(1)
#+end_example
List all tags for a given path glob (assuming the same data set as above).
#+begin_example
$ oktags -l '*txt'
tag1(1)
#+end_example
Rename tag.
#+begin_example
$ oktags -l
200ok_expense(8)
business_card(4)
$ oktags -r 200ok_expense 200ok,expense
$ oktags -l
expense(8)
200ok(8)
business_card(4)
#+end_example
Search files with tags.
#+begin_example
$ 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
#+end_example
* INSTALLATION
=oktags= is implemented in [[https://www.ruby-lang.org/en/][Ruby]] and can be installed as a [[https://rubygems.org/][gem]].
#+begin_example
gem install oktags
#+end_example
* DEVELOPMENT
=oktags= is implemented in [[https://www.ruby-lang.org/en/][Ruby]], dependencies are managed with [[https://bundler.io/][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 [[https://rubygems.org][rubygems.org]].
* TESTS
Tests are implemented with [[https://rspec.info/][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 [[https://en.wikipedia.org/wiki/Computer_file#Storage][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 ([[https://www.ruby-lang.org/en/][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 [[https://200ok.ch/][200ok]], we develop various Free Software projects that work on plain
old files:
- [[https://github.com/200ok-ch/organice/][organice]]: An implementation of Org mode without the dependency of
Emacs - built for mobile and desktop browsers.
- [[https://github.com/200ok-ch/okdoc][okdoc]]: A document scanning and archiving solution (which works well
with =oktags=).
* SEE ALSO
[[http://tmsu.org/][tmsu]], [[https://www.tagspaces.org/][tagspaces]]