PUBLIC-INBOX-CLONE(1) public-inbox user manual PUBLIC-INBOX-CLONE(1)
NAME
public-inbox-clone - "git clone --mirror" wrapper
SYNOPSIS
public-inbox-clone INBOX_URL [INBOX_DIR]
public-inbox-clone ROOT_URL [DESTINATION]
DESCRIPTION
public-inbox-clone is a wrapper around "git clone --mirror" for making
the initial clone of a remote HTTP(S) public-inbox. It allows cloning
multi-epoch v2 inboxes with a single command and zero configuration.
It does not run public-inbox-init(1) nor public-inbox-index(1). Those
commands must be run separately if serving/searching the mirror is
required. As-is, public-inbox-clone is suitable for creating a git-
only backup.
public-inbox-clone creates a Makefile with handy targets to update the
inbox once indexed. This Makefile may be edited by the user; it will
not be rewritten by public-inbox-fetch(1) unless it is removed
completely.
public-inbox-clone does not use nor require any extra configuration
files (not even "~/.public-inbox/config").
public-inbox-fetch(1) may be used to keep "INBOX_DIR" up-to-date.
For v2 inboxes, it will create a "$INBOX_DIR/manifest.js.gz" file to
speed up subsequent public-inbox-fetch(1).
OPTIONS
--epoch=RANGE
Restrict clones of public-inbox-v2-format(5) inboxes to the given
range of epochs. The range may be a single non-negative integer or
a (possibly open-ended) "LOW..HIGH" range of non-negative integers.
"~" may be prefixed to either (or both) integer values to represent
the offset from the maximum possible value.
For example, "--epoch=~0" alone clones only the latest epoch,
"--epoch=~2.." clones the three latest epochs.
Default: "0..~0" or 0.. or "..~0" (all epochs, all three examples
are equivalent)
-I PATTERN
--include=PATTERN
When cloning a top-level with multiple inboxes, only clone inboxes
and repositories matching a given wildcard pattern (using "*?" and
"[]" is supported).
--exclude=PATTERN
When cloning a top-level with multiple inboxes, ignore inboxes and
repositories matching the given wildcard pattern. Supports the
same wildcards as "--include"
--inbox-config=always|v2|v1|never
Whether or not to retrieve the "$INBOX/_/text/config/raw" HTTP(S)
endpoint when cloning.
Since we can't deduce v1 inboxes from code repositories, setting
this to "v2" or "never" can allow faster clones of code
repositories if no v1 inboxes are present.
Default: "always"
--inbox-version=NUM
Force a remote public-inbox version (must be 1 or 2). This is
auto-detected by default, and this option exists mainly for
testing.
--objstore=DIR
Enables space savings when the remote "manifest.js.gz" includes
"forkgroup" entries as generated by grokmirror 2.x.
If "DIR" does not start with "/", "./", or "../", it is treated as
relative to the "DESTINATION" directory. If only "--objstore=" is
specified where "DIR" is an empty string (""), then "objstore"
("$DESTINATION/objstore") is the implied value of "DIR".
--manifest=FILE
When incrementally updating an existing mirror, load the given
manifest (typically "manifest.js.gz") to speed up updates.
By default, public-inbox writes the retrieved manifest to
"$DESTINATION/manifest.js.gz", this directive also changes the
destination to the specified "FILE"
If "FILE" does not start with "/", "./", or "../", it is treated as
relative to the "DESTINATION" directory. If only "--manifest=" is
specified where "FILE" is an empty string (""), then
"manifest.js.gz" ("$DESTINATION/manifest.js.gz") is the implied
value of "FILE".
--project-list=FILE
When cloning code repos from a manifest, generate a cgit-compatible
project list.
If "FILE" does not start with "/", "./", or "../", it is treated as
relative to the "DESTINATION" directory. If only "--project-list="
is specified where "FILE" is an empty string (""), then
"projects.list" ("$DESTINATION/projects.list") is the implied value
of "FILE".
--post-update-hook=COMMAND
Hooks to run after a repository is cloned or updated, "COMMAND"
will have the bare git repository destination given as its first
and only argument.
For v2 inboxes, this operates on a per-epoch basis.
May be specified multiple times to run multiple commands in the
order specified on the command-line.
-p
--prune
Pass the "--prune" and "--prune-tags" flags to git-fetch(1) calls
on incremental clones.
--exit-code
Exit with 127 if no updates are done when relying on a manifest.
Updates include fingerprint mismatches in the manifest, new
symlinks, new repositories, and removed repositories from the
--project-list
-k
--keep-going
Continue as much as possible after an error.
-n
--dry-run
Show what would be done, without making any changes.
-q
--quiet
Quiets down progress messages, also passed to git-fetch(1).
-v
--verbose
Increases verbosity, also passed to git-fetch(1).
--torsocks=auto|no|yes
--no-torsocks
Whether to wrap git(1) and curl(1) commands with torsocks(1).
Default: "auto"
CONTACT
Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>
The mail archives are hosted at <https://public-inbox.org/meta/> and
<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
COPYRIGHT
Copyright all contributors <mailto:meta@public-inbox.org>
License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
SEE ALSO
public-inbox-fetch(1), public-inbox-init(1), public-inbox-index(1)
public-inbox.git 1993-10-02 PUBLIC-INBOX-CLONE(1)