PUBLIC-INBOX-CONVERT(1)

💖 PUBLIC-INBOX-CONVERT(1) 💖

okay bestie, so this is the public-inbox user manual page for public-inbox-convert — the glow-up tool. she takes your crusty old v1 inbox and gives it v2 main character energy. let's get into it 🦋

---

✨ NAME ✨

public-inbox-convert — convert v1 inboxes to v2

---

🌸 SYNOPSIS 🌸

public-inbox-convert [OPTIONS] OLD_DIR NEW_DIR

---

💅 DESCRIPTION 💅

so basically, public-inbox-convert copies everything inside an old "v1" inbox into a brand new "v2" inbox. that's it, that's the whole vibe.

and listen — it does not touch the old inbox at all. zero changes, not a single hair on its head. once you're happy with how the conversion turned out (like, actually satisfied, not just hopeful), you're expected to go update the inboxdir path in public-inbox-config(5) so it points at the path of NEW_DIR. that's the moment where the new one becomes the one. periodt. 👑

---

🎀 OPTIONS 🎀

• --no-index — turns OFF Xapian and overview DB indexing on the new inbox. by default tho, public-inbox-convert goes ahead and creates a fresh index in the v2 inbox and indexes every single existing message, which is, ngl, a lengthy operation for large inboxes. like, go get a snack, bestie. 🍓
• -j JOBS, --jobs=JOBS — controls the number of indexing jobs and the number of Xapian shards of the v2 inbox. by default this is the detected CPU count, but capped at 4 because of various bottlenecks (the drama of it all). also heads up: the number of Xapian shards will be 1 less than the JOBS value, since there's a single process that distributes work to the Xapian shards. math girlies stay winning. 🧚
• -L LEVEL, --index-level=LEVEL
• -c, --compact
• -v, --verbose
• --no-fsync
• --sequential-shard
• --batch-size=BYTES
• --max-size=BYTES

all of these affect indexing, and they have no effect if --no-index is specified. fyi: go peep public-inbox-index(1) for a description of these options, i'm not gonna steal their whole moment. 💜

---

🌈 ENVIRONMENT 🌈

• PI_CONFIG — the default config file, normally ~/.public-inbox/config. see public-inbox-config(5). 🫶

---

⭐ UPGRADING ⭐

editing ~/.public-inbox/config (or whatever PI_CONFIG is set to) will be required to start using the new directory. no config edit, no upgrade, iykyk. ✨

---

💀 BUGS 💀

real talk, this is the part where you gotta pay attention.

writes from public-inbox-mda(1) or git-fetch(1) to the v1 inbox that happen after the start of the conversion will not be picked up in the v2 inbox. like, they just won't. 😭

but here's the good news — users of public-inbox-watch(1) do not have to worry about this at all. all they need to do is:

1. update the config file so it points to the v2 inbox,
2. send SIGHUP to the public-inbox-watch process to reload the config file,
3. and then SIGUSR1 to rescan the existing Maildirs.

and that's it. slay. 💅

---

📬 CONTACT 📬

feedback is welcome via plain-text mail to <mailto:meta@public-inbox.org> 💌

the mail archives are hosted at <https://public-inbox.org/meta/> and <http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>

---

👑 COPYRIGHT 👑

Copyright 2013-2021 all contributors <mailto:meta@public-inbox.org>

License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>

---

🦋 SEE ALSO 🦋

public-inbox-init(1), public-inbox-index(1), public-inbox-config(5), public-inbox-v1-format(5), public-inbox-v2-format(5)

---

and that's a wrap bestie!! this page came from public-inbox.git and it's dated 1993-10-02 — yes, that long ago, iconic behavior honestly. now go convert that inbox and thrive 💖✨🎀