3 public-inbox-clone - "git clone --mirror" wrapper
7 public-inbox-clone INBOX_URL [INBOX_DIR]
9 public-inbox-clone ROOT_URL [DESTINATION]
13 public-inbox-clone is a wrapper around C<git clone --mirror> for
14 making the initial clone of a remote HTTP(S) public-inbox. It
15 allows cloning multi-epoch v2 inboxes with a single command and
18 It does not run L<public-inbox-init(1)> nor
19 L<public-inbox-index(1)>. Those commands must be run separately
20 if serving/searching the mirror is required. As-is,
21 public-inbox-clone is suitable for creating a git-only backup.
23 public-inbox-clone creates a Makefile with handy targets to update the
24 inbox once indexed. This Makefile may be edited by the user; it will
25 not be rewritten by L<public-inbox-fetch(1)> unless it is removed
28 public-inbox-clone does not use nor require any extra
29 configuration files (not even C<~/.public-inbox/config>).
31 L<public-inbox-fetch(1)> may be used to keep C<INBOX_DIR>
34 For v2 inboxes, it will create a C<$INBOX_DIR/manifest.js.gz>
35 file to speed up subsequent L<public-inbox-fetch(1)>.
43 Restrict clones of L<public-inbox-v2-format(5)> inboxes to the
44 given range of epochs. The range may be a single non-negative
45 integer or a (possibly open-ended) C<LOW..HIGH> range of
46 non-negative integers. C<~> may be prefixed to either (or both)
47 integer values to represent the offset from the maximum possible
50 For example, C<--epoch=~0> alone clones only the latest epoch,
51 C<--epoch=~2..> clones the three latest epochs.
53 Default: C<0..~0> or C<0..> or C<..~0>
54 (all epochs, all three examples are equivalent)
58 =item --include=PATTERN
60 When cloning a top-level with multiple inboxes, only clone inboxes and
61 repositories matching a given wildcard pattern (using C<*?> and C<[]> is
64 =item --exclude=PATTERN
66 When cloning a top-level with multiple inboxes, ignore inboxes and
67 repositories matching the given wildcard pattern. Supports the same
68 wildcards as L</--include>
70 =item --inbox-config=always|v2|v1|never
72 Whether or not to retrieve the C<$INBOX/_/text/config/raw> HTTP(S)
73 endpoint when cloning.
75 Since we can't deduce v1 inboxes from code repositories, setting this
76 to C<v2> or C<never> can allow faster clones of code repositories if
77 no v1 inboxes are present.
81 =item --inbox-version=NUM
83 Force a remote public-inbox version (must be C<1> or C<2>).
84 This is auto-detected by default, and this option exists mainly
89 Enables space savings when the remote C<manifest.js.gz>
90 includes C<forkgroup> entries as generated by grokmirror 2.x.
92 If C<DIR> does not start with C</>, C<./>, or C<../>, it is treated
93 as relative to the C<DESTINATION> directory. If only C<--objstore=>
94 is specified where C<DIR> is an empty string (C<"">), then C<objstore>
95 (C<$DESTINATION/objstore>) is the implied value of C<DIR>.
99 When incrementally updating an existing mirror, load the given
100 manifest (typically C<manifest.js.gz>) to speed up updates.
102 By default, public-inbox writes the retrieved manifest to
103 C<$DESTINATION/manifest.js.gz>, this directive also
104 changes the destination to the specified C<FILE>
106 If C<FILE> does not start with C</>, C<./>, or C<../>, it is treated
107 as relative to the C<DESTINATION> directory. If only C<--manifest=>
108 is specified where C<FILE> is an empty string (C<"">), then C<manifest.js.gz>
109 (C<$DESTINATION/manifest.js.gz>) is the implied value of C<FILE>.
111 =item --project-list=FILE
113 When cloning code repos from a manifest, generate a cgit-compatible
116 If C<FILE> does not start with C</>, C<./>, or C<../>, it is treated
117 as relative to the C<DESTINATION> directory. If only C<--project-list=>
118 is specified where C<FILE> is an empty string (C<"">), then C<projects.list>
119 (C<$DESTINATION/projects.list>) is the implied value of C<FILE>.
121 =item --post-update-hook=COMMAND
123 Hooks to run after a repository is cloned or updated, C<COMMAND> will
124 have the bare git repository destination given as its first and only
127 For v2 inboxes, this operates on a per-epoch basis.
129 May be specified multiple times to run multiple commands in the
130 order specified on the command-line.
136 Pass the C<--prune> and C<--prune-tags> flags to L<git-fetch(1)>
137 calls on incremental clones.
143 Continue as much as possible after an error.
149 Show what would be done, without making any changes.
155 Quiets down progress messages, also passed to L<git-fetch(1)>.
161 Increases verbosity, also passed to L<git-fetch(1)>.
163 =item --torsocks=auto|no|yes
167 Whether to wrap L<git(1)> and L<curl(1)> commands with L<torsocks(1)>.
175 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
177 The mail archives are hosted at L<https://public-inbox.org/meta/> and
178 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
182 Copyright all contributors L<mailto:meta@public-inbox.org>
184 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
188 L<public-inbox-fetch(1)>, L<public-inbox-init(1)>, L<public-inbox-index(1)>