digitaglinktree(1)

💖 digitaglinktree — Linux User's Manual 💖

okay so bestie, welcome to digitaglinktree(1) — yes that's the manual name, it's a lot of letters, we love her anyway 🫶

---

🌸 NAME 🌸

digitaglinktree — Export tag structure of photos in digikam to the filesystem.

---

✨ SYNOPSIS ✨

digitaglinktree

-l taglinkdir | -A archivedir

-d database

[-r rootdir]

[-H|-f|-a|-v|-C]

---

🦋 DESCRIPTION 🦋

So here's the vibe: digitaglinktree builds a linktree for every single photo in a digikam database that has tags set on it. Tags (like eg. "family", "events", ...) are the thing digikam uses to make virtual folders full of images that all have one or more tags assigned. 💅

⚠️ Important, no cap: photos that have no tags at all assigned are silently ignored by this script. And listen — the program will not modify or even touch your original photos managed by digikam. Your babies are safe. 🫶

The script can be used in two ways:

Way number one — call it with option -l taglinkdir and the script creates the user specified directory taglinkdir, and inside that directory it makes subdirectories for digikam tags set on the photos. Inside those subdirectories it finally drops symbolic or hard links (see -H) pointing to the photos that have the tags in question. End result? You literally see the tags of your photos as folders, and inside those folders you find links to your original photos. Iconic.

This way you can access the collection of all images that share a certain tag by just changing directory into the folder with the tag's name created by this script. Which means you can, for example, run JAlbum — a photo album software that needs to find the pictures it's putting into a web album in the filesystem — because JAlbum cannot access digikam's virtual folders directly. periodt.

Way number two — the so called archive-mode, by setting option -A archiveDir.

Archive mode is thought for people who want to archive tagged photos independently of digikam's root directories and the photos therein. This way you can put your photos and their tag structure into eg. a tar archive and send it to a friend, who can look at the photos via their tag structure. 🎀

In this mode the script creates the directory given as parameter to -A, and in this directory it makes two more subdirectories:

1. One named Photos
2. A second named Tags

The Photos directory contains hard links to your original photos, and the Tags directory contains a subdirectory for each Tag used by any of your photos. Inside this subdirectory there are links (either symbolic or hard links) to the files in the Photos directory. This way the archive directory needs nearly no additional space on your harddisk and you have an archive that lets you or a friend easily look at the photos' tag structure. obsessed.

Another benefit from using this script: you have kind of a backup of your tag settings for all of your photos. The backup is simply the directory structure containing links to the original images that wear the tags. This could become important if, for whatever reason, the digikam.db file gets corrupted or even lost. 😭 (protect her!!)

---

👑 COMMAND-LINE OPTIONS 👑

• -l taglinkdir — Parameter taglinkdir denotes a directory in which the tag structure of all your photos stored in rootdir will be exported to, by creating subdirectories for each tag and placing symbolic links in these subdirectories that point to the original photo wearing the tags. If you call the script with option -l taglinkDir you also have to specify options -r rootdir as well as -d database.
• -A archivedirectory — archivedirectory denotes a directory into which the script will export the photos and their tag structure. -A has to be used together with option -r rootdir if using digikam version < 0.10, as well as -d database — else the script will terminate. 🛑

Inside the archive directory the script will create a Photos and a Tags directory. It will put hard links in the Photos directory that point to your original photos. By using hard links you are independent of changes in your digikam root directory, but on the other hand you are limited to one filesystem. So the directory given by -r rootdir and the directory specified for -A archivedir have to be on the same filesystem.

If using digikam in version >= 0.10 you cannot specify -r rootdir. Instead the root paths of all albums are taken from digikam's database directly. However, the requirement still holds that archivedir has to be on the same filesystem as all the root directories containing photos you defined in digikam. If one of digikam's root directories is on another filesystem, this one will not be processed, since hardlinking the photos inside the Photos directory would not work in this case!

The Tags subdirectory will contain links to the files in the Photos directory. This way you have one archive directory that is completely self contained. You can tar it, send it to a friend, or just put it somewhere for archival or backup purposes. 🌈

Usually only those photos will be archived that have a digikam tag set on them. By using option -C however you can perform a complete archive. See -C for more infos.

• -d database — database is the complete path including the filename to digikam's photo database, which usually can be found in digikam's root directory. The file's name is usually digikam.db.
• -r rootdir — rootdir denotes the digikam base directory containing all your photos if you are using digikam in a version before 0.10. If you are using digikam 0.10 or newer you must not use this option. If you do it anyway, you will see a hint that the option given will be ignored, because digikam's version 0.10 database contains the root directories of all albums defined in digikam.
• -C — When the script is called with option -A archivedir, only those photos will be archived (by placing links) in the Photos subdirectory of archivedir that have at least one digikam tag set. By setting option -C all photos will be archived to archivedir no matter if they have a tag set or not. 📸

Note: this only changes the contents of the Photos subdirectory, not of the Tags subdirectory in the archivedir directory.

• -a — By default the script will try to create relative symbolic links from the directory taglinkdir set by option -l to the photo files under rootdir given by option -r. Using this option will result in absolute symbolic links being created instead of relative ones.
• -H — By default the script will create soft (symbolic) links from the Tag-Tree to the photos. By setting option -H the script will use hard links instead.

💀 Please note that hard links can only be created inside one filesystem. So your photos and the Tag tree have to be on the same filesystem. If not, you will see a warning about this problem and the script will not run.

• -f — In digikam photos can have hierarchical tags (tags that have subtags). In this case digitaglinktree would by default add a directory for the tag and a subdirectory for each of the subtags of this tag. By setting -f a subtag is treated like a regular tag, just as its parent tag, so digitaglinktree will create all subdirectories for tags and subtags at the same level, independent of the tag–subtag hierarchy.
• -Y — Create a year directory under each tag directory. Year information is taken from "Date taken" in the database. 🗓️
• -i tag1,..,tagn — tag1,..,tagn — Include only images with tags in the list. Use comma as tag separator. Default is "none". Use "all" to include all tags at once if you really want this. Better try a list with only some tags first to see how long it takes to complete. ⏳
• -e tag1,..,tagn — tag1,..,tagn — Exclude images with tags in the list. Use comma as tag separator. Default is "none".
• -M level_number — level_number specify the number of directory level. -M specifies that instead of following normal tag hierarchy, it creates a hierarchy combining different tags together and not only within one tag hierarchy (for example combining Places and People tags). You have to add tags to be included by using the option -i (see above).

😭 Depending on the level given and the number of tags you have included and how many photos you manage using digikam, this option may take a considerable amount of time (possibly more than one hour) to complete! A level_number of "5" seems to be the maximum reasonable level to start with in this mode. Options -A -C -a -H -f not tested with this option!

• -V — Verbose mode. 🗣️
• -v — Prints the script's version number and exits.

---

🧚 CONFIGURATION 🧚

By default this script will run with all photo databases created by digikam version 0.10 as well as older versions like 0.9 and 0.8. If you still have digikam version 0.7 then you have to reconfigure the script itself.

You have to reconfigure the script by setting the path to the sqlite binary that is used by the script to query the digikam database digikam.db. Since very old digikam versions use sqlite in version 2, but later digikam versions need sqlite version 3, you have to take care to install the correct version of sqlite for the installed digikam version — and to set the path to the correct sqlite executable in the script's head: 🎀

Choose

$SQLITE="/usr/bin/sqlite3";

for digikam version 0.8x and 0.9x and 0.10x

$SQLITE="/usr/bin/sqlite";

for digikam version 0.7x.

---

💖 EXAMPLE 💖

okay bestie, real talk — here's what actually calling digitaglinktree looks like in the wild. 🦋

A call to digitaglinktree is shown below:

digiTagLinktree  -l /home/user/tags
            -d /home/user/photos/digikam.db

so in this example we're assuming you're running digikam version 0.10 or higher, which means no option -r was used to specify the photo root dir. instead, that info gets fetched automatically from digikam's database. it's giving effortless. ✨

But if you want to run the script on a digikam database that was created by digikam version 0.9 or earlier, you have to use -r to specify the root directory where you keep all your photos that are managed by digikam:

digiTagLinktree -l /home/user/tags
            -d /home/user/photos/digikam.db

In this example digikam's photo root denoted by -r is /home/user/photos.

---

Option -l /home/user/tags tells the script that all the subdirectories and symbolic links will be placed in the directory /home/user/tags. The folder was chosen so that the tags-directory is not under digikam's photo root. You may put the tags folder inside digikam's photoroot but this is not the preferred method. 🚫 Because the link directory contains only links, this tag structure does hardly need any additional space on your harddisk. storage girlies stay winning. 💅

digiTagLinktree -r /home/user/photos -l /home/user/tags          -d
/home/user/photos/digikam.db
            -i People,Place
            -M 2
            -Y

In this example, if you have an image with the tags People/me, Place/home from 1970 it will create the following directory (link to the image under _all directory):

/home/user/tags/Date/1970/_all/

/home/user/tags/Date/1970/People/me/_all/

/home/user/tags/Date/1970/People/me/Place/home/_all/

/home/user/tags/Date/1970/Place/home/_all/

/home/user/tags/Date/1970/Place/home/People/me/_all/

same starting with /Place ... same starting with /People ...

bestie the way it just builds every combination of your tags into paths?? main character energy fr fr. 😭💖

---

👑 AUTHORS 👑

digitaglinktree was written by Rainer Krienke <krienke at uni-koblenz.de> 🫶

---

and that's the whole page, babe! 🌸 this one comes from the digitaglinktree(1) manual, dated 16 Aug 2006 — yeah it's an elder but it still ate. go forth and link your tags, bestie. 🎀⭐💜