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@xxxxxxxxx> > --- > 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 > --------------------
