squaretag
squaretag copied to clipboard
mdom
Tag files using just the file name
=pod
=for html 
=head1 NAME
squaretag - tag files by using filenames
=head1 SYNOPSIS
squaretag [-s SEP] [-r] add [-v] [-n] [-f] TAG [[FILES...]] squaretag [-s SEP] [-r] remove [-v] [-n] [-f] TAG [[FILES...]] squaretag [-r] clear [-v] [-n] [-f] [[FILES...]] squaretag [-s SEP] [-r] rename [-v] [-n] [-f] OLD_TAG NEW_TAG [[FILES...]] squaretag [-s SEP] [-r] list [[FILES...]] squaretag [-s SEP] [-r] search [-I REGEX] SEARCH [[FILES...]] squaretag [-r] untagged [[FILES...]]
=head1 DESCRIPTION
Squaretag helps you to organize your files by tagging them. The tags are saved in the filename by adding all tags in square brackets either at the end of the filename or just before the last dot.
=head1 EXAMPLES
Suppose the current directory contains the following files:
$ squaretag untagged picture01.jpg picture02
Now you want to add the tag I
$ squaretag add -v family picture01.jpg -> picture01[family].jpg picture02 -> picture02[family]
Files can have multiple tags
$ squaretag add -v myself picture01[family].jpg picture01[family].jpg -> picture01[family,myself].jpg
You can rename single tags
$ squaretag rename -v myself me picture01[family,myself].jpg picture01[family,myself].jpg -> picture01[family,me].jpg
Or delete a tag
$ squaretag remove me -v picture01[family,me].jpg picture01[family,me].jpg -> picture01[family].jpg
And what would tags be good for if you couldn't search for them
$ squaretag search 'family && !me' picture02[family]
And if you have enough, you can simple clear all tags
$ squaretag clear picture01[family].jpg -> picture01.jpg picture02[family] -> picture02
Tags can also have values:
$ squaretag add read=2016 book.epub $ squaretag search 'read>2010' books[read=2016].epub $ squaretag search 'read<2010' $ squaretag search 'read=2016' books[read=2016].epub
=head1 COMMANDS
=over 4
=item add TAG [FILES...]
Add TAG to FILES. TAG is a comma seperated list of tags to add. If a tag has a suffix of I<-> this tag will be removed from the file.
=item remove TAG [FILES...]
Remove TAG from FILES. TAG is a comma seperated list of tags to remove. If a tag has a suffix of I<+> this tag will be added to the file.
=item search SPEC [FILES...]
List all FILES that match the search SPEC. SPEC can contain tags and the usual boolean operators.
For example:
read && good !read || (not_read && prio )
There are four additional operators I<E
The function I<tagged()> returns true if the file has any explicit tags, I<implicit()> if it has any implicit tags.
=over 4
=item I<=>
Compares if operands are string-equal.
=item I<E
Numerical less-than or more-than comparison.
=item I<~>
Checks if left operand contains right operand as substring.
=back
=item clear [FILES...]
Remove all tags from FILES.
=item sort [FILES...]
Sort tags in all FILES with tags.
=item rename OLD_TAG NEW_TAG [FILES...]
Rename OLD_TAG in NEW_TAG in all FILES.
=item list [FILES...]
List and count all tags for FILES. The tags are sorted in descending order of frequency.
=item untagged [FILES...]
List all FILES without a tag.
=back
=head1 OPTIONS
=over 4
=item --verbose|-v
Print what squaretag does.
=item --dry-run|-n
Just print which files squaretag would rename without doing it.
=item --force
Ignore warnings about tags that look like files and overwriting existing files.
=item --separator=SEP|-s=SEP
The string to separate tags. Defaults to I<,>.
=item --recursive|-r
Recurse into subdirectories.
=item --extensions=LIST
A comma separated list of extensions that are recognized by squartag. The leading dot is implied. This is only needed for extensions with a dot in them, normal extensions are handled by squartag without the need to specify them.
=item --implicit=REGEX|-I=REGEX
Apply regex to the basename of the file without its tags. All matched capture groups are added as tags with less precedence than the explicit tags.
For example, if regex is '^(?
=back
=head1 CONFIGURATION FILE
squaretag will try to read I<$HOME/.squaretagrc> on startup. Empty lines are ignored, as is everything after I<#>. Everything else is a key-value combination separated by a equal sign. All options can be set. Quoting is optional, except to save trailings whitespace.
separator = " " # by space! force = 1
=head1 RATIONALE
Tagging files in a way that tags are preserved cross-platform or even cross-filesystem seems to be a hard problem with no clear cut solution.
=head2 Fileformat
Some file formats as mp3 or pdf support saving tags inside the files but there a a lot (probably most) that don't. And even the former need special programs to do that.
=head2 Filesystem
Many modern file systems support tags and special meta data streams, but the tags are most likely lost when you copy files from one file system to the next.
=head2 External database
Keeping the tags in a external database requires a sync step after moving or deleting files. This is harder than it sounds, you probably need the keep checksums to reckognize known files after a rename.
=head2 Filename
All filesystems limit the length of the filename, so the number of tags you can save per file is also limited. And even before you reach the limit, the filename will be hard to read.
But at least it works for all kinds of files, it not dependent on your file or operating sytemen is does not need external tools or syncing steps.
=head1 SEE ALSO
L<tmsu|http://tmsu.org/>, L<tagspaces|https://www.tagspaces.org/>
=head1 COPYRIGHT AND LICENSE
Copyright 2016 Mario Domgoergen C<< [email protected] >>
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
mdom