Documentation/public-inbox-edit.pod

   1 =head1 NAME
   2
   3 public-inbox-edit - destructively edit messages in a public inbox
   4
   5 =head1 SYNOPSIS
   6
   7         public-inbox-edit -m MESSAGE-ID --all|INBOX_DIR
   8
   9         public-inbox-edit -F RAW_FILE --all|INBOX_DIR [.. INBOX_DIR]
  10
  11 =head1 DESCRIPTION
  12
  13 public-inbox-edit allows editing messages in a given inbox
  14 to remove sensitive information.  It is only intended as a
  15 last resort, as it will cause discontiguous git history and
  16 draw more attention to the sensitive data in mirrors.
  17
  18 =head1 OPTIONS
  19
  20 =over
  21
  22 =item --all
  23
  24 Edit the message in all inboxes configured in ~/.public-inbox/config.
  25 This is an alternative to specifying individual inboxes directories
  26 on the command-line.
  27
  28 =item -m MESSAGE-ID
  29
  30 Edits the message corresponding to the given C<MESSAGE-ID>.
  31 If the C<MESSAGE-ID> is ambiguous, C<--force> or using the
  32 C<--file> of the original will be required.
  33
  34 =item -F FILE
  35
  36 Edits the message corresponding to the Message-ID: header
  37 and content given in C<FILE>.  This requires the unmodified
  38 raw message, and the contents of C<FILE> will not itself
  39 be modified.  This is useful if a Message-ID is ambiguous
  40 due to filtering/munging rules or other edits.
  41
  42 =item --force
  43
  44 Forcibly perform the edit even if Message-ID is ambiguous.
  45
  46 =item --raw
  47
  48 Do not perform "From " line escaping.  By default, this
  49 generates a mboxrd variant file to detect unpurged messages
  50 in the new mbox.  This makes sense if your configured
  51 C<publicinbox.mailEditor> is a regular editor and not
  52 something like C<mutt -f>
  53
  54 =back
  55
  56 =head1 CONFIGURATION
  57
  58 =over 8
  59
  60 =item publicinbox.mailEditor
  61
  62 The command to perform the edit with.  An example of this would be
  63 C<mutt -f>, and the user would then use the facilities in L<mutt(1)>
  64 to edit the mail.  This is useful for editing attachments or
  65 Base64-encoded emails which are more difficult to edit with a
  66 normal editor (configured via C<GIT_EDITOR>, C<VISUAL> or C<EDITOR>).
  67
  68 Default: none
  69
  70 =back
  71
  72 =head1 ENVIRONMENT
  73
  74 =over 8
  75
  76 =item GIT_EDITOR / VISUAL / EDITOR
  77
  78 =for comment MAIL_EDITOR is undocumented (unstable, don't want naming conflicts)
  79
  80 public-inbox-edit will fall back to using one of these variables
  81 (in that order) if C<publicinbox.mailEditor> is unset.
  82
  83 =item PI_CONFIG
  84
  85 The default config file, normally "~/.public-inbox/config".
  86 See L<public-inbox-config(5)>
  87
  88 =back
  89
  90 =head1 LIMITATIONS
  91
  92 Only L<v2|public-inbox-v2-format(5)> repositories are supported.
  93
  94 This is safe to run while normal inbox writing tools
  95 (L<public-inbox-mda(1)>, L<public-inbox-watch(1)>,
  96 L<public-inbox-learn(1)>) are active.
  97
  98 Running this in parallel with L<public-inbox-xcpdb(1)> or
  99 C<"public-inbox-index --reindex"> can lead to errors or
 100 edited data remaining indexed.
 101
 102 Incremental L<public-inbox-index(1)> (without C<--reindex>)
 103 is fine.
 104
 105 Keep in mind this is a last resort, as it will be disruptive
 106 to anyone using L<git(1)> to mirror the inbox being edited.
 107
 108 =head1 CONTACT
 109
 110 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 111
 112 The mail archives are hosted at L<https://public-inbox.org/meta/> and
 113 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 114
 115 =head1 COPYRIGHT
 116
 117 Copyright 2019-2021 all contributors L<mailto:meta@public-inbox.org>
 118
 119 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 120
 121 =head1 SEE ALSO
 122
 123 L<public-inbox-purge(1)>