From: Eric Wong <e@80x24.org>
To: meta@public-inbox.org
Subject: [PATCH] doc: update clone+fetch with 2.0+ switches
Date: Mon, 27 Feb 2023 10:21:05 +0000 [thread overview]
Message-ID: <20230227102105.1336625-1-e@80x24.org> (raw)
Because old versions will exist for a long time and our latest
documentation is visible on the web, we must document when a
switch appears to avoid confusing users of old versions.
---
Documentation/public-inbox-clone.pod | 42 ++++++++++++++++++++++++----
Documentation/public-inbox-fetch.pod | 2 ++
2 files changed, 38 insertions(+), 6 deletions(-)
diff --git a/Documentation/public-inbox-clone.pod b/Documentation/public-inbox-clone.pod
index 7498aed9..7774d4ed 100644
--- a/Documentation/public-inbox-clone.pod
+++ b/Documentation/public-inbox-clone.pod
@@ -4,9 +4,9 @@ public-inbox-clone - "git clone --mirror" wrapper
=head1 SYNOPSIS
-public-inbox-clone INBOX_URL [INBOX_DIR]
+public-inbox-clone [OPTIONS] INBOX_URL [INBOX_DIR]
-public-inbox-clone ROOT_URL [DESTINATION]
+public-inbox-clone [OPTIONS] ROOT_URL [DESTINATION] # public-inbox 2.0+
=head1 DESCRIPTION
@@ -15,21 +15,27 @@ 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.
+In public-inbox 2.0+, public-inbox-clone can also mirror multiple
+inboxes or code repositories using manifest.js.gz files like
+L<grok-pull(1)> from grokmirror.
+
It does not run L<public-inbox-init(1)> nor
L<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
+When cloning a single inbox, 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 L<public-inbox-fetch(1)> unless it is removed
completely.
public-inbox-clone does not use nor require any extra
configuration files (not even C<~/.public-inbox/config>).
-L<public-inbox-fetch(1)> may be used to keep C<INBOX_DIR>
-up-to-date.
+L<public-inbox-fetch(1)> may be used to keep a single C<INBOX_DIR>
+up-to-date. When using manifest.js.gz, public-inbox-clone is used
+to maintain the multi-repository mirror.
For v2 inboxes, it will create a C<$INBOX_DIR/manifest.js.gz>
file to speed up subsequent L<public-inbox-fetch(1)>.
@@ -61,12 +67,16 @@ When cloning a top-level with multiple inboxes, only clone inboxes and
repositories matching a given wildcard pattern (using C<*?> and C<[]> is
supported).
+This is a new option in public-inbox 2.0+
+
=item --exclude=PATTERN
When cloning a top-level with multiple inboxes, ignore inboxes and
repositories matching the given wildcard pattern. Supports the same
wildcards as L</--include>
+This is a new option in public-inbox 2.0+
+
=item --inbox-config=always|v2|v1|never
Whether or not to retrieve the C<$INBOX/_/text/config/raw> HTTP(S)
@@ -78,12 +88,16 @@ no v1 inboxes are present.
Default: C<always>
+This is a new option in public-inbox 2.0+
+
=item --inbox-version=NUM
Force a remote public-inbox version (must be C<1> or C<2>).
This is auto-detected by default, and this option exists mainly
for testing.
+This is a new option in public-inbox 2.0+
+
=item --objstore=DIR
Enables space savings when the remote C<manifest.js.gz>
@@ -94,6 +108,8 @@ as relative to the C<DESTINATION> directory. If only C<--objstore=>
is specified where C<DIR> is an empty string (C<"">), then C<objstore>
(C<$DESTINATION/objstore>) is the implied value of C<DIR>.
+This is a new option in public-inbox 2.0+
+
=item --manifest=FILE
When incrementally updating an existing mirror, load the given
@@ -108,6 +124,8 @@ as relative to the C<DESTINATION> directory. If only C<--manifest=>
is specified where C<FILE> is an empty string (C<"">), then C<manifest.js.gz>
(C<$DESTINATION/manifest.js.gz>) is the implied value of C<FILE>.
+This is a new option in public-inbox 2.0+
+
=item --project-list=FILE
When cloning code repos from a manifest, generate a cgit-compatible
@@ -118,6 +136,8 @@ as relative to the C<DESTINATION> directory. If only C<--project-list=>
is specified where C<FILE> is an empty string (C<"">), then C<projects.list>
(C<$DESTINATION/projects.list>) is the implied value of C<FILE>.
+This is a new option in public-inbox 2.0+
+
=item --post-update-hook=COMMAND
Hooks to run after a repository is cloned or updated, C<COMMAND> will
@@ -129,6 +149,8 @@ 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+
+
=item -p
=item --prune
@@ -136,24 +158,32 @@ order specified on the command-line.
Pass the C<--prune> and C<--prune-tags> flags to L<git-fetch(1)>
calls on incremental clones.
+This is a new option in public-inbox 2.0+
+
=item --exit-code
Exit with C<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 L<--project-list>
+This is a new option in public-inbox 2.0+
+
=item -k
=item --keep-going
Continue as much as possible after an error.
+This is a new option in public-inbox 2.0+
+
=item -n
=item --dry-run
Show what would be done, without making any changes.
+This is a new option in public-inbox 2.0+
+
=item -q
=item --quiet
diff --git a/Documentation/public-inbox-fetch.pod b/Documentation/public-inbox-fetch.pod
index c5e73d38..1ff0df44 100644
--- a/Documentation/public-inbox-fetch.pod
+++ b/Documentation/public-inbox-fetch.pod
@@ -67,6 +67,8 @@ there are no updates:
Pass the C<--prune> and C<--prune-tags> flags to L<git-fetch(1)> calls.
+This is a new option in public-inbox 2.0+
+
=item -v
=item --verbose
reply other threads:[~2023-02-27 10:21 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://public-inbox.org/README
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230227102105.1336625-1-e@80x24.org \
--to=e@80x24.org \
--cc=meta@public-inbox.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).