Documentation/public-inbox-fetch.pod

   1 =head1 NAME
   2
   3 public-inbox-fetch - "git fetch" wrapper for v2 inbox mirrors
   4
   5 =head1 SYNOPSIS
   6
   7 public-inbox-fetch [--exit-code] -C INBOX_DIR
   8
   9 =head1 DESCRIPTION
  10
  11 public-inbox-fetch updates git storage of public-inbox mirrors.
  12 With v2 inboxes, it allows detection of new epochs and avoids
  13 unnecessary traffic on old epochs.
  14
  15 public-inbox-fetch does not use nor require any configuration
  16 files of its own.
  17
  18 It does not run L<public-inbox-index(1)>, making it suitable
  19 for maintaining git-only backups.
  20
  21 For v2 inboxes, it will maintain C<$INBOX_DIR/manifest.js.gz>
  22 file to speed up future invocations.  It always safe to remove
  23 manifest.js.gz, it is merely an optimization and will be
  24 restored on the next invocation.
  25
  26 To prevent fetches on any v2 epoch, use L<chmod(1)> to remove
  27 write permissions to the top-level of the epoch.  For example,
  28 to disable fetches on epoch 4:
  29
  30         chmod a-w $INBOX_DIR/git/4.git
  31
  32 If you wish to re-enable fetches to the epoch:
  33
  34         chmod u+w $INBOX_DIR/git/4.git
  35
  36 =head1 OPTIONS
  37
  38 =over
  39
  40 =item -q
  41
  42 =item --quiet
  43
  44 Quiets down progress messages, also passed to L<git-fetch(1)>.
  45
  46 =item -T REMOTE
  47
  48 =item --try-remote REMOTE
  49
  50 Try a given remote name instead of C<origin> or C<_grokmirror>.
  51 May be specified more than once.
  52
  53 Default: C<origin>, C<_grokmirror>
  54
  55 =item --exit-code
  56
  57 Exit with C<127> if no updates are done.  This can be used in
  58 shell scripts to avoid invoking L<public-inbox-index(1)> when
  59 there are no updates:
  60
  61         public-inbox-fetch -q --exit-code && public-inbox-index
  62         test $? -eq 0 || exit $?
  63
  64 =item -p
  65
  66 =item --prune
  67
  68 Pass the C<--prune> and C<--prune-tags> flags to L<git-fetch(1)> calls.
  69
  70 =item -v
  71
  72 =item --verbose
  73
  74 Increases verbosity, also passed to L<git-fetch(1)>.
  75
  76 =item --torsocks=auto|no|yes
  77
  78 =item --no-torsocks
  79
  80 Whether to wrap L<git(1)> and L<curl(1)> commands with L<torsocks(1)>.
  81
  82 Default: C<auto>
  83
  84 =back
  85
  86 =head1 EXIT CODES
  87
  88 =over
  89
  90 =item 127
  91
  92 no updates when L</--exit-code> is used above
  93
  94 =back
  95
  96 public-inbox-fetch will also exit with curl L<curl(1)/EXIT CODES>
  97 as documented in the L<curl(1)> manpage (e.g. C<7> when curl cannot
  98 reach a host).  Likewise, L<git-fetch(1)> failures are also
  99 propagated to the user.
 100
 101 =head1 CONTACT
 102
 103 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 104
 105 The mail archives are hosted at L<https://public-inbox.org/meta/> and
 106 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 107
 108 =head1 COPYRIGHT
 109
 110 Copyright all contributors L<mailto:meta@public-inbox.org>
 111
 112 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 113
 114 =head1 SEE ALSO
 115
 116 L<public-inbox-index(1)>, L<curl(1)>