2.6 KiB
libimagentryref
This library crate contains functionality to generate references within the imag store.
Problem
The problem this library solves is the following: A user wants to refer to a file which exists on her filesystem from within imag. But unfortunately, the user has several devices and the filesystem layout (the way the $HOME is organized) is not the same on every device. With this library, the user is able to refer to a file, but without specifying the whole path.
Each device can have a different "base path", files are re-found via their hashes and file names, assuming that the files are equal on different devices or have at least the same name.
User Story / Usecase
Alice has a music library on her workstation and on her notebook. On her
workstation, the music collection is at home/alice/music, on the notebook, it
exists in /home/al/media/music.
From within imag, alice wants to create a link to a file
$music_store/Psy_trance_2018_yearmix.mp3.
libimagentryref helps her, because she can provide a "base path" in the
imag configuration file of each device and then link the file. imag only stores
data about the file and its relative path, but not its abolute path.
When moving the imag store from the workstation to the notebook, the base path
for the music collection is not /home/alice/music anymore, but
/home/al/media/music and imag can find the file automatically.
Solution, Details
libimagentryref does store the following data:
[ref]
basepath = "music"
is_ref = true # marker that this entry is actually a "ref"
relpath = "Psy_trance_2018_yearmix.mp3"
[ref.hash]
sha1 = "<sha1 hash of the file>"
The filehash is stored so that libimagentryref can re-find the file whenever it
was moved. The sha1 key is added to be able to upgrade hashes later to other
hashing algorithms.
relpath is the part of the path that when joined with the "base" path from
the configuration results in the full path of the file for the current machine.
The "collection" key hints to the configuration key in the imag config file.
The configuration section for the collections looks like this:
[ref.basepathes]
music = "/home/alice/music"
documents = "/home/alice/doc"
libimagentryref provides functionality to get the file. libimagentryref also offers functionality to find files only using their filename (x)or filehash and correct the filehash or filename respectively (automatically or explicitely).
Limits
As soon as the file is renamed and modified, this fails. This does also not cover the use case where the same file has different names on different machines.