mddiff(1)

📦
version 1.3.0 · 2 versions
, in ubuntu jammy

💌 mddiff(1) — the maildir diff bestie 💌

Sync Mail Dir (smd) documentation 🎀 yes we're doing the smd family today, and today's main character is mddiff.

✨ NAME ✨

mddiff — computes diff for maildirs 🦋

🌸 SYNOPSIS 🌸

mddiff [--max-mailno mno] [--db-file dbf] [-l|--list] [-s|--symlink]
       [--exclude globexpr] [-v|--verbose] [-d|--dry-run]
       [-n|--no-delete] [--no-move] [--help] [--sha1sum] paths

💖 DESCRIPTION 💖

okay so here's the tea 🫖: mddiff computes the delta between an old status of a maildir (one that was previously recorded in a support file, aka the db file) and the current status. Out comes a set of commands — a diff, literally — that some third party software can apply to synchronize a (possibly remote, iykyk) copy of that maildir. iconic behaviour fr fr 💅

If paths is a single file name, and that file is a fifo, then mddiff reads file names from it, separated by newline, and outputs the sha1 of its header and body separated by a space. no cap ✨

$ mddiff /tmp/fifo_for_mddiff
806a0ffe4f29766effd764... 463e543da9dac8e298...
582cbb6a5cd3ce13965c8c... 8fa60a7458b1157193...

...

If paths is a single file name, and that file is a fifo, and the -s option is passed, mddiff reads from that fifo two lines at a time — first a source name, then a target name. Then it creates a symlink named as the target name, pointing to the source name 🪄. If some directories need to be created in order to create that symlink, that gets done too. mddiff prints 'OK' on stdout to signal a success, and 'ERROR' to signal an error. slay 🌈

If paths is a list of directories, mddiff outputs a list of actions that a client has to perform to synchronize a copy of those same maildirs. This set of actions is relative to a previous status of the maildir, the one stored in the db file 👑. The input directories get traversed recursively, and every file encountered inside directories named cur/ and new/ is a potential mail message — unless it contains no \n\n, in which case it is skipped. noted bestie, it's giving ✨selective✨

$ mddiff ~/Mail/
ADD ~/Mail/cur/1239038050.14937_1.garfield:2,S 66532ebb05b252e...

...

Every client (meaning: every endpoint that uses mddiff for synchronization) must use a different db-file. the way that the db-file is strictly related to the set of directories you pass as arguments… it should not be used with a different directory set 🚨. Adding items to the directory set is safe 💚, but removing them may not do what you want — delete actions get generated, and that's a whole situation 💀

mddiff does not alter the dbf file. It generates a new one called dbf.new. It's up to the higher level tool smd-server(1) to rename dbf.new to dbf, but only in case the other endpoint successfully applied the diff. so don't go renaming things yourself, mkay 🙈

The --exclude option tells mddiff to ignore all paths matching the given glob(7) expression. You can pass this option multiple times 🔁. Matching is performed using fnmatch(3) with no special flags, so '*' and '?' match any character including '/'. Matching happens when a directory is entered. If the match is successful, that directory and all its subdirectories are skipped. bye felicia 👋

The --no-delete option tells mddiff to not output a DELETE action for files that disappear. But heads up 🫶: a DELETE action is anyway generated for files that are moved (i.e. move is COPY plus DELETE). The result is that deletions are not propagated to the other endpoint. periodt.

🎀 OPTIONS 🎀

  • --max-mailno mno — estimation of max mail message number (defaults to the number of messages in the db-file + 1000, or 500000 if there is no db-file). You may want to decrease it for the first run on small systems. It is anyway increased automatically when needed 💅
  • --db-file dbf — name of the cache for the endpoint (default db.txt) 🗂️
  • --exclude globexpr — exclude paths matching the given expression 🚫
  • --sha1sum — behaves like the sha1sum utility 🔐
  • --mkdir-p — behaves like mkdir -p 📁
  • --mkfifo — behaves like mkfifo 🧵
  • -l, --list — only list the mailboxes recursively contained in paths 📝
  • -s, --symlink — create symlinks for paths read on the input fifo 🔗
  • -v, --verbose — increase program verbosity (printed on stderr) 🗣️
  • -d, --dry-run — do not generate a new db-file 🙅
  • -n, --no-delete — do not track deleted files 🫥
  • --no-move — do not generate MOVE (only COPY + DELETE) 🔀
  • --help — this help screen 💖

🦋 NOTES 🦋

mddiff is a low level utility, used by smd-server and smd-client. You should use higher level tools like smd-pull(1), smd-push(1) and smd-loop(1) — let the big sisters handle it bestie, they got you 🫶

💜 SEE ALSO 💜

smd-client(1), smd-server(1), smd-pull(1), smd-push(1), smd-loop(1)

👑 AUTHOR 👑

Enrico Tassi <gares@fettunta.org> 💌

okay that's the whole page, and as a lil sign-off: this one's from the Sync Mail Dir (smd) docs, dated 21 April 2021, and it's mddiff(1) — go forth and diff those maildirs, bestie 💅✨🌈

📦 where this page comes from