NAME

       PublicInbox::Import - message importer for public-inbox v1 inboxes

VERSION

       version 1.0

SYNOPSIS

               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;

DESCRIPTION

       An importer and remover for public-inboxes which takes "PublicInbox::Eml" or Email::MIME
       messages as input and stores them in a git repository as documented in
       <https://public-inbox.org/public-inbox-v1-format.txt>, except it does not allow duplicate
       Message-IDs.

       It requires git(1) and git-fast-import(1) to be installed.

METHODS

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

       Initialize a new PublicInbox::Import object.

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

       Adds a message to to the git repository.  This will acquire "$GIT_DIR/ssoma.lock" and
       start git-fast-import(1) if necessary.

       Messages added will not be visible to other processes until "done" is called, but "remove"
       may be called on them.

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

       Removes a message from the repository.  On success, it returns a ':'-prefixed numeric code
       representing the git-fast-import mark and the original messages as a PublicInbox::Eml (or
       Email::MIME) object.  If the message could not be found, the code is "MISSING" and the
       original message is undef.  If there is a mismatch where the "Message-ID" is matched but
       the subject and body do not match, the returned code is "MISMATCH" and the conflicting
       message is returned as orig.

   done
       Finalizes the git-fast-import(1) and unlocks the repository.  Calling this is required to
       finalize changes to a repository.

SEE ALSO

       Email::MIME

CONTACT

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

       The mail archives are hosted at <https://public-inbox.org/meta/>

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>