From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: git@vger.kernel.org
Cc: "Junio C Hamano" <gitster@pobox.com>,
"Johannes Schindelin" <Johannes.Schindelin@gmx.de>,
"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Subject: [PATCH v5 2/3] bundle doc: elaborate on object prerequisites
Date: Fri, 2 Jul 2021 13:26:54 +0200 [thread overview]
Message-ID: <patch-2.3-444b06740bc-20210702T112254Z-avarab@gmail.com> (raw)
In-Reply-To: <cover-0.3-00000000000-20210702T112254Z-avarab@gmail.com>
Split out the discussion bout "object prerequisites" into its own
section, and add some more examples of the common cases.
See 2e0afafebd (Add git-bundle: move objects and references by
archive, 2007-02-22) for the introduction of the documentation being
changed here.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 26 +++++++++++++++++++++++---
1 file changed, 23 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 9c743aed49f..f5430029b8c 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -45,6 +45,7 @@ header is (mostly) in the format emitted by linkgit:git-show-ref[1].
Like the the packed archive format itself bundles can either be
self-contained, or be created using exclusions.
+See the "OBJECT PREREQUISITES" section below.
Bundles created using revision exclusions are "thin packs" created
using the `--thin` option to linkgit:git-pack-objects[1], and
@@ -153,19 +154,38 @@ contained in the union of the given bases. Each basis can be
specified explicitly (e.g. `^master~10`), or implicitly (e.g.
`master~10..master`, `--since=10.days.ago master`).
-It is very important that the basis used be held by the destination.
+OBJECT PREREQUISITES
+--------------------
+
+When creating bundles it is possible to create a fully self-contained
+bundle with all the prerequisite objects, as well as providing
+negative revisions to exclude prerequisite objects.
+
+A revision such as `new` will produce a tip with all the prerequisite
+objects needed for the `new` reference.
+
+A revision range such as `old..new` will produce a bundle tip that'll
+require any objects existing before `new` to already be present in the
+repository performing the 'git bundle unbundle' operation.
+
+A self-contained bundle without any prerequisites can be extracted
+into anywhere, even into an empty repository, or be cloned from
+(i.e., `new`, but not `old..new`).
+
It is okay to err on the side of caution, causing the bundle file
to contain objects already in the destination, as these are ignored
when unpacking at the destination.
-`git clone` can use any bundle created without negative refspecs
-(e.g., `new`, but not `old..new`).
If you want to match `git clone --mirror`, which would include your
refs such as `refs/remotes/*`, use `--all`.
If you want to provide the same set of refs that a clone directly
from the source repository would get, use `--branches --tags` for
the `<git-rev-list-args>`.
+The 'git bundle verify' command can be used to check whether your
+recipient repository has the required prerequisite commits for a
+bundle.
+
EXAMPLES
--------
--
2.32.0.632.g49a94b9226d
next prev parent reply other threads:[~2021-07-02 11:27 UTC|newest]
Thread overview: 41+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-06-07 14:37 [PATCH] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
2021-06-07 16:56 ` [PATCH v2] " Ævar Arnfjörð Bjarmason
2021-06-07 23:35 ` Junio C Hamano
2021-06-24 19:40 ` [PATCH v3 0/3] bundle doc: generaliz & elaborate Ævar Arnfjörð Bjarmason
2021-06-24 19:40 ` [PATCH v3 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
2021-06-29 4:52 ` Junio C Hamano
2021-06-24 19:40 ` [PATCH v3 2/3] bundle doc: split out thin v.s. not discussion from <rev-arg> Ævar Arnfjörð Bjarmason
2021-06-29 4:52 ` Junio C Hamano
2021-06-24 19:40 ` [PATCH v3 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
2021-06-30 9:16 ` [PATCH v4 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-06-30 9:16 ` [PATCH v4 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
2021-06-30 9:16 ` [PATCH v4 2/3] bundle doc: split out open v.s. closed discussion from <rev-arg> Ævar Arnfjörð Bjarmason
2021-06-30 21:13 ` Junio C Hamano
2021-06-30 9:16 ` [PATCH v4 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
2021-07-02 11:26 ` [PATCH v5 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-07-02 11:26 ` [PATCH v5 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
2021-07-02 11:26 ` Ævar Arnfjörð Bjarmason [this message]
2021-07-02 15:10 ` [PATCH v5 2/3] bundle doc: elaborate on object prerequisites Junio C Hamano
2021-07-02 11:26 ` [PATCH v5 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
2021-07-20 14:20 ` [PATCH v6 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-07-20 14:20 ` [PATCH v6 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
2021-07-20 14:20 ` [PATCH v6 2/3] bundle doc: elaborate on object prerequisites Ævar Arnfjörð Bjarmason
2021-07-20 20:06 ` Junio C Hamano
2021-07-20 14:20 ` [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
2021-07-20 20:19 ` Junio C Hamano
2021-07-21 9:27 ` Philip Oakley
2021-07-21 16:57 ` Junio C Hamano
2021-07-22 11:37 ` Philip Oakley
2021-07-22 11:46 ` Ævar Arnfjörð Bjarmason
2021-07-22 23:14 ` Philip Oakley
2021-07-27 0:24 ` [PATCH v7 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-07-27 0:24 ` [PATCH v7 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
2021-07-27 0:24 ` [PATCH v7 2/3] bundle doc: elaborate on object prerequisites Ævar Arnfjörð Bjarmason
2021-07-27 0:24 ` [PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
2021-07-28 15:17 ` Philip Oakley
2021-07-28 18:05 ` Junio C Hamano
2021-07-31 8:23 ` [PATCH v8 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-07-31 8:23 ` [PATCH v8 1/4] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
2021-07-31 8:23 ` [PATCH v8 2/4] bundle doc: elaborate on object prerequisites Ævar Arnfjörð Bjarmason
2021-07-31 8:23 ` [PATCH v8 3/4] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
2021-07-31 8:23 ` [PATCH v8 4/4] bundle doc: replace "basis" with "prerequsite(s)" Ævar Arnfjörð Bjarmason
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=patch-2.3-444b06740bc-20210702T112254Z-avarab@gmail.com \
--to=avarab@gmail.com \
--cc=Johannes.Schindelin@gmx.de \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
/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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.