From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: X-Spam-Status: No, score=-4.2 required=3.0 tests=ALL_TRUSTED,BAYES_00, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF shortcircuit=no autolearn=ham autolearn_force=no version=3.4.6 Received: from localhost (dcvr.yhbt.net [127.0.0.1]) by dcvr.yhbt.net (Postfix) with ESMTP id 75E451F47D for ; Mon, 27 Feb 2023 10:21:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=80x24.org; s=selector1; t=1677493265; bh=3tMiQ2/ad8xAWKCwxUCqKRqfijOQx0dsjA5alhDrxG4=; h=From:To:Subject:Date:From; b=qCXSkjZhoK0TAk/n1TOaTX++GPSMKWAFvinQ0rn98tUPVxHuw3HiXfpdjQsC9CBby wtga2i5wJud4oNoiURb7gX068EhoZNSetmOakyABItkm1zPcIeHbK3A/Pbp97U1xQs Kyy1qe7j9+So/Fbq1Pd6wmbTn0eaHHl5f2v8nB/Y= From: Eric Wong To: meta@public-inbox.org Subject: [PATCH] doc: update clone+fetch with 2.0+ switches Date: Mon, 27 Feb 2023 10:21:05 +0000 Message-Id: <20230227102105.1336625-1-e@80x24.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit List-Id: 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 from grokmirror. + It does not run L nor L. 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 unless it is removed completely. public-inbox-clone does not use nor require any extra configuration files (not even C<~/.public-inbox/config>). -L may be used to keep C -up-to-date. +L may be used to keep a single C +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. @@ -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 +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 +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 @@ -94,6 +108,8 @@ as relative to the C directory. If only C<--objstore=> is specified where C is an empty string (C<"">), then C (C<$DESTINATION/objstore>) is the implied value of C. +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 directory. If only C<--manifest=> is specified where C is an empty string (C<"">), then C (C<$DESTINATION/manifest.js.gz>) is the implied value of C. +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 directory. If only C<--project-list=> is specified where C is an empty string (C<"">), then C (C<$DESTINATION/projects.list>) is the implied value of C. +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 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 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 calls. +This is a new option in public-inbox 2.0+ + =item -v =item --verbose