git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Cc: git@vger.kernel.org, Johannes Schindelin <Johannes.Schindelin@gmx.de>
Subject: Re: [PATCH v5 2/3] bundle doc: elaborate on object prerequisites
Date: Fri, 02 Jul 2021 08:10:32 -0700	[thread overview]
Message-ID: <xmqq7di8rbtj.fsf@gitster.g> (raw)
In-Reply-To: <patch-2.3-444b06740bc-20210702T112254Z-avarab@gmail.com> ("Ævar	Arnfjörð Bjarmason"'s message of "Fri, 2 Jul 2021 13:26:54 +0200")

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

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

The above two paragraphs use the word "prerequisites" in a confusing
way.  The original meaning of the word in the context of talking
about a bundle is "you must have these commits in the receiving
repository for the bundle to be unbundle-able".

"git bundle create recent.bndl old..new" creates a bundle that
requires 'old' (and everything reachable from it) to exist in the
receiving repository.  We call the object 'old' (not the objects
reachable from it) the prerequisite of the bundle.

"git bundle create full.bndl new" creates a bundle that needs no
prerequistes.

It is confusing to say that full.bndl has all the prerequisite
objects needed.  It is correct to say that it has all the objects
reachable from 'new', but if we wanted to say that, we did not have
to introduce the new term "prerequisite" when we invented the bundle
format.  The concept "prerequisite" tries to convey is different.

So, the two paragraphs above use the word "prerequisite" when it
wants to talk about "reachable objects" (except for one use---the
one in "to exclude prerequisite objects" is correctly used), which
is confusing.  Here is the first paragraph with probably a better
phrasing.

	... it is possible to create a self-contained bundle that
	can be unbundled in an empty repository, as well as
	providing negative revisions to exclude objects needed in
	the earlier parts of the history.

As to the second paragraph:

	... will produce a bundle without any prerequisites.  It can
	be unbundled in any repository to obtain a full history that
	leads to the commit `new`.

By the way, I needed to read "a revision such as `new` will produce
..." three times before realizing that the reader must fill quite a
lot of missing words to understand what the sentence wanted to say,
which is:

	(feeding) a revision such as `new` (to "git bundle create"
	as the revision range argument) will produce ...

I think it is easier to follow if you spelled the command out, e.g.

    A command

    $ git bundle create full.bndl new

    will create a bundle file that contains all the objects
    reachable from the branch 'new'.

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

Getting warmer ;-).  In this case, 'old' is the prerequisite, so

    ... that'll require the commit 'old' (and any objects reachable
    from it) to exist for the bundle to be "unbundle"-able.

would be correct.

> +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`).
> +

This is entirely correct.

> +The 'git bundle verify' command can be used to check whether your
> +recipient repository has the required prerequisite commits for a
> +bundle.

So is this.

Thanks.

  reply	other threads:[~2021-07-02 15:10 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         ` [PATCH v5 2/3] bundle doc: elaborate on object prerequisites Ævar Arnfjörð Bjarmason
2021-07-02 15:10           ` Junio C Hamano [this message]
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

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqq7di8rbtj.fsf@gitster.g \
    --to=gitster@pobox.com \
    --cc=Johannes.Schindelin@gmx.de \
    --cc=avarab@gmail.com \
    --cc=git@vger.kernel.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.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

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