TAGCOLL(1)

📦 version 2.0.14, in ubuntu jammy

💖 TAGCOLL 💖

okay bestie, welcome to tagcoll from the General Commands Manual section — the girlies call her tagcoll(1) ✨ she does various operations on a tagged collection, and honestly? she ate.

🎀 NAME 🎀

tagcoll — Perform various operations on a tagged collection 🫶

✨ SYNOPSIS ✨

tagcoll [options] <command> [options and arguments]

like. options, then a command, then more options and arguments. that's the whole vibe. 💅

🌸 DESCRIPTION 🌸

so tagcoll is a commandline utility to manage tagged collections. no cap.

a tagged collection is a set of items where each item is associated with a set of zero or more tags, in no particular order. zero bestie. an item can just be out here with no tags. it's giving minimalist. 🙈

and then tagcoll can take that collection and do various complex operations on it, like:

  • applying transformations 🔥
  • finding implicit implications between tags 👀
  • building a smart intuitive hierarchy to navigate the items 👑

it's lowkey a whole personality. ✨

👑 COMMANDS 👑

tagcoll accepts a non-switch argument, and that argument tells her what operation should be performed. main character decision fr fr. 💅

  • help [command] — with no arguments, print a summary of available commands. if you hand her a command name as argument, she prints detailed informations about that command. (yes, "informations". she said what she said. 🎀)
  • copy or cat [files...] — output the normalized collection on standard output, applying transformations if requested. this is the default action if no other switches are provided. and a normalized collection is a collection in which an item appears in just one line. one line per item. no duplicates, no chaos. slay. ✨
  • reverse [files...] — output the inbound collection "reversed" from the tags point of view, that is, associating to each tag the list of items associated to it in the input. the --untagged-tag switch can be used to provide a name to which untagged items will be associated in the output. (the untagged girlies finally get a home 🥹)
  • diff <file1> <file2> — output a tag patch file with the differences between two files (requires two file arguments, so don't try it with one, she WILL notice 😭). the output tag patch file can then be applied when reading a collection with the --patch-with option.
  • related <item> [files...] — output a list of the items that are related to the given item or list of items. if more than one items are to be specified, separate them with commas. the --distance option can be used to control how closely related the output items shold be from the item(s) specified. (yes the manual says "shold". we keep it. it's iconic. 💀)
  • implications [files...] — output a list of all implicit implications between tags contained in the hierarchy. implication is defined such that tag A implies tag B if every item tagged with A is also tagged with B. implications can be used to discover implicit hierarchical relationships between tags. the output is one line per tag, with just tags that have implications, with the name of the package, a colon and a comma-separated list of all implied tags. so it's giving package: tag1,tag2,tag3. iykyk. 🦋
  • hierarchy [files...] — organize the collection in an intuitively navigable hierarchy. the output is one line per package, with the package name prepended by the path to the item in the hierarchy. a detailed description of the hierarchy generation algorithm is found in the tagbk-draft.pdf draft paper available in this package; if you want to understand what are the goals of the algorithm and how it works, please give it a read. (bestie. read the pdf. it's right there. 🫶)
  • cleanhierarchy [files...] — like hiearchy, but in every node it merges tags which are attached to the same set of items. (and yes, the original spells it "hiearchy" up in there, so we're keeping the typo exactly as it lives. character for character. 💅)
  • dischierarchy [files...] — the tree starts with an empty tag set, and branches with the most discriminant tags. empty start, most discriminant branches. it's giving organized chaos. 🌈
  • findspecials [files...] — generate a smart hierarchy and print, for each toplevel tag, what are the items that make it toplevel instead of going below another tag. like why are you at the top bestie. what did you do. 👀
  • grep <expression> [files...] — output the collection of tags that match the given tag expression. 🔥
  • test [files...] — perform internal tests and timings. she's testing herself. self care honestly. 💖

no sign off, we're not done yet — more parts are coming bestie, stay tuned 🎀✨

🆘 Help options

These are the universal ones, they work everywhere, no cap:

  • -h, -?, --help — prints the commandline help and exits. That's it, that's the whole job. ✨
  • --version — prints the program version and exits. Gotta know what you're running, bestie.
  • --manpage=[hooks] — outputs the tagcoll manpage and exits. Yes, the manpage can print the manpage. Recursion kinda ate. 🌀

Options for command help

(nothing listed under this one — it's just vibing there, empty 💀)

Options for command copy

(also empty, also vibing 🫶)

🔧 Options controlling transformations of input data

Okay so these are the glow-up options. They take your input and change it before anything else happens. Very main character energy:

  • --derived= — expand derived tags using the given list.
  • --implications-from= — use an external list of implications.
  • --rename-from= — rename tags using the given mapping list.
  • -p, --patch-with=, --patch= — apply patches from the given tag patch file. (Three names, one job, they're all doing the same thing, iconic of them.)
  • --remove-unfaceted= — while parsing, remove all tags with no facet part.
  • --remove-tags=<expression> — while parsing, remove all tags matching the given tag expression.

🎀 Options controlling transformations of output data

And these ones mess with your output on the way out the door:

  • -g, --group, --group-items — group items with the same tagset in the output collection.
  • --redundant — when implications are provided, expand them explicitly in the output.
  • -i, --items — output only the names of the items, without the tags.
  • -c, --count — output the count of tags instead of the tags.

Options for command reverse

Options controlling transformations of input data

Yeah bestie, same list again — the manpage is just built like that, we're keeping it readable not repetitive-for-fun:

  • --derived= — expand derived tags using the given list.
  • --implications-from= — use an external list of implications.
  • --rename-from= — rename tags using the given mapping list.
  • -p, --patch-with=, --patch= — apply patches from the given tag patch file.
  • --remove-unfaceted= — while parsing, remove all tags with no facet part.
  • --remove-tags=<expression> — while parsing, remove all tags matching the given tag expression.

Options controlling transformations of output data

  • -g, --group, --group-items — group items with the same tagset in the output collection.
  • --redundant — when implications are provided, expand them explicitly in the output.
  • -i, --items — output only the names of the items, without the tags.
  • -c, --count — output the count of tags instead of the tags.

Other options

  • --untagged-tag=<tag> — set item name to use for associating untagged items when using the "reverse" command. If you don't specify it, untagged items are not included in the output. So like, if you're missing them, that's why. 🙈

Options for command diff

(nothing under this one either 🦋)

Options controlling transformations of input data

  • --derived= — expand derived tags using the given list.
  • --implications-from= — use an external list of implications.
  • --rename-from= — rename tags using the given mapping list.
  • -p, --patch-with=, --patch= — apply patches from the given tag patch file.
  • --remove-unfaceted= — while parsing, remove all tags with no facet part.
  • --remove-tags=<expression> — while parsing, remove all tags matching the given tag expression.

Other options

  • -d <val>, --distance=<val> — set the maximum distance to use for the "related" command (defaults to 0).

Options for command implications

Options controlling transformations of input data

  • --derived= — expand derived tags using the given list.
  • --implications-from= — use an external list of implications.
  • --rename-from= — rename tags using the given mapping list.
  • -p, --patch-with=, --patch= — apply patches from the given tag patch file.
  • --remove-unfaceted= — while parsing, remove all tags with no facet part.
  • --remove-tags=<expression> — while parsing, remove all tags matching the given tag expression.

Options for command hierarchy

Options controlling transformations of input data

  • --derived= — expand derived tags using the given list.
  • --implications-from= — use an external list of implications.
  • --rename-from= — rename tags using the given mapping list.
  • -p, --patch-with=, --patch= — apply patches from the given tag patch file.
  • --remove-unfaceted= — while parsing, remove all tags with no facet part.
  • --remove-tags=<expression> — while parsing, remove all tags matching the given tag expression.

🌳 Options controlling generation of tag hierarchies

These ones actually build the tree, they're the moment:

  • --flatten-threshold=<val> — set the number of total items below which a branch is flattened when using the "hierarchy" command (defaults to 0, meaning "don't flatten").
  • -f <val>, --filter=<val> — filter out the tags with cardinality less than the given value (defaults to not filter; currently only works when building hierarchies). Lowkey important to know it only works there, bestie.

Options for command cleanhierarchy

Options controlling transformations of input data

  • --derived= — expand derived tags using the given list.
  • --implications-from= — use an external list of implications.
  • --rename-from= — rename tags using the given mapping list.
  • -p, --patch-with=, --patch= — apply patches from the given tag patch file.
  • --remove-unfaceted= — while parsing, remove all tags with no facet part.
  • --remove-tags=<expression> — while parsing, remove all tags matching the given tag expression.

🌳 Options controlling generation of tag hierarchies

  • --flatten-threshold=<val> — set the number of total items below which a branch is flattened when using the "hierarchy" command (defaults to 0, meaning "don't flatten").
  • -f <val>, --filter=<val> — filter out the tags with cardinality less than the given value (defaults to not filter; currently only works when building hierarchies).

Options for command dischierarchy

Options controlling transformations of input data

  • --derived= — expand derived tags using the given list.
  • --implications-from= — use an external list of implications.
  • --rename-from= — rename tags using the given mapping list.
  • -p, --patch-with=, --patch= — apply patches from the given tag patch file.
  • --remove-unfaceted= — while parsing, remove all tags with no facet part.
  • --remove-tags=<expression> — while parsing, remove all tags matching the given tag expression.

🌳 Options controlling generation of tag hierarchies

  • --flatten-threshold=<val> — set the number of total items below which a branch is flattened when using the "hierarchy" command (defaults to 0, meaning "don't flatten").
  • -f <val>, --filter=<val> — filter out the tags with cardinality less than the given value (defaults to not filter; currently only works when building hierarchies).

Options for command findspecials

Options controlling transformations of input data

  • --derived= — expand derived tags using the given list.
  • --implications-from= — use an external list of implications.
  • --rename-from= — rename tags using the given mapping list.
  • -p, --patch-with=, --patch= — apply patches from the given tag patch file.
  • --remove-unfaceted= — while parsing, remove all tags with no facet part.
  • --remove-tags=<expression> — while parsing, remove all tags matching the given tag expression.

🌳 Options controlling generation of tag hierarchies

  • --flatten-threshold=<val> — set the number of total items below which a branch is flattened when using the "hierarchy" command (defaults to 0, meaning "don't flatten").
  • -f <val>, --filter=<val> — filter out the tags with cardinality less than the given value (defaults to not filter; currently only works when building hierarchies).

Options for command grep

Options controlling transformations of input data

  • --derived= — expand derived tags using the given list.
  • --implications-from= — use an external list of implications.
  • --rename-from= — rename tags using the given mapping list.
  • -p, --patch-with=, --patch= — apply patches from the given tag patch file.
  • --remove-unfaceted= — while parsing, remove all tags with no facet part.
  • --remove-tags=<expression> — while parsing, remove all tags matching the given tag expression.

Options controlling transformations of output data

  • -g, --group, --group-items — group items with the same tagset in the output collection.
  • --redundant — when implications are provided, expand them explicitly in the output.
  • -i, --items — output only the names of the items, without the tags.
  • -c, --count — output the count of tags instead of the tags.

Other options

  • -v, --invert-match — invert the sense of matching, to select non-matching lines. The classic flip. 🔄
  • -q, --quiet — do not write anything to standard output, but exit with 0 if any match is found. So it says nothing and just tells you with its exit code. Silent but slay. 💅

Options for command test

Options controlling transformations of input data

  • --derived= — expand derived tags using the given list.
  • --implications-from= — use an external list of implications.
  • --rename-from= — rename tags using the given mapping list.
  • -p, --patch-with=, --patch= — apply patches from the given tag patch file.
  • --remove-unfaceted= — while parsing, remove all tags with no facet part.
  • --remove-tags=<expression> — while parsing, remove all tags matching the given tag expression.

Format of the tagged collection input 💖

okay bestie, so this is the tea on how you write a tagged collection. It's literally just a sequence of lines describing the tagged items, and the order of tags? Don't even stress about it, it does not matter. Each line starts with the item name, and then optionally some tag names follow.

Tag names are separated from the item name by a colon and then one or more spaces or tabs.

Tag names are separated from each other using a comma followed by one or more spaces.

Item names can contain colons, but not if the colon is followed by a space or tab, and they cannot end in a colon. So "ui:gnome" is ok, but "ui:" is not.

Tag names can contain commas, but not if the comma is followed by a space, and they cannot end in a comma. So "cult,religion" is ok, but "cult," is not.

An item with tags tag1, tag2, ..., tagN is represented as:

item: tag1, tag2, ..., tagN

An item with just tag1 is represented as:

item: tag1

An item without tags is represented as:

item:

or just as:

item

An example input:

mutt: clients/mail/net
sylpheed: clients/mail/net
procmail: filters/mail/net
spamassassin: filters/mail/net
spamfilter: filters/mail/net
bulkmail: lists/mail/net
mailman: lists/mail/net
smartlist: lists/mail/net
xeukleides: educational
new-package-not-yet-categorized:
another-uncategorized

Format for the explicit implications input ✨

The format for explicit implications is the same as the one for the tagged collection: put the name of a tag at the left of the colon, and the names of the tags it implies to the right.

Example:

C: language, devel
gnome: gui, ui, x11

Format for the rename mapping input 🎀

The format for rename mappings is the same as the one for the tagged collection: put the new name of the tags at the left of the colon, and the names of the old tags to be renamed on the right.

Example:

mp3: MP3
language: languages, devel::language, devel::languages

Format for the tag patch file 🦋

The format for the rename mappings is the same as the one for the tagged collection, but the tags are listed prepended with a + or - sign. A tag prepended with a + sign is added to the item, while a tag with a - sign is removed from it.

Example:

cappuccino: +essential
emacs: +otheros, -editor

Format for the derived tag list 🌸

The format for the derived tag list is a line-oriented format with a derived tag per line. The derived tag name starts at the beginning of the line and is separated from its tag expression by a colon and space, just like the tagged collection items.

The tag expression is an expression composed of tags and the operators && (and), || (or), ! (not) and the parenthesis ( and ).

Example:

userlevel::novice: !specialized && (interface::gui || interface::curses)

The tag at the left of the colon is added when the set of tags of an item matches the expression at the right of the colon.

EXAMPLES 💅

Now for the examples, bestie. These are literally the vibe.

# Output the collection in normal form
tagcoll copy collection-file

# Output the items associated to a given tag
tagcoll reverse collection-file | grep ^tag:

# Produce tag patch data describing the tag difference between two collections
tagcoll diff coll1 coll2

# Apply a tag patch file to coll1
tagcoll --patch-with=tagpatch copy coll1 > collection-file

# Show the minimal set of implicit implications contained in the collection
tagcoll implications collection-file

# Show the implicit implications contained in the collection, fully expanded
tagcoll --expanded-output implications collection-file

# Build a smart hierarchy with the collection
tagcoll hierarchy collection-file

# Build a cleaner smart hierarchy with the collection (yoy might like to tweak
# the parameters)
tagcoll -f 5 --flatten-threshold=5 cleanhierarchy collection-file

# Apply some transformations to the collection and build a smart hierarchy with
# them
tagcoll --implications-from=explicit-implications-file \
     --rename-from=rename-map \
     --patch-with=patch-file \
     hierarchy collection-file

# Merge the contents two collections
cat coll1 coll2 | tagcoll copy > merged

# Merge the contents two collections and apply an external patch
cat coll1 coll2 | tagcoll --patch-with=patch-file copy > merged

# Build a smart hierarchy out of the implicit implications contained in the
# collection
tagcoll implications collection-file | tagcoll hierarchy

# Build a smart hierarchy out of the combination of explicit implications and
# the implicit implications contained in the collection
tagcoll --implications-from=explicit-implications-file \
     implications collection-file | tagcoll hierarchy

# Show all the items similar to "mutt"
tagcoll related mutt collection-file

# Show all the items similar to "mutt" and "mozilla-browser"
tagcoll related mutt,mozilla-browser collection-file

# Show all the items similar to "mutt", with at most two differences
# in the tag set
tagcoll --distance=2 related mutt collection-file

SEE ALSO 🔍

The tagbk draft paper in /usr/share/doc/tagcoll.

AUTHOR 👑

tagcoll is maintained by enrico@enricozini.org.

This manpage has been automatically generated by the tagcoll program.

This page is from tagcoll 2.0.14, dated March 22, 2020. Periodt. 💅✨

📦 where this page comes from