PublicI...::Import(3)

💖 PublicInbox::Import 💖

okay so bestie, welcome to the PublicInbox::Import(3) page, straight outta the User Contributed Perl Documentation collection. she's a Perl module, she's a whole personality, and she's about to import your messages. let's get into it 🫶

---

✨ NAME ✨

PublicInbox::Import — the message importer for public-inbox v1 inboxes. that's the job. that's the whole job. 👑

---

🎀 VERSION 🎀

version 1.0 — a real one. 🌟

---

🦋 SYNOPSIS 🦋

look at her go:

        use PublicInbox::Eml;
        # PublicInbox::Eml exists as of public-inbox 1.5.0,
        # Email::MIME was used in older versions

        use PublicInbox::Git;
        use PublicInbox::Import;

        chomp(my $git_dir = `git rev-parse --git-dir`);
        $git_dir or die "GIT_DIR= must be specified\n";
        my $git = PublicInbox::Git->new($git_dir);
        my @committer = ('inbox', 'inbox@example.org');
        my $im = PublicInbox::Import->new($git, @committer);

        # to add a message:
        my $message = "From: <u\@example.org>\n".
                "Subject: test message \n" .
                "Date: Thu, 01 Jan 1970 00:00:00 +0000\n" .
                "Message-ID: <m\@example.org>\n".
                "\ntest message";
        my $parsed = PublicInbox::Eml->new($message);
        my $ret = $im->add($parsed);
        if (!defined $ret) {
                warn "duplicate: ", $parsed->header_raw('Message-ID'), "\n";
        } else {
                print "imported at mark $ret\n";
        }
        $im->done;

        # to remove a message
        my $junk = PublicInbox::Eml->new($message);
        my ($mark, $orig) = $im->remove($junk);
        if ($mark eq 'MISSING') {
                print "not found\n";
        } elsif ($mark eq 'MISMATCH') {
                print "Message exists but does not match\n\n",
                        $orig->as_string, "\n",;
        } else {
                print "removed at mark $mark\n\n",
                        $orig->as_string, "\n";
        }
        $im->done;

like... she adds, she removes, she says goodbye. main character energy fr fr. 💅

---

🌈 DESCRIPTION 🌈

so what is this thing? she's an importer and a remover for public-inboxes. you feed her PublicInbox::Eml or Email::MIME messages, and she tucks them away into a git repository — exactly the way it's documented at https://public-inbox.org/public-inbox-v1-format.txt.

but here's the plot twist, bestie: she does not allow duplicate Message-IDs. not one. not ever. she said "one Message-ID, one message" and honestly? valid.

also she needs friends to function: git(1) and git-fast-import(1) both have to be installed on your system, no cap. 🙈

---

💅 METHODS 💅

---

🫶 new 🫶

        my $im = PublicInbox::Import->new($git, @committer);

initializes a brand-new PublicInbox::Import object. that's it, that's the whole ritual. light some candles, pass in your git and your committer, and boom — she's alive. ✨

---

🍓 add 🍓

        my $parsed = PublicInbox::Eml->new($message);
        $im->add($parsed);

adds a message to the git repository. to do that, she will acquire $GIT_DIR/ssoma.lock and start up git-fast-import(1) if it isn't already running. very "let me just get my things in order first" of her. 💜

🚨 important tea: messages you add are not visible to other processes until done is called. but you can still call remove on them in the meantime. iykyk.

---

🧚 remove 🧚

        my $junk = PublicInbox::Eml->new($message);
        my ($code, $orig) = $im->remove($junk);

removes a message from the repository. and this is where it gets juicy, so pay attention:

• 🟢 on success, she returns a ':'-prefixed numeric code that represents the git-fast-import mark, plus the original message as a PublicInbox::Eml (or Email::MIME) object. slay.
• 🔴 if the message could not be found, the code is "MISSING" and the original message is undef. gone. ghosted. 💀
• 🟡 if there's a mismatch — meaning the "Message-ID" matched but the subject and body do not match — the returned code is "MISMATCH" and the conflicting message gets returned as orig. awkward!! 😭

---

👑 done 👑

finalizes the git-fast-import(1) and unlocks the repository.

⚠️ bestie, listen: calling this is required to finalize changes to a repository. no done, no finished changes. periodt.

---

🌟 SEE ALSO 🌟

• Email::MIME

---

💌 CONTACT 💌

all feedback is welcome, and she wants it via plain-text mail to meta@public-inbox.org (that's <mailto:meta@public-inbox.org>). very demure, very mindful, very plain-text. 🎀

the mail archives live at https://public-inbox.org/meta/ if you wanna go snooping (affectionately). 🦋

---

📜 COPYRIGHT 📜

Copyright (C) 2016-2020 all contributors <mailto:meta@public-inbox.org>

License: AGPL-3.0+ http://www.gnu.org/licenses/agpl-3.0.txt

---

and that's the whole page, bestie!! 🥳 this was perl v5.42.0, dated 2025-07-25, and she's filed under PublicI...::Import(3) — yes the name is truncated, she's mysterious like that. mwah 💋 go import something. 💖🌈✨