Re: [PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 28, 2021, 18:05 UTC
Message-ID: <xmqqa6m69uvh.fsf@gitster.g>
In-Reply-To: <patch-3.3-88e7ad1cf4-20210727T002001Z-avarab@gmail.com>

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

> +Revisions must accompanied by reference names to be packaged in a
> +bundle, since the header of the bundle is in a format similar to 'git
> +show-ref'.

As I already said in the review of v6, I do not think "header has a format similar to show-ref" is not something we need to say so prominently to the user.

The reason we should give readers why they must give refs while creating a bundle, I think, is because the only way to access the contents of the bundle is to fetch refs from it, and the refs given to the command when the bundle was created becomes the refs that can be fetched from the bundle.

And that is what the readers should be told here, I think.

Show 8 quoted lines

> +More than one reference may be packaged, and more than one basis can
> +be specified.  The objects packaged are those not contained in the
> +union of the given bases.
> +
> +The 'git bundle create' command resolves the reference names for you
> +using the same rules as `git rev-parse --abbrev-ref=loose`. Each
> +basis can be specified explicitly (e.g. `^master~10`), or implicitly
> +(e.g. `master~10..master`, `--since=10.days.ago master`).

Also, we introduced "prerequisite objects" in the previous step, but here we say "basis". The readers would be helped greatly if we were a bit more consistent.

Show 10 quoted lines

> ...
> +A revision name or a range whose right-hand-side cannot be resolved to
> +a reference is not accepted:
> +
> +----------------
> +$ git bundle create HEAD.bundle $(git rev-parse HEAD)
> +fatal: Refusing to create empty bundle.
> +$ git bundle create master-yesterday.bundle master~10..master~5
> +fatal: Refusing to create empty bundle.
> +----------------

This is a good example, as Philip already said.

Thanks.