smd-config(5)

💖 smd-config — the config file glow-up for smd-pull and smd-push 💖

okay bestie, welcome to the smd-config(5) manual page, aka the group chat where your mail sync setup finally gets its life together. this is the config file for smd-pull and smd-push, and yes, it's giving main character energy from the very first line. 🎀

---

✨ GENERAL SETUP ✨

so to generate a template config file, you literally just run smd-pull(1) with the -t option. that's it, that's the move. 🫶

if no endpoint is specified, the configuration file is named ~/.smd/config.default. but if you do specify an endpoint? then it's named ~/.smd/config.endpoint. iconic behavior, honestly.

that file is composed by the following fields:

• CLIENTNAME — name of the client host
• SERVERNAME — name of the server host
• MAILBOX — list of directories, separated by space

ngl, the field SERVERNAME must be a valid name for ssh, so it can be an alias like smd-server-foo. the default configuration file contains an example of how to set up an alias for ssh, so like, look at it. 👀

the field CLIENTNAME is just an ID for the local host. and listen — if you plan to sync the same host with multiple remote hosts, you MUST use different values for CLIENTNAME for every configuration file. no cap, don't skip this one. 💀

the field MAILBOX is a space separated list or roots that will be scanned for maildirs. typically it's just one directory name, Mail or Maildir. the roots must be paths relative to the home directory. in the simplest case, the roots are named the same on both the local and the remote hosts. slay. ✨

if the roots have different names on the local and remote hosts, but their internal structure is the same, the simplest solution is to just use a symlink on one of the two hosts so that a single name can be used to refer to both. lowkey genius.

if the internal sub folder structure differ — for example because on the remote hosts sub folder names are prefixed with a dot but it is not the case on the local one — refer to the MAIL FOLDER RENAMING section of this document. i got you. 👑

the configuration file is a regular shell script, so refer to bash(1) for its syntax. yes bestie, it's just bash, you got this. 💅

---

🪝 HOOKS 🪝

the content of the directories ~/.smd/hooks/{pre,post}-pull.d/ is executed respectively before and after smd-pull does it's job. and bestie, they receive four arguments: "pre" or "post", "pull", the endpoint name and the status. the status is always 0 (meaning success) for pre hooks, while can be 1 (for failure) for post hooks. hooks should not fail — if they do so then smd-pull will fail too. so like, keep your hooks chill. 😭

the content of the directories ~/.smd/hooks/{pre,post}-push.d/ is executed respectively before and after smd-push does it's job. they receive four arguments: "pre" or "post", "push", the endpoint name and the status. the status is always 0 (meaning success) for pre hooks, while can be 1 (for failure) for post hooks. hooks should not fail, if they do so then smd-push will fail too. same vibe, different verb. 🔥

---

🌸 MAIL FOLDER RENAMING 🌸

to make the transition from other synchronization tools smooth, the folders structure on the local and remote host are allowed to differ. for example, offlineimap usually removes trailing dots from the names of sub folders. so if you're migrating, this section is your bestie fr fr.

to take advantage of folder renaming, the configuration file can contain the following fields:

• MAILBOX_LOCAL — the local roots of maildirs
• MAILBOX_REMOTE — the remote roots of maildirs
• TRANSLATOR_RL — a program to translate remote mailbox names to local ones
• TRANSLATOR_LR — a program to translate local mailbox names to remote ones

the fields MAILBOX_LOCAL and MAILBOX_REMOTE must substitute the MAILBOX fields explained above. swappin' in, swappin' out. 💜

the fields TRANSLATOR_RL and TRANSLATOR_LR must define two translator programs that will be run to translate remote mailbox names to local ones (TRANSLATOR_RL) and vice versa (TRANSLATOR_LR). a translator program must fulfil the following requirements:

• must be an absolute path or relative to the $HOME directory or in the user $PATH and must be executable
• receives in standard input one or more paths starting with one of the roots listed in MAILBOX_LOCAL (for TRANSLATOR_LR) or MAILBOX_REMOTE (for TRANSLATOR_RL) and ending with cur, new or tmp
• it can fail, returning 1 and writing on standard output the string ERROR followed by a new line and a human readable error message in the following lines
• it can succeed, returning 0 and printing on standard output the corresponding translated paths

so basically your translator is a little program that eats paths and spits out renamed ones. cute. 🦋

---

🚫 PATHS EXCLUSION 🚫

in case some paths need to be skipped, they can be specified as space separated glob(7) expressions in the variable:

• EXCLUDE — glob expressions identifying paths to be excluded

note that these expressions must match real paths, no translation operation is applied to them, so it may be necessary to specify different expressions for the local and remote endpoint. in that case the following variables can be set:

• EXCLUDE_LOCAL — glob expressions identifying local paths to be excluded
• EXCLUDE_REMOTE — glob expressions identifying remote paths to be excluded

matching is performed using fnmatch(3) with no special flags, thus * and ? match any character including /. last, note that spaces in glob expressions must be replaced by %20. for example, to exclude all paths matching the expression Mail/delayed [1-5] days/* the variable EXCLUDE must be set to Mail/delayed%20[1-5]%20days/*

bestie this %20 thing is not a vibe, it's a requirement. spaces in glob expressions become %20, periodt. 💅

last, matching is performed every time a directory is entered, and if the matching succeeds the directory and all its subdirectories are skipped. thus there is no need to specify a trailing /* in every expression. we love an efficient queen. 👑

---

🏠 LOCAL SYNCHRONIZATION 🏠

if the local and remote mailboxes are on the same host the following option must be added to the configuration file:

SMDCLIENTOPTS=-l

note that this options has also the effect that ssh is not used. a a simple pair of pipes is used instead. (yes, "a a" — that's exactly how the original says it, i'm just the messenger. 🙈)

---

💀 DELETIONS 💀

in some cases, usually unidirectional synchronizations, one may want to not propagate deletions. e.g. one keeps a slim working mailbox but pushes to a backup mailbox to save every email. for that scenario smd-pull and smd-push accept a -n, --no-delete, option. to avoid specifying this option every time one can put it in the configuration file:

SMDSERVEROPTS=-n

backup bestie behavior, honestly. keep every email, delete nothing. 🍓

---

📁 FILES 📁

~/.smd/config.*  ~/.smd/hooks/pre-pull.d/ ~/.smd/hooks/post-pull.d/
~/.smd/hooks/pre-push.d/ ~/.smd/hooks/post-push.d/

---

👀 SEE ALSO 👀

mddiff(1), smd-server(1), smd-client(1), smd-push(1), smd-loop(1), smd-translate(1)

---

🌈 AUTHOR 🌈

Enrico Tassi <gares@fettunta.org>

---

and that's the whole page, bestie! this one came from the <strong>Sync Mail Dir (smd) documentation</strong>, dated <strong>21 April 2021</strong>. go forth and configure your mail sync, you absolute icon. mwah. 💖✨🎀