PUBLIC-INBOX-CLONE(1)

📦
version 2.0.0~20230714git590023f · 5 versions
, in fedora 43, fedora 44

💖 public-inbox-clone 💖

okay bestie, welcome to public-inbox-clone — it's a page straight out of the public-inbox user manual, and honestly? it's giving "one command, zero config, absolute slay". 🎀

✨ NAME ✨

public-inbox-clone — it's a wrapper around "git clone --mirror". that's literally the whole job. iconic.

🌸 SYNOPSIS 🌸

public-inbox-clone [OPTIONS] INBOX_URL [INBOX_DIR]

public-inbox-clone [OPTIONS] ROOT_URL [DESTINATION] # public-inbox 2.0+

🦋 DESCRIPTION 🦋

okay so public-inbox-clone is a wrapper around "git clone --mirror" that does the very first clone of a remote HTTP(S) public-inbox for you. and the way it just handles multi-epoch v2 inboxes with one single command and zero configuration?? obsessed. no cap. 💅

in public-inbox 2.0+, public-inbox-clone can also create and maintain a mirror of multiple inboxes or code repositories using manifest.js.gz files, exactly like grok-pull(1) from grokmirror. and when you're in this mode, public-inbox-fetch(1) is NOT required. periodt.

it does not run public-inbox-init(1) and it does not run public-inbox-index(1). so if you actually want to serve or search your mirror, bestie, you gotta run those commands yourself, separately. as-is though? public-inbox-clone is perfect for making a git-only backup without Xapian and SQLite indices. lowkey ideal for that. 🫶

when you're cloning a single inbox, public-inbox-clone creates a Makefile with handy targets so you can update the inbox once it's indexed. and yes, you can edit that Makefile yourself — public-inbox-fetch(1) will not rewrite it unless you remove it completely. your file, your rules. 👑

public-inbox-clone does not use and does not require any extra configuration files (not even "~/.public-inbox/config"), but it can download snippets that are suitable for adding to any public-inbox-config(5) file. cute of it.

public-inbox-fetch(1) may be used to keep a single INBOX_DIR up-to-date. 🔥

and for v2 inboxes, it will create a "$INBOX_DIR/manifest.js.gz" file to speed up subsequent public-inbox-fetch(1) calls. it's literally doing pre-work for future-you. main character energy fr fr. ✨

💅 OPTIONS 💅

  • --epoch=RANGE — restricts clones of public-inbox-v2-format(5) inboxes to the given range of epochs. the range can be a single non-negative integer, or a (possibly open-ended) "LOW..HIGH" range of non-negative integers. you can prefix "~" to either integer value (or both!) to represent the offset from the maximum possible value.

so for example, "--epoch=~0" all by itself clones only the latest epoch, and "--epoch=~2.." clones the three latest epochs. slay.

Default: "0..~0" or 0.. or "..~0" (all epochs — all three examples are equivalent)

  • -I PATTERN, --include=PATTERN — when you're cloning a top-level with multiple inboxes via manifest, this only clones the inboxes and repositories matching a given wildcard pattern (using "*?" and "[]" is supported).

This is a new option in public-inbox 2.0+

  • --exclude=PATTERN — when cloning a top-level with multiple inboxes via manifest, this ignores inboxes and repositories matching the given wildcard pattern. supports the same wildcards as "--include".

This is a new option in public-inbox 2.0+

  • --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. smart.

Default: "always"

This is a new option in public-inbox 2.0+

  • --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.

This is a new option in public-inbox 2.0+

  • --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".

This is a new option in public-inbox 2.0+

  • --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", and 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".

This is a new option in public-inbox 2.0+

  • --remote-manifest=URL|RELATIVE_PATH — use an alternate location for the remote manifest.js.gz file. you can specify it as a full absolute URL (e.g. "--remote-manifest=https://80x24.org/lore/pub/manifest.js.gz"), or as a pathname relative to the ROOT_URL (e.g. "--remote-manifest=pub/manifest.js.gz" when ROOT_URL is "https://80x24.org/lore/").

by default, "ROOT_URL/manifest.js.gz" is used.

This is a new option in public-inbox 2.0+

  • --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".

This is a new option in public-inbox 2.0+

  • --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.

This is a new option in public-inbox 2.0+

  • -p, --prune — passes the "--prune" and "--prune-tags" flags to git-fetch(1) calls on incremental clones.

This is a new option in public-inbox 2.0+

  • --purge — deletes entire repos which no longer exist in the remote manifest, or are filtered out by "--include=" or "--exclude=".

this is only useful when using "--manifest"

This is a new option in public-inbox 2.0+

  • --exit-code — exits 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.

This is a new option in public-inbox 2.0+

  • -k, --keep-going — continue as much as possible after an error. we stay resilient. 💪

This is a new option in public-inbox 2.0+

  • -n, --dry-run — shows what would be done, without making any changes. window shopping, but for clones. 🛍️

This is a new option in public-inbox 2.0+

  • -q, --quiet — quiets down progress messages, and is also passed to git-fetch(1).
  • -v, --verbose — increases verbosity, and is 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"

  • -j JOBS, --jobs=JOBS — the number of parallel processes to spawn at once for various network operations using git(1) and/or curl(1).

🌈 EXAMPLES 🌈

to mirror the most recent epochs of dwarves and LTTng inboxes:

public-inbox-clone --epoch=~0 \
      --include='*lttng*' --include='*dwarves' \
      https://80x24.org/lore/ /path/to/inbox-mirror

"https://lore.kernel.org/" may be used instead of "https://80x24.org/lore/"

to mirror all code repos of the sparse project:

public-inbox-clone --objstore= --project-list= --prune \
      --include='*sparse*' --inbox-config=never \
      --remote-manifest=https://80x24.org/lore/pub/manifest.js.gz \
      https://80x24.org/lore/ /path/to/code-mirror

"https://git.kernel.org/" may be used instead of "https://80x24.org/lore/" and the "--remote-manifest" option can be omitted.

💌 CONTACT 💌

feedback welcome via plain-text mail to <mailto:meta@public-inbox.org> — slide into the inbox, bestie, it's right there in the name. 🫶

the mail archives are hosted at <https://public-inbox.org/meta/> and <http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/> (yes that's a real onion address, and yes it's iconic).

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)

and that's the whole vibe check, bestie 💖 this page came from public-inbox.git, dated 1993-10-02, and it's filed under PUBLIC-INBOX-CLONE(1). go clone something gorgeous. 🎀✨💅
📦 where this page comes from