.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PublicInbox::Import 3"
.TH PublicInbox::Import 3 2023-07-30 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
PublicInbox::Import \- message importer for public\-inbox v1 inboxes
.SH VERSION
.IX Header "VERSION"
version 1.0
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&        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\en";
\&        my $git = PublicInbox::Git\->new($git_dir);
\&        my @committer = (\*(Aqinbox\*(Aq, \*(Aqinbox@example.org\*(Aq);
\&        my $im = PublicInbox::Import\->new($git, @committer);
\&
\&        # to add a message:
\&        my $message = "From: <u\e@example.org>\en".
\&                "Subject: test message \en" .
\&                "Date: Thu, 01 Jan 1970 00:00:00 +0000\en" .
\&                "Message\-ID: <m\e@example.org>\en".
\&                "\entest message";
\&        my $parsed = PublicInbox::Eml\->new($message);
\&        my $ret = $im\->add($parsed);
\&        if (!defined $ret) {
\&                warn "duplicate: ", $parsed\->header_raw(\*(AqMessage\-ID\*(Aq), "\en";
\&        } else {
\&                print "imported at mark $ret\en";
\&        }
\&        $im\->done;
\&
\&        # to remove a message
\&        my $junk = PublicInbox::Eml\->new($message);
\&        my ($mark, $orig) = $im\->remove($junk);
\&        if ($mark eq \*(AqMISSING\*(Aq) {
\&                print "not found\en";
\&        } elsif ($mark eq \*(AqMISMATCH\*(Aq) {
\&                print "Message exists but does not match\en\en",
\&                        $orig\->as_string, "\en",;
\&        } else {
\&                print "removed at mark $mark\en\en",
\&                        $orig\->as_string, "\en";
\&        }
\&        $im\->done;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
An importer and remover for public-inboxes which takes \f(CW\*(C`PublicInbox::Eml\*(C'\fR
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.
.PP
It requires \fBgit\fR\|(1) and \fBgit\-fast\-import\fR\|(1) to be installed.
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
.Vb 1
\&        my $im = PublicInbox::Import\->new($git, @committer);
.Ve
.PP
Initialize a new PublicInbox::Import object.
.SS add
.IX Subsection "add"
.Vb 2
\&        my $parsed = PublicInbox::Eml\->new($message);
\&        $im\->add($parsed);
.Ve
.PP
Adds a message to to the git repository.  This will acquire
\&\f(CW\*(C`$GIT_DIR/ssoma.lock\*(C'\fR and start \fBgit\-fast\-import\fR\|(1) if necessary.
.PP
Messages added will not be visible to other processes until "done"
is called, but "remove" may be called on them.
.SS remove
.IX Subsection "remove"
.Vb 2
\&        my $junk = PublicInbox::Eml\->new($message);
\&        my ($code, $orig) = $im\->remove($junk);
.Ve
.PP
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.
.SS done
.IX Subsection "done"
Finalizes the \fBgit\-fast\-import\fR\|(1) and unlocks the repository.
Calling this is required to finalize changes to a repository.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Email::MIME
.SH CONTACT
.IX Header "CONTACT"
All feedback welcome via plain-text mail to <mailto:meta@public\-inbox.org>
.PP
The mail archives are hosted at <https://public\-inbox.org/meta/>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2016\-2020 all contributors <mailto:meta@public\-inbox.org>
.PP
License: AGPL\-3.0+ <http://www.gnu.org/licenses/agpl\-3.0.txt>