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

[Junio C Hamano <gitster@pobox.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.


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

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