| Message ID | patch-3.3-6d66d4480ff-20210720T141611Z-avarab@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | bundle doc: generalize & elaborate | expand |
Æ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'. This may be an improvement in the way how the description refers to "show-ref", but we do not have to say anything about "show-ref" ;-) 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. Thanks.
On 20/07/2021 21:19, Junio C Hamano wrote: > Æ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'. > This may be an improvement in the way how the description refers to > "show-ref", but we do not have to say anything about "show-ref" ;-) > > 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. > > Thanks. > Should the `list-heads` option be mentioned for investigating existing bundles? -- Philip
Philip Oakley <philipoakley@iee.email> writes: > Should the `list-heads` option be mentioned for investigating existing > bundles? I think 'list-heads' has been listed in the options section. I however may encourage people to use "git ls-remote one.bndl" over "git bundle list-heads one.bndl"---they do the same thing, no? Thanks.
On 21/07/2021 17:57, Junio C Hamano wrote: > Philip Oakley <philipoakley@iee.email> writes: > >> Should the `list-heads` option be mentioned for investigating existing >> bundles? > I think 'list-heads' has been listed in the options section. True, it's why I was suggesting pointing at that route for the extra details that are beyond just a set of refs. > I > however may encourage people to use "git ls-remote one.bndl" over > "git bundle list-heads one.bndl"---they do the same thing, no? It is good to provide both directions to the user. The formats may be different but the content is essentially the same, and redirecting users to the more core command is useful. > > Thanks. > > >
On Thu, Jul 22 2021, Philip Oakley wrote: > On 21/07/2021 17:57, Junio C Hamano wrote: >> Philip Oakley <philipoakley@iee.email> writes: >> >>> Should the `list-heads` option be mentioned for investigating existing >>> bundles? >> I think 'list-heads' has been listed in the options section. > > True, it's why I was suggesting pointing at that route for the extra > details that are beyond just a set of refs. > >> I >> however may encourage people to use "git ls-remote one.bndl" over >> "git bundle list-heads one.bndl"---they do the same thing, no? > > It is good to provide both directions to the user. The formats may be > different but the content is essentially the same, and redirecting users > to the more core command is useful. > I'll work those suggestions into a future update of the docs I have queued, but for now I think talking about list-heads v.s. ls-remote doesn't have much directly to do with this particular series, correct?
On 22/07/2021 12:46, Ævar Arnfjörð Bjarmason wrote: > On Thu, Jul 22 2021, Philip Oakley wrote: > >> On 21/07/2021 17:57, Junio C Hamano wrote: >>> Philip Oakley <philipoakley@iee.email> writes: >>> >>>> Should the `list-heads` option be mentioned for investigating existing >>>> bundles? >>> I think 'list-heads' has been listed in the options section. >> True, it's why I was suggesting pointing at that route for the extra >> details that are beyond just a set of refs. >> >>> I >>> however may encourage people to use "git ls-remote one.bndl" over >>> "git bundle list-heads one.bndl"---they do the same thing, no? >> It is good to provide both directions to the user. The formats may be >> different but the content is essentially the same, and redirecting users >> to the more core command is useful. >> > I'll work those suggestions into a future update of the docs I have > queued, but for now I think talking about list-heads v.s. ls-remote > doesn't have much directly to do with this particular series, correct? True. However I'm still not really clear about the distinction between the 'basis' and the `header references` (that is, the text doesn't make it clear). for the future updates, it would also be good if the `--all` and `--branches --tags` text was also shown in the examples - I continue to get StackOverflow points for my Q&A on that ;-) Philip
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index d5627b8cc51..e7a685e533e 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -145,14 +145,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(-)