]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/public-inbox-fetch.pod
ipc: drop unused $args from ->ipc_worker_stop
[public-inbox.git] / 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)>