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

[Philip Oakley <philipoakley@iee.email>]

On 27/07/2021 01:24, Ævar Arnfjörð Bjarmason wrote:
> Elaborate on the restriction that you cannot provide a revision that
> doesn't resolve to a reference in the "SPECIFYING REFERENCES" section
> with examples.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
>  Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------
>  1 file changed, 39 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
> index f1f84ce2c4..0f28c41409 100644
> --- a/Documentation/git-bundle.txt
> +++ b/Documentation/git-bundle.txt
> @@ -144,14 +144,45 @@ unbundle <file>::
>  SPECIFYING REFERENCES
>  ---------------------
>  
> -'git bundle' will only package references that are shown by
> -'git show-ref': this includes heads, tags, and remote heads.  References
> -such as `master~1` cannot be packaged, but are perfectly suitable for
> -defining the basis.  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.  Each basis can be
> -specified explicitly (e.g. `^master~10`), or implicitly (e.g.
> -`master~10..master`, `--since=10.days.ago master`).
> +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'.
> +
> +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`).
> +
> +All of these simple cases are OK (assuming we have a "master" and
> +"next" branch):
> +
> +----------------
> +$ git bundle create master.bundle master
> +$ echo master | git bundle create master.bundle --stdin
> +$ git bundle create master-and-next.bundle master next
> +$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
> +----------------
> +
> +And so are these (and the same but omitted `--stdin` examples):
> +
> +----------------
> +$ git bundle create recent-master.bundle master~10..master
> +$ git bundle create recent-updates.bundle master~10..master next~5..next
> +----------------
> +
> +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.

I like this example showing the need for a reference name to be part of
the basis, clarifying that part of the description.

Philip

> +----------------
>  
>  OBJECT PREREQUISITES
>  --------------------