| Message ID | patch-3.3-88e7ad1cf4-20210727T002001Z-avarab@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | bundle doc: generalize & elaborate | expand |
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 > --------------------
Æ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.
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. +---------------- OBJECT PREREQUISITES --------------------
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(-)