{"thread":{"id":"55869","subject":"[PATCH] bundle doc: rewrite the \"DESCRIPTION\" section","startedAt":"2021-06-07T14:37:36Z","lastAt":"2021-07-31T08:23:25Z","messageCount":41,"participants":["Ævar Arnfjörð Bjarmason","Junio C Hamano","Philip Oakley"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"426608","messageId":"patch-1.1-4e736877d1-20210607T143643Z-avarab@gmail.com","threadId":"55869","inReplyTo":null,"subject":"[PATCH] bundle doc: rewrite the \"DESCRIPTION\" section","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-07T14:37:26Z","receivedAt":"2021-06-07T14:37:36Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Rewrite the \"DESCRIPTION\" section for \"git bundle\" to start by talking\nabout what bundles are in general terms, rather than diving directly\ninto one example of what they might be used for. This changes\ndocumentation that's been substantially the same ever since the\ncommand was added in 2e0afafebd8 (Add git-bundle: move objects and\nreferences by archive, 2007-02-22).\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 31 ++++++++++++++++++++++---------\n 1 file changed, 22 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 53804cad4b..1d7c6bdbb2 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -3,7 +3,7 @@ git-bundle(1)\n \n NAME\n ----\n-git-bundle - Move objects and refs by archive\n+git-bundle - Create, unpack and manipulate \"bundles\"\n \n \n SYNOPSIS\n@@ -18,15 +18,25 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Some workflows require that one or more branches of development on one\n-machine be replicated on another machine, but the two machines cannot\n-be directly connected, and therefore the interactive Git protocols (git,\n-ssh, http) cannot be used.\n+Create, unpack and manipulate \"bundles\" (.bundle) files. Bundles are\n+.pack files (see linkgit:git-pack-objects[1]) with a header indicating\n+what references are contained within the bundle. The header is in the\n+format emitted by linkgit:git-show-ref[1].\n \n-The 'git bundle' command packages objects and references in an archive\n-at the originating machine, which can then be imported into another\n-repository using 'git fetch', 'git pull', or 'git clone',\n-after moving the archive by some means (e.g., by sneakernet).\n+Like the the packed archive format itself bundles can either be\n+self-contained or thin (see \"--thin\" in linkgit:git-pack-objects[1]).\n+\n+Bundles are useful for numerous purposes. They were originally\n+designed to facilitate the transfer of repository data between\n+repositories which could not be directly connect to each other, and\n+therefore the interactive Git protocols (git, ssh, http) could not be\n+used.\n+\n+In that scenario a bundle is produced on the originating machine. It\n+is then transferred to the other machine (e.g. by sneakernet), and\n+unpacked on the other end. The unpacking can happen either with\n+linkgit:git-clone[1] (which knows how to clone from bundle files), or\n+by \"git bundle unbundle\".\n \n As no\n direct connection between the repositories exists, the user must specify a\n@@ -34,6 +44,9 @@ basis for the bundle that is held by the destination repository: the\n bundle assumes that all objects in the basis are already in the\n destination repository.\n \n+Similarly, bundles are commonly used to produce incremental backups of\n+git repositories. See the \"EXAMPLES\" section below.\n+\n OPTIONS\n -------\n \n-- \n2.32.0.rc3.434.gd8aed1f08a7\n\n"},{"id":"426629","messageId":"patch-1.1-bc6a6d8922-20210607T165507Z-avarab@gmail.com","threadId":"55869","inReplyTo":"patch-1.1-4e736877d1-20210607T143643Z-avarab@gmail.com","subject":"[PATCH v2] bundle doc: rewrite the \"DESCRIPTION\" section","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-07T16:56:39Z","receivedAt":"2021-06-07T16:56:45Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Rewrite the \"DESCRIPTION\" section for \"git bundle\" to start by talking\nabout what bundles are in general terms, rather than diving directly\ninto one example of what they might be used for. This changes\ndocumentation that's been substantially the same ever since the\ncommand was added in 2e0afafebd8 (Add git-bundle: move objects and\nreferences by archive, 2007-02-22).\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n\nI didn't think I needed to type \"make\" to check a doc-only change, but\nas it turns out v1 of this doesn't compile git because the script to\ngenerate command-list.h doesn't know how to escape the quotes in the\nC-string it generates.\n\nThis is probably better in either case, sorry about the noise.\n\nRange-diff against v1:\n1: 4e736877d1 ! 1: bc6a6d8922 bundle doc: rewrite the \"DESCRIPTION\" section\n @@ Documentation/git-bundle.txt: git-bundle(1)\n NAME\n ----\n -git-bundle - Move objects and refs by archive\n -+git-bundle - Create, unpack and manipulate \"bundles\"\n ++git-bundle - Create, unpack and manipulate bundles\n \n \n SYNOPSIS\n\n Documentation/git-bundle.txt | 31 ++++++++++++++++++++++---------\n 1 file changed, 22 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 53804cad4b..cdc4e0b51b 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -3,7 +3,7 @@ git-bundle(1)\n \n NAME\n ----\n-git-bundle - Move objects and refs by archive\n+git-bundle - Create, unpack and manipulate bundles\n \n \n SYNOPSIS\n@@ -18,15 +18,25 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Some workflows require that one or more branches of development on one\n-machine be replicated on another machine, but the two machines cannot\n-be directly connected, and therefore the interactive Git protocols (git,\n-ssh, http) cannot be used.\n+Create, unpack and manipulate \"bundles\" (.bundle) files. Bundles are\n+.pack files (see linkgit:git-pack-objects[1]) with a header indicating\n+what references are contained within the bundle. The header is in the\n+format emitted by linkgit:git-show-ref[1].\n \n-The 'git bundle' command packages objects and references in an archive\n-at the originating machine, which can then be imported into another\n-repository using 'git fetch', 'git pull', or 'git clone',\n-after moving the archive by some means (e.g., by sneakernet).\n+Like the the packed archive format itself bundles can either be\n+self-contained or thin (see \"--thin\" in linkgit:git-pack-objects[1]).\n+\n+Bundles are useful for numerous purposes. They were originally\n+designed to facilitate the transfer of repository data between\n+repositories which could not be directly connect to each other, and\n+therefore the interactive Git protocols (git, ssh, http) could not be\n+used.\n+\n+In that scenario a bundle is produced on the originating machine. It\n+is then transferred to the other machine (e.g. by sneakernet), and\n+unpacked on the other end. The unpacking can happen either with\n+linkgit:git-clone[1] (which knows how to clone from bundle files), or\n+by \"git bundle unbundle\".\n \n As no\n direct connection between the repositories exists, the user must specify a\n@@ -34,6 +44,9 @@ basis for the bundle that is held by the destination repository: the\n bundle assumes that all objects in the basis are already in the\n destination repository.\n \n+Similarly, bundles are commonly used to produce incremental backups of\n+git repositories. See the \"EXAMPLES\" section below.\n+\n OPTIONS\n -------\n \n-- \n2.32.0.rc3.434.gd8aed1f08a7\n\n"},{"id":"426673","messageId":"xmqqh7i9tfhe.fsf@gitster.g","threadId":"55869","inReplyTo":"patch-1.1-bc6a6d8922-20210607T165507Z-avarab@gmail.com","subject":"Re: [PATCH v2] bundle doc: rewrite the \"DESCRIPTION\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-06-07T23:35:57Z","receivedAt":"2021-06-07T23:36:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Rewrite the \"DESCRIPTION\" section for \"git bundle\" to start by talking\n> about what bundles are in general terms, rather than diving directly\n> into one example of what they might be used for. This changes\n> documentation that's been substantially the same ever since the\n> command was added in 2e0afafebd8 (Add git-bundle: move objects and\n> references by archive, 2007-02-22).\n\nOK.\n\n> NAME\n> ----\n> -git-bundle - Move objects and refs by archive\n> +git-bundle - Create, unpack and manipulate bundles\n\nWhile I find the updated description an improvement, I do not think\nthe updated one-line explanation is. Not that \"archive\" is much\nbetter than \"bundles\", but to those who needs \"git-bundle\" explained,\nit is better not to use the same word \"bundle\" to do so, and worse,\nwhen one does not know what \"bundles\" are, \"do X, Y or Z\" on that\nunknown thing would not help understanding all that much. At least,\nthe original _hints_ that it is related to some way to transport Git\ndata (by mentioning \"objects and refs\"), and those with good instinct\nmay even guess that it is an offline transport (with the hint the\nword \"archive\" leaves).\n\n> -Some workflows require that one or more branches of development on one\n> -machine be replicated on another machine, but the two machines cannot\n> -be directly connected, and therefore the interactive Git protocols (git,\n> -ssh, http) cannot be used.\n> +Create, unpack and manipulate \"bundles\" (.bundle) files. Bundles are\n> +.pack files (see linkgit:git-pack-objects[1]) with a header indicating\n> +what references are contained within the bundle. The header is in the\n> +format emitted by linkgit:git-show-ref[1].\n\nBefore going into the composition of a bundle, can we touch the\nreason why we create such a thing? It is to help \"offline\" Git\ntransfer without common history discovery.\n\nThat is,\n\n\tCreate, unpack, and manipulate \"bundle\" files, that helps\n\t\"offline\" transfer of Git objects without an active \"server\"\n\tsitting on the other side of the network connection.\n\nor something.\n"},{"id":"428423","messageId":"cover-0.3-00000000000-20210624T193730Z-avarab@gmail.com","threadId":"55869","inReplyTo":"patch-1.1-bc6a6d8922-20210607T165507Z-avarab@gmail.com","subject":"[PATCH v3 0/3] bundle doc: generaliz & elaborate","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-24T19:40:25Z","receivedAt":"2021-06-24T19:40:39Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"This started as 1 patch in\nhttps://lore.kernel.org/git/patch-1.1-bc6a6d8922-20210607T165507Z-avarab@gmail.com/\nbut is now 3.\n\nIn rewriting the DESCRIPTION section per Junio's feedback I went on to\nelaborate on the thin v.s. not thin bundles and in 3/3 rewrote some\nprose to make heavier use of show and tell.\n\nPer a certain recent CodingGuidelines discussion about patterns in our\ndocumentation I've long thought that the sort of change I'm doing in\n3/3 is something we could do more of. I.e. replacing somewhat complex\nand dense prose with short paragraphs broken up by simple command\nexamples (and output), whenever possible.\n\nÆvar Arnfjörð Bjarmason (3):\n bundle doc: rewrite the \"DESCRIPTION\" section\n bundle doc: split out thin v.s. not discussion from \n bundle doc: elaborate on rev<->ref restriction\n\n Documentation/git-bundle.txt | 111 +++++++++++++++++++++++++++--------\n 1 file changed, 87 insertions(+), 24 deletions(-)\n\nRange-diff against v2:\n1: bc6a6d89224 ! 1: 2824133f423 bundle doc: rewrite the \"DESCRIPTION\" section\n @@ Commit message\n \n Rewrite the \"DESCRIPTION\" section for \"git bundle\" to start by talking\n about what bundles are in general terms, rather than diving directly\n - into one example of what they might be used for. This changes\n - documentation that's been substantially the same ever since the\n - command was added in 2e0afafebd8 (Add git-bundle: move objects and\n - references by archive, 2007-02-22).\n + into one example of what they might be used for.\n +\n + This changes documentation that's been substantially the same ever\n + since the command was added in 2e0afafebd8 (Add git-bundle: move\n + objects and references by archive, 2007-02-22).\n +\n + I've split up the DESCRIPTION into that section and a \"BUNDLE FORMAT\"\n + section, it briefly discusses the format, but then links to the\n + technical/bundle-format.txt documentation.\n +\n + The \"the user must specify a basis\" part of this is discussed below in\n + \"SPECIFYING REFERENCES\", so I'm removing that part and letting the\n + brief mention of \"thin\" suffice.\n +\n + To the extent that we should say more on the topic that documentation\n + will be improved by subsequent commits.\n \n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/git-bundle.txt ##\n -@@ Documentation/git-bundle.txt: git-bundle(1)\n - \n - NAME\n - ----\n --git-bundle - Move objects and refs by archive\n -+git-bundle - Create, unpack and manipulate bundles\n - \n - \n - SYNOPSIS\n @@ Documentation/git-bundle.txt: SYNOPSIS\n DESCRIPTION\n -----------\n @@ Documentation/git-bundle.txt: SYNOPSIS\n -machine be replicated on another machine, but the two machines cannot\n -be directly connected, and therefore the interactive Git protocols (git,\n -ssh, http) cannot be used.\n -+Create, unpack and manipulate \"bundles\" (.bundle) files. Bundles are\n -+.pack files (see linkgit:git-pack-objects[1]) with a header indicating\n -+what references are contained within the bundle. The header is in the\n -+format emitted by linkgit:git-show-ref[1].\n - \n +-\n -The 'git bundle' command packages objects and references in an archive\n -at the originating machine, which can then be imported into another\n -repository using 'git fetch', 'git pull', or 'git clone',\n -after moving the archive by some means (e.g., by sneakernet).\n +-\n +-As no\n +-direct connection between the repositories exists, the user must specify a\n +-basis for the bundle that is held by the destination repository: the\n +-bundle assumes that all objects in the basis are already in the\n +-destination repository.\n ++Create, unpack, and manipulate \"bundle\" files. Bundles are used for\n ++the \"offline\" transfer of Git objects without an active \"server\"\n ++sitting on the other side of the network connection.\n ++\n ++They can be used to create both incremental and full backups of a\n ++repository, and to relay the state of the references in one repository\n ++to another.\n ++\n ++Other git commands that understand protocols such as `ssh://` and\n ++`https://` can also operate on bundle files. It is possible\n ++linkgit:git-clone[1] a new repository from a bundle, to use\n ++linkgit:git-fetch[1] to fetch from one, and to list the references\n ++contained within it with linkgit:git-ls-remote[1].\n ++\n ++See the \"EXAMPLES\" section below for examples of how to use bundles.\n ++\n ++BUNDLE FORMAT\n ++-------------\n ++\n ++Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a\n ++header indicating what references are contained within the bundle. The\n ++header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n ++\n +Like the the packed archive format itself bundles can either be\n +self-contained or thin (see \"--thin\" in linkgit:git-pack-objects[1]).\n +\n -+Bundles are useful for numerous purposes. They were originally\n -+designed to facilitate the transfer of repository data between\n -+repositories which could not be directly connect to each other, and\n -+therefore the interactive Git protocols (git, ssh, http) could not be\n -+used.\n -+\n -+In that scenario a bundle is produced on the originating machine. It\n -+is then transferred to the other machine (e.g. by sneakernet), and\n -+unpacked on the other end. The unpacking can happen either with\n -+linkgit:git-clone[1] (which knows how to clone from bundle files), or\n -+by \"git bundle unbundle\".\n - \n - As no\n - direct connection between the repositories exists, the user must specify a\n -@@ Documentation/git-bundle.txt: basis for the bundle that is held by the destination repository: the\n - bundle assumes that all objects in the basis are already in the\n - destination repository.\n ++See link:technical/bundle-format.html[the `bundle-format`\n ++documentation] for more details.\n \n -+Similarly, bundles are commonly used to produce incremental backups of\n -+git repositories. See the \"EXAMPLES\" section below.\n -+\n OPTIONS\n -------\n - \n-: ----------- > 2: 63f871a0c72 bundle doc: split out thin v.s. not discussion from \n-: ----------- > 3: 14e4a724fb2 bundle doc: elaborate on rev<->ref restriction\n-- \n2.32.0.610.gd639e370050\n\n"},{"id":"428424","messageId":"patch-1.3-2824133f423-20210624T193730Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210624T193730Z-avarab@gmail.com","subject":"[PATCH v3 1/3] bundle doc: rewrite the \"DESCRIPTION\" section","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-24T19:40:26Z","receivedAt":"2021-06-24T19:40:40Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Rewrite the \"DESCRIPTION\" section for \"git bundle\" to start by talking\nabout what bundles are in general terms, rather than diving directly\ninto one example of what they might be used for.\n\nThis changes documentation that's been substantially the same ever\nsince the command was added in 2e0afafebd8 (Add git-bundle: move\nobjects and references by archive, 2007-02-22).\n\nI've split up the DESCRIPTION into that section and a \"BUNDLE FORMAT\"\nsection, it briefly discusses the format, but then links to the\ntechnical/bundle-format.txt documentation.\n\nThe \"the user must specify a basis\" part of this is discussed below in\n\"SPECIFYING REFERENCES\", so I'm removing that part and letting the\nbrief mention of \"thin\" suffice.\n\nTo the extent that we should say more on the topic that documentation\nwill be improved by subsequent commits.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 43 +++++++++++++++++++++++-------------\n 1 file changed, 28 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 53804cad4b6..1b02f8b7468 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -18,21 +18,34 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Some workflows require that one or more branches of development on one\n-machine be replicated on another machine, but the two machines cannot\n-be directly connected, and therefore the interactive Git protocols (git,\n-ssh, http) cannot be used.\n-\n-The 'git bundle' command packages objects and references in an archive\n-at the originating machine, which can then be imported into another\n-repository using 'git fetch', 'git pull', or 'git clone',\n-after moving the archive by some means (e.g., by sneakernet).\n-\n-As no\n-direct connection between the repositories exists, the user must specify a\n-basis for the bundle that is held by the destination repository: the\n-bundle assumes that all objects in the basis are already in the\n-destination repository.\n+Create, unpack, and manipulate \"bundle\" files. Bundles are used for\n+the \"offline\" transfer of Git objects without an active \"server\"\n+sitting on the other side of the network connection.\n+\n+They can be used to create both incremental and full backups of a\n+repository, and to relay the state of the references in one repository\n+to another.\n+\n+Other git commands that understand protocols such as `ssh://` and\n+`https://` can also operate on bundle files. It is possible\n+linkgit:git-clone[1] a new repository from a bundle, to use\n+linkgit:git-fetch[1] to fetch from one, and to list the references\n+contained within it with linkgit:git-ls-remote[1].\n+\n+See the \"EXAMPLES\" section below for examples of how to use bundles.\n+\n+BUNDLE FORMAT\n+-------------\n+\n+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a\n+header indicating what references are contained within the bundle. The\n+header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n+\n+Like the the packed archive format itself bundles can either be\n+self-contained or thin (see \"--thin\" in linkgit:git-pack-objects[1]).\n+\n+See link:technical/bundle-format.html[the `bundle-format`\n+documentation] for more details.\n \n OPTIONS\n -------\n-- \n2.32.0.610.gd639e370050\n\n"},{"id":"428425","messageId":"patch-2.3-63f871a0c72-20210624T193730Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210624T193730Z-avarab@gmail.com","subject":"[PATCH v3 2/3] bundle doc: split out thin v.s. not discussion from ","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-24T19:40:27Z","receivedAt":"2021-06-24T19:40:41Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Split out the discussion of why you should or should not create \"thin\nbundles\" into a new section, away from the discussion of our handling\nof the rev-args syntax.\n\nSee 2e0afafebd (Add git-bundle: move objects and references by\narchive, 2007-02-22) for the introduction of the documentation being\nchanged here.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 23 +++++++++++++++++++++--\n 1 file changed, 21 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 1b02f8b7468..f231f42b12f 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -42,7 +42,8 @@ header indicating what references are contained within the bundle. The\n header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n \n Like the the packed archive format itself bundles can either be\n-self-contained or thin (see \"--thin\" in linkgit:git-pack-objects[1]).\n+self-contained or thin, see the \"OPEN (THIN) AND CLOSED BUNDLES\"\n+section below.\n \n See link:technical/bundle-format.html[the `bundle-format`\n documentation] for more details.\n@@ -139,7 +140,20 @@ contained in the union of the given bases. Each basis can be\n specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n `master~10..master`, `--since=10.days.ago master`).\n \n-It is very important that the basis used be held by the destination.\n+OPEN (THIN) AND CLOSED BUNDLES\n+------------------------------\n+\n+When creating bundles it is possible to create bundle tips that are\n+either closed or open under reachability, i.e. those that contain all\n+the history needed to get to a given point (closed), and those that do\n+not (open). A revision such as \"master\" will produce a closed tip, a\n+range such as \"master~2..master\" will not (unless the full history is\n+contained within that range).\n+\n+Another name for \"open\" bundles might be \"thin bundles\", as in the\n+`--thin` option to linkgit:git-pack-objects[1]. Under the hood that's\n+what `git bundle create` uses to write bundles. When thin bundles\n+it is very important that the basis used be held by the destination.\n It is okay to err on the side of caution, causing the bundle file\n to contain objects already in the destination, as these are ignored\n when unpacking at the destination.\n@@ -152,6 +166,11 @@ If you want to provide the same set of refs that a clone directly\n from the source repository would get, use `--branches --tags` for\n the ``.\n \n+See the the `--thin` option to linkgit:git-pack-objects[1] noted\n+above, and the discussion of \"thin pack\" in\n+link:technical/pack-format.html[the pack format documentation] for\n+further details.\n+\n EXAMPLES\n --------\n \n-- \n2.32.0.610.gd639e370050\n\n"},{"id":"428426","messageId":"patch-3.3-14e4a724fb2-20210624T193730Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210624T193730Z-avarab@gmail.com","subject":"[PATCH v3 3/3] bundle doc: elaborate on rev<->ref restriction","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-24T19:40:28Z","receivedAt":"2021-06-24T19:40:42Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Elaborate on the restriction that you cannot provide a revision that\ndoesn't resolve to a reference in the \"SPECIFYING REFERENCES\" section\nwith examples.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------\n 1 file changed, 39 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex f231f42b12f..5674e18155a 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -131,14 +131,45 @@ unbundle ::\n SPECIFYING REFERENCES\n ---------------------\n \n-'git bundle' will only package references that are shown by\n-'git show-ref': this includes heads, tags, and remote heads. References\n-such as `master~1` cannot be packaged, but are perfectly suitable for\n-defining the basis. More than one reference may be packaged, and more\n-than one basis can be specified. The objects packaged are those not\n-contained in the union of the given bases. Each basis can be\n-specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n-`master~10..master`, `--since=10.days.ago master`).\n+Revisions must accompanied by reference names to be packaged in a\n+bundle, since the header of the bundle is in a format similar to 'git\n+show-ref'.\n+\n+More than one reference may be packaged, and more than one basis can\n+be specified. The objects packaged are those not contained in the\n+union of the given bases.\n+\n+The 'git bundle create' command resolves the reference names for you\n+using the same rules as `git rev-parse --abbrev-ref=loose`. Each\n+basis can be specified explicitly (e.g. `^master~10`), or implicitly\n+(e.g. `master~10..master`, `--since=10.days.ago master`).\n+\n+All of these simple cases are OK (assuming we have a \"master\" and\n+\"next\" branch):\n+\n+----------------\n+$ git bundle create master.bundle master\n+$ echo master | git bundle create master.bundle --stdin\n+$ git bundle create master-and-next.bundle master next\n+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin\n+----------------\n+\n+And so are these (and the same but omitted `--stdin` examples):\n+\n+----------------\n+$ git bundle create recent-master.bundle master~10..master\n+$ git bundle create recent-updates.bundle master~10..master next~5..next\n+----------------\n+\n+A revision name or a range whose right-hand-side cannot be resolved to\n+a reference is not accepted:\n+\n+----------------\n+$ git bundle create HEAD.bundle $(git rev-parse HEAD)\n+fatal: Refusing to create empty bundle.\n+$ git bundle create master-yesterday.bundle master~10..master~5\n+fatal: Refusing to create empty bundle.\n+----------------\n \n OPEN (THIN) AND CLOSED BUNDLES\n ------------------------------\n-- \n2.32.0.610.gd639e370050\n\n"},{"id":"428713","messageId":"xmqqwnqdz2zu.fsf@gitster.g","threadId":"55869","inReplyTo":"patch-1.3-2824133f423-20210624T193730Z-avarab@gmail.com","subject":"Re: [PATCH v3 1/3] bundle doc: rewrite the \"DESCRIPTION\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-06-29T04:52:37Z","receivedAt":"2021-06-29T04:52:45Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> +Create, unpack, and manipulate \"bundle\" files. Bundles are used for\n> +the \"offline\" transfer of Git objects without an active \"server\"\n> +sitting on the other side of the network connection.\n> +\n> +They can be used to create both incremental and full backups of a\n> +repository, and to relay the state of the references in one repository\n> +to another.\n> +\n> +Other git commands that understand protocols such as `ssh://` and\n> +`https://` can also operate on bundle files. It is possible\n\nI'd rather drop \"Other\", especially given that it is irrelevant if\n\"git bundle\" understands \"://\" or not. Instead, I'd somehow\nlimit the \"git commands\" to those that are meant to \"read\" from the\nother side.\n\nIOW, \"git push git.bndl master\" would not make sense (yet).\n\nThanks.\n"},{"id":"428714","messageId":"xmqqr1glz2zt.fsf@gitster.g","threadId":"55869","inReplyTo":"patch-2.3-63f871a0c72-20210624T193730Z-avarab@gmail.com","subject":"Re: [PATCH v3 2/3] bundle doc: split out thin v.s. not discussion from ","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-06-29T04:52:38Z","receivedAt":"2021-06-29T04:52:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Split out the discussion of why you should or should not create \"thin\n> bundles\" into a new section, away from the discussion of our handling\n> of the rev-args syntax.\n>\n> See 2e0afafebd (Add git-bundle: move objects and references by\n> archive, 2007-02-22) for the introduction of the documentation being\n> changed here.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/git-bundle.txt | 23 +++++++++++++++++++++--\n> 1 file changed, 21 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\n> index 1b02f8b7468..f231f42b12f 100644\n> --- a/Documentation/git-bundle.txt\n> +++ b/Documentation/git-bundle.txt\n> @@ -42,7 +42,8 @@ header indicating what references are contained within the bundle. The\n> header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n> \n> Like the the packed archive format itself bundles can either be\n> -self-contained or thin (see \"--thin\" in linkgit:git-pack-objects[1]).\n> +self-contained or thin, see the \"OPEN (THIN) AND CLOSED BUNDLES\"\n> +section below.\n> \n> See link:technical/bundle-format.html[the `bundle-format`\n> documentation] for more details.\n> @@ -139,7 +140,20 @@ contained in the union of the given bases. Each basis can be\n> specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n> `master~10..master`, `--since=10.days.ago master`).\n> \n> -It is very important that the basis used be held by the destination.\n> +OPEN (THIN) AND CLOSED BUNDLES\n> +------------------------------\n> +\n> +When creating bundles it is possible to create bundle tips that are\n> +either closed or open under reachability, i.e. those that contain all\n> +the history needed to get to a given point (closed), and those that do\n> +not (open). A revision such as \"master\" will produce a closed tip, a\n> +range such as \"master~2..master\" will not (unless the full history is\n> +contained within that range).\n> +\n> +Another name for \"open\" bundles might be \"thin bundles\", as in the\n> +`--thin` option to linkgit:git-pack-objects[1]. Under the hood that's\n> +what `git bundle create` uses to write bundles. When thin bundles\n> +it is very important that the basis used be held by the destination.\n\nWhile it is true that \"thin\" bundle or packfile must have been\ncreated with a commit range with an uninteresting end, presence of\nthe negative end in the range does not necessarily mean the\nresulting packfile or bundle is thin.\n\nIf you want to introduce \"open\" to mean \"some objects reachable from\nthe tip may not be present in the resulting pack/bundle\", that is\nperfectly fine, but \"thin\" is a different concept. For a packfile\nto be \"thin\", it has to be \"open\", but an \"open\" packfile can be\n\"thick\". Even though they are *not* orthogonal concepts, \"thin\"\npackfile is a strict subset of \"open\" packfile.\n\nWhat \"thin\" means is that such a packfile can store an object in a\ndeltified form against a base object that is not in the same\npackfile.\n\n"},{"id":"428813","messageId":"cover-0.3-00000000000-20210630T091548Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210624T193730Z-avarab@gmail.com","subject":"[PATCH v4 0/3] bundle doc: generalize & elaborate","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-30T09:16:25Z","receivedAt":"2021-06-30T09:16:34Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"A re-roll of v3:\nhttp://lore.kernel.org/git/cover-0.3-00000000000-20210624T193730Z-avarab@gmail.com\n\nJunio had comments to the effect that we should mention that we can't\npush into bundles, and that I was confusing \"thin\" v.s. \"open\"\npacks. Both ahve been cleared up in this version. I added a new \"THIN\nBUNDLES\" section after the \"OPEN AND CLOSED BUNDLES\" section.\n\nÆvar Arnfjörð Bjarmason (3):\n bundle doc: rewrite the \"DESCRIPTION\" section\n bundle doc: split out open v.s. closed discussion from \n bundle doc: elaborate on rev<->ref restriction\n\n Documentation/git-bundle.txt | 130 +++++++++++++++++++++++++++--------\n 1 file changed, 103 insertions(+), 27 deletions(-)\n\nRange-diff against v3:\n1: 2824133f423 ! 1: e32e7b3322d bundle doc: rewrite the \"DESCRIPTION\" section\n @@ Documentation/git-bundle.txt: SYNOPSIS\n +repository, and to relay the state of the references in one repository\n +to another.\n +\n -+Other git commands that understand protocols such as `ssh://` and\n -+`https://` can also operate on bundle files. It is possible\n -+linkgit:git-clone[1] a new repository from a bundle, to use\n ++Git commands that fetch or otherwise \"read\" via protocols such as\n ++`ssh://` and `https://` can also operate on bundle files. It is\n ++possible linkgit:git-clone[1] a new repository from a bundle, to use\n +linkgit:git-fetch[1] to fetch from one, and to list the references\n -+contained within it with linkgit:git-ls-remote[1].\n ++contained within it with linkgit:git-ls-remote[1]. There's no\n ++corresponding \"write\" support, i.e.a 'git push' into a bundle is not\n ++supported.\n +\n +See the \"EXAMPLES\" section below for examples of how to use bundles.\n +\n2: 63f871a0c72 ! 2: fe61f20f19f bundle doc: split out thin v.s. not discussion from \n @@ Metadata\n Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - bundle doc: split out thin v.s. not discussion from \n + bundle doc: split out open v.s. closed discussion from \n \n - Split out the discussion of why you should or should not create \"thin\n + Split out the discussion of why you should or should not create \"open\n bundles\" into a new section, away from the discussion of our handling\n of the rev-args syntax.\n \n @@ Documentation/git-bundle.txt: contained in the union of the given bases. Each b\n `master~10..master`, `--since=10.days.ago master`).\n \n -It is very important that the basis used be held by the destination.\n -+OPEN (THIN) AND CLOSED BUNDLES\n -+------------------------------\n +-It is okay to err on the side of caution, causing the bundle file\n +-to contain objects already in the destination, as these are ignored\n +-when unpacking at the destination.\n ++OPEN AND CLOSED BUNDLES\n ++-----------------------\n +\n +When creating bundles it is possible to create bundle tips that are\n +either closed or open under reachability, i.e. those that contain all\n @@ Documentation/git-bundle.txt: contained in the union of the given bases. Each b\n +range such as \"master~2..master\" will not (unless the full history is\n +contained within that range).\n +\n -+Another name for \"open\" bundles might be \"thin bundles\", as in the\n -+`--thin` option to linkgit:git-pack-objects[1]. Under the hood that's\n -+what `git bundle create` uses to write bundles. When thin bundles\n -+it is very important that the basis used be held by the destination.\n - It is okay to err on the side of caution, causing the bundle file\n - to contain objects already in the destination, as these are ignored\n - when unpacking at the destination.\n ++When creating \"open\" bundles it is very important that the basis used\n ++be held by the destination. It is okay to err on the side of caution,\n ++causing the bundle file to contain objects already in the destination,\n ++as these are ignored when unpacking at the destination.\n + \n + `git clone` can use any bundle created without negative refspecs\n + (e.g., `new`, but not `old..new`).\n @@ Documentation/git-bundle.txt: If you want to provide the same set of refs that a clone directly\n from the source repository would get, use `--branches --tags` for\n the ``.\n \n -+See the the `--thin` option to linkgit:git-pack-objects[1] noted\n -+above, and the discussion of \"thin pack\" in\n ++THIN BUNDLES\n ++------------\n ++\n ++Bundles that are \"open\" (see above) are created \"thin\" by using the\n ++`--thin` option to linkgit:git-pack-objects[1]. Whether a bundle (or\n ++packfile) is \"thin\" is a subset of whether it's \"open\". What \"thin\"\n ++means is that such a packfile can store an object in a deltified form\n ++against a base object that is not in the same packfile.\n ++\n ++To put it another way, when creating \"open\" bundles we assume that the\n ++objects leading up to the starting range(s) already exist in the\n ++recipient repository, which allows us to save space. When we run 'git\n ++bundle unbundle' we invoke linkgit:git-index-pack[1] with the\n ++`--fix-thin` option.\n ++\n ++See the discussion of \"thin pack\" in\n +link:technical/pack-format.html[the pack format documentation] for\n +further details.\n +\n3: 14e4a724fb2 ! 3: 9a1c33cb853 bundle doc: elaborate on rev<->ref restriction\n @@ Documentation/git-bundle.txt: unbundle ::\n +fatal: Refusing to create empty bundle.\n +----------------\n \n - OPEN (THIN) AND CLOSED BUNDLES\n - ------------------------------\n + OPEN AND CLOSED BUNDLES\n + -----------------------\n-- \n2.32.0.613.g8e17abc2eb\n\n"},{"id":"428814","messageId":"patch-2.3-fe61f20f19f-20210630T091548Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210630T091548Z-avarab@gmail.com","subject":"[PATCH v4 2/3] bundle doc: split out open v.s. closed discussion from ","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-30T09:16:27Z","receivedAt":"2021-06-30T09:16:37Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Split out the discussion of why you should or should not create \"open\nbundles\" into a new section, away from the discussion of our handling\nof the rev-args syntax.\n\nSee 2e0afafebd (Add git-bundle: move objects and references by\narchive, 2007-02-22) for the introduction of the documentation being\nchanged here.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 40 +++++++++++++++++++++++++++++++-----\n 1 file changed, 35 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex e19c2b83c91..3bb3b71526c 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -44,7 +44,8 @@ header indicating what references are contained within the bundle. The\n header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n \n Like the the packed archive format itself bundles can either be\n-self-contained or thin (see \"--thin\" in linkgit:git-pack-objects[1]).\n+self-contained or thin, see the \"OPEN (THIN) AND CLOSED BUNDLES\"\n+section below.\n \n See link:technical/bundle-format.html[the `bundle-format`\n documentation] for more details.\n@@ -141,10 +142,20 @@ contained in the union of the given bases. Each basis can be\n specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n `master~10..master`, `--since=10.days.ago master`).\n \n-It is very important that the basis used be held by the destination.\n-It is okay to err on the side of caution, causing the bundle file\n-to contain objects already in the destination, as these are ignored\n-when unpacking at the destination.\n+OPEN AND CLOSED BUNDLES\n+-----------------------\n+\n+When creating bundles it is possible to create bundle tips that are\n+either closed or open under reachability, i.e. those that contain all\n+the history needed to get to a given point (closed), and those that do\n+not (open). A revision such as \"master\" will produce a closed tip, a\n+range such as \"master~2..master\" will not (unless the full history is\n+contained within that range).\n+\n+When creating \"open\" bundles it is very important that the basis used\n+be held by the destination. It is okay to err on the side of caution,\n+causing the bundle file to contain objects already in the destination,\n+as these are ignored when unpacking at the destination.\n \n `git clone` can use any bundle created without negative refspecs\n (e.g., `new`, but not `old..new`).\n@@ -154,6 +165,25 @@ If you want to provide the same set of refs that a clone directly\n from the source repository would get, use `--branches --tags` for\n the ``.\n \n+THIN BUNDLES\n+------------\n+\n+Bundles that are \"open\" (see above) are created \"thin\" by using the\n+`--thin` option to linkgit:git-pack-objects[1]. Whether a bundle (or\n+packfile) is \"thin\" is a subset of whether it's \"open\". What \"thin\"\n+means is that such a packfile can store an object in a deltified form\n+against a base object that is not in the same packfile.\n+\n+To put it another way, when creating \"open\" bundles we assume that the\n+objects leading up to the starting range(s) already exist in the\n+recipient repository, which allows us to save space. When we run 'git\n+bundle unbundle' we invoke linkgit:git-index-pack[1] with the\n+`--fix-thin` option.\n+\n+See the discussion of \"thin pack\" in\n+link:technical/pack-format.html[the pack format documentation] for\n+further details.\n+\n EXAMPLES\n --------\n \n-- \n2.32.0.613.g8e17abc2eb\n\n"},{"id":"428815","messageId":"patch-1.3-e32e7b3322d-20210630T091548Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210630T091548Z-avarab@gmail.com","subject":"[PATCH v4 1/3] bundle doc: rewrite the \"DESCRIPTION\" section","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-30T09:16:26Z","receivedAt":"2021-06-30T09:16:38Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Rewrite the \"DESCRIPTION\" section for \"git bundle\" to start by talking\nabout what bundles are in general terms, rather than diving directly\ninto one example of what they might be used for.\n\nThis changes documentation that's been substantially the same ever\nsince the command was added in 2e0afafebd8 (Add git-bundle: move\nobjects and references by archive, 2007-02-22).\n\nI've split up the DESCRIPTION into that section and a \"BUNDLE FORMAT\"\nsection, it briefly discusses the format, but then links to the\ntechnical/bundle-format.txt documentation.\n\nThe \"the user must specify a basis\" part of this is discussed below in\n\"SPECIFYING REFERENCES\", so I'm removing that part and letting the\nbrief mention of \"thin\" suffice.\n\nTo the extent that we should say more on the topic that documentation\nwill be improved by subsequent commits.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 45 ++++++++++++++++++++++++------------\n 1 file changed, 30 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 53804cad4b6..e19c2b83c91 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -18,21 +18,36 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Some workflows require that one or more branches of development on one\n-machine be replicated on another machine, but the two machines cannot\n-be directly connected, and therefore the interactive Git protocols (git,\n-ssh, http) cannot be used.\n-\n-The 'git bundle' command packages objects and references in an archive\n-at the originating machine, which can then be imported into another\n-repository using 'git fetch', 'git pull', or 'git clone',\n-after moving the archive by some means (e.g., by sneakernet).\n-\n-As no\n-direct connection between the repositories exists, the user must specify a\n-basis for the bundle that is held by the destination repository: the\n-bundle assumes that all objects in the basis are already in the\n-destination repository.\n+Create, unpack, and manipulate \"bundle\" files. Bundles are used for\n+the \"offline\" transfer of Git objects without an active \"server\"\n+sitting on the other side of the network connection.\n+\n+They can be used to create both incremental and full backups of a\n+repository, and to relay the state of the references in one repository\n+to another.\n+\n+Git commands that fetch or otherwise \"read\" via protocols such as\n+`ssh://` and `https://` can also operate on bundle files. It is\n+possible linkgit:git-clone[1] a new repository from a bundle, to use\n+linkgit:git-fetch[1] to fetch from one, and to list the references\n+contained within it with linkgit:git-ls-remote[1]. There's no\n+corresponding \"write\" support, i.e.a 'git push' into a bundle is not\n+supported.\n+\n+See the \"EXAMPLES\" section below for examples of how to use bundles.\n+\n+BUNDLE FORMAT\n+-------------\n+\n+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a\n+header indicating what references are contained within the bundle. The\n+header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n+\n+Like the the packed archive format itself bundles can either be\n+self-contained or thin (see \"--thin\" in linkgit:git-pack-objects[1]).\n+\n+See link:technical/bundle-format.html[the `bundle-format`\n+documentation] for more details.\n \n OPTIONS\n -------\n-- \n2.32.0.613.g8e17abc2eb\n\n"},{"id":"428816","messageId":"patch-3.3-9a1c33cb853-20210630T091548Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210630T091548Z-avarab@gmail.com","subject":"[PATCH v4 3/3] bundle doc: elaborate on rev<->ref restriction","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-06-30T09:16:28Z","receivedAt":"2021-06-30T09:16:38Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Elaborate on the restriction that you cannot provide a revision that\ndoesn't resolve to a reference in the \"SPECIFYING REFERENCES\" section\nwith examples.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------\n 1 file changed, 39 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 3bb3b71526c..2216b9f2843 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -133,14 +133,45 @@ unbundle ::\n SPECIFYING REFERENCES\n ---------------------\n \n-'git bundle' will only package references that are shown by\n-'git show-ref': this includes heads, tags, and remote heads. References\n-such as `master~1` cannot be packaged, but are perfectly suitable for\n-defining the basis. More than one reference may be packaged, and more\n-than one basis can be specified. The objects packaged are those not\n-contained in the union of the given bases. Each basis can be\n-specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n-`master~10..master`, `--since=10.days.ago master`).\n+Revisions must accompanied by reference names to be packaged in a\n+bundle, since the header of the bundle is in a format similar to 'git\n+show-ref'.\n+\n+More than one reference may be packaged, and more than one basis can\n+be specified. The objects packaged are those not contained in the\n+union of the given bases.\n+\n+The 'git bundle create' command resolves the reference names for you\n+using the same rules as `git rev-parse --abbrev-ref=loose`. Each\n+basis can be specified explicitly (e.g. `^master~10`), or implicitly\n+(e.g. `master~10..master`, `--since=10.days.ago master`).\n+\n+All of these simple cases are OK (assuming we have a \"master\" and\n+\"next\" branch):\n+\n+----------------\n+$ git bundle create master.bundle master\n+$ echo master | git bundle create master.bundle --stdin\n+$ git bundle create master-and-next.bundle master next\n+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin\n+----------------\n+\n+And so are these (and the same but omitted `--stdin` examples):\n+\n+----------------\n+$ git bundle create recent-master.bundle master~10..master\n+$ git bundle create recent-updates.bundle master~10..master next~5..next\n+----------------\n+\n+A revision name or a range whose right-hand-side cannot be resolved to\n+a reference is not accepted:\n+\n+----------------\n+$ git bundle create HEAD.bundle $(git rev-parse HEAD)\n+fatal: Refusing to create empty bundle.\n+$ git bundle create master-yesterday.bundle master~10..master~5\n+fatal: Refusing to create empty bundle.\n+----------------\n \n OPEN AND CLOSED BUNDLES\n -----------------------\n-- \n2.32.0.613.g8e17abc2eb\n\n"},{"id":"428853","messageId":"xmqqk0mbt5rj.fsf@gitster.g","threadId":"55869","inReplyTo":"patch-2.3-fe61f20f19f-20210630T091548Z-avarab@gmail.com","subject":"Re: [PATCH v4 2/3] bundle doc: split out open v.s. closed discussion from ","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-06-30T21:13:52Z","receivedAt":"2021-06-30T21:14:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Split out the discussion of why you should or should not create \"open\n> bundles\" into a new section, away from the discussion of our handling\n> of the rev-args syntax.\n\nI changed my mind about this part.\n\n * There is no option to create a bundle with one or more\n prerequisite commits with a non-thin packfile as its payload\n part. So \"THIN BUNDLE\" is an unnecessary new jargon and concept\n that does not help readers at all, because there is no \"thick\n bundle\" that has prerequisite commits. Let's not introduce such\n a new word.\n\n * We do not call DAG in our history with bottom end (i.e. a range\n with one or more uninteresting commits) an \"open history\". Let's\n not invent the words, \"open\" vs \"close\", to describe the history\n recorded in a bundle, either.\n\nWe do already have an appropriate phrase we can use to explain what\nyou wrote in open/close section: \"the prerequisite commits\" (find it\nin the description of \"verify\" subcommand) and that has been a\nconcept well understood for a long time, ever since 2e0afafe (Add\ngit-bundle: move objects and references by archive, 2007-02-22)\nintroduced the bundle format. Let's use that phrase, instead of\ninventing a new word.\n\nIn short, there are two kinds of bundles.\n\n - A bundle with one or more prerequisite commits can only be\n extracted in a repository that already has all these prerequisite\n commits and the history behind them, and \"git bundle verify\" is\n an easy way to check if your recipient repository has the\n prerequisites. The payload in such a bundle is always a thin\n packfile, but such a technical detail does not concern readers.\n\n - A bundle without any prerequisites can be extracted into\n anywhere, even into an empty repository, or cloned from it.\n\nAnd that should be sufficient to base your new paragraph(s).\n\nSorry for having made a potentially confusing comment earlier. What\nI said about open vs thin was technically correct (i.e. there wasn't\nfundamental reason why a bundle with prerequisites MUST use a thin\npack as its payload---we designed it that way because such a bundle\nMUST be extracted in a repository with these prerequisites present,\nhence it was OK to assume that a --fix-thin would work while\nextracting such a bundle), but it is irrelevant in practice because\nyou cannot ask for a thick packfile to be created when creating such\na bundle anyway.\n\nThanks.\n"},{"id":"429028","messageId":"patch-1.3-3b447500da9-20210702T112254Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210702T112254Z-avarab@gmail.com","subject":"[PATCH v5 1/3] bundle doc: rewrite the \"DESCRIPTION\" section","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-02T11:26:53Z","receivedAt":"2021-07-02T11:27:01Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Rewrite the \"DESCRIPTION\" section for \"git bundle\" to start by talking\nabout what bundles are in general terms, rather than diving directly\ninto one example of what they might be used for.\n\nThis changes documentation that's been substantially the same ever\nsince the command was added in 2e0afafebd8 (Add git-bundle: move\nobjects and references by archive, 2007-02-22).\n\nI've split up the DESCRIPTION into that section and a \"BUNDLE FORMAT\"\nsection, it briefly discusses the format, but then links to the\ntechnical/bundle-format.txt documentation.\n\nThe \"the user must specify a basis\" part of this is discussed below in\n\"SPECIFYING REFERENCES\", and will be further elaborated on in a\nsubsequent commit. So I'm removing that part and letting the mention\nof \"revision exclusions\" suffice.\n\nThere was a discussion about whether to say anything at all about\n\"thin packs\" here[1]. I think it's good to mention it for the curious\nreader willing to read the technical docs, but let's explicitly say\nthat there's no \"thick pack\", and that the difference shouldn't\nmatter.\n\n1. http://lore.kernel.org/git/xmqqk0mbt5rj.fsf@gitster.g\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 57 ++++++++++++++++++++++++++----------\n 1 file changed, 42 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 53804cad4b6..9c743aed49f 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -18,21 +18,48 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Some workflows require that one or more branches of development on one\n-machine be replicated on another machine, but the two machines cannot\n-be directly connected, and therefore the interactive Git protocols (git,\n-ssh, http) cannot be used.\n-\n-The 'git bundle' command packages objects and references in an archive\n-at the originating machine, which can then be imported into another\n-repository using 'git fetch', 'git pull', or 'git clone',\n-after moving the archive by some means (e.g., by sneakernet).\n-\n-As no\n-direct connection between the repositories exists, the user must specify a\n-basis for the bundle that is held by the destination repository: the\n-bundle assumes that all objects in the basis are already in the\n-destination repository.\n+Create, unpack, and manipulate \"bundle\" files. Bundles are used for\n+the \"offline\" transfer of Git objects without an active \"server\"\n+sitting on the other side of the network connection.\n+\n+They can be used to create both incremental and full backups of a\n+repository, and to relay the state of the references in one repository\n+to another.\n+\n+Git commands that fetch or otherwise \"read\" via protocols such as\n+`ssh://` and `https://` can also operate on bundle files. It is\n+possible linkgit:git-clone[1] a new repository from a bundle, to use\n+linkgit:git-fetch[1] to fetch from one, and to list the references\n+contained within it with linkgit:git-ls-remote[1]. There's no\n+corresponding \"write\" support, i.e.a 'git push' into a bundle is not\n+supported.\n+\n+See the \"EXAMPLES\" section below for examples of how to use bundles.\n+\n+BUNDLE FORMAT\n+-------------\n+\n+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a\n+header indicating what references are contained within the bundle. The\n+header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n+\n+Like the the packed archive format itself bundles can either be\n+self-contained, or be created using exclusions.\n+\n+Bundles created using revision exclusions are \"thin packs\" created\n+using the `--thin` option to linkgit:git-pack-objects[1], and\n+unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].\n+\n+There is no option to create a \"thick pack\" when using revision\n+exclusions, users should not be concerned about the difference. By\n+using \"thin packs\" bundles created using exclusions are smaller in\n+size. That they're \"thin\" under the hood is merely noted here as a\n+curiosity, and as a reference to other documentation\n+\n+See link:technical/bundle-format.html[the `bundle-format`\n+documentation] for more details and the discussion of \"thin pack\" in\n+link:technical/pack-format.html[the pack format documentation] for\n+further details.\n \n OPTIONS\n -------\n-- \n2.32.0.632.g49a94b9226d\n\n"},{"id":"429029","messageId":"cover-0.3-00000000000-20210702T112254Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210630T091548Z-avarab@gmail.com","subject":"[PATCH v5 0/3] bundle doc: generalize & elaborate","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-02T11:26:52Z","receivedAt":"2021-07-02T11:27:01Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"A v5 of improvements to the \"git bundle\" documentation. See\nhttp://lore.kernel.org/git/cover-0.3-00000000000-20210630T091548Z-avarab@gmail.com\nfor v4.\n\nThis hopefully addresses Junio's concern in\nhttps://lore.kernel.org/git/xmqqk0mbt5rj.fsf@gitster.g/\n\nI didn't remove the discussion of \"thin packs\" entirely, but now the\nwhole section about \"open\" v.s. \"closed\" doesn't use that wording at\nall, we now talk only about whether a bundle includes prerequisite\ncommits, and use the same language as git-rev-list does when referring\nto \"exclusions'.\n\nThe mention of \"think pack\" is left in the \"BUNDLE FORMAT\"\nsection. It's made clear that it doesn't matter to the end result, but\nthat it's noted as a reference to other docs. We then go on to link to\nthe bundle & pack technical format docs for the overly curious.\n\nÆvar Arnfjörð Bjarmason (3):\n bundle doc: rewrite the \"DESCRIPTION\" section\n bundle doc: elaborate on object prerequisites\n bundle doc: elaborate on rev<->ref restriction\n\n Documentation/git-bundle.txt | 130 ++++++++++++++++++++++++++++-------\n 1 file changed, 104 insertions(+), 26 deletions(-)\n\nRange-diff against v4:\n1: d10060a237e ! 1: 3b447500da9 bundle doc: rewrite the \"DESCRIPTION\" section\n @@ Commit message\n technical/bundle-format.txt documentation.\n \n The \"the user must specify a basis\" part of this is discussed below in\n - \"SPECIFYING REFERENCES\", so I'm removing that part and letting the\n - brief mention of \"thin\" suffice.\n + \"SPECIFYING REFERENCES\", and will be further elaborated on in a\n + subsequent commit. So I'm removing that part and letting the mention\n + of \"revision exclusions\" suffice.\n \n - To the extent that we should say more on the topic that documentation\n - will be improved by subsequent commits.\n + There was a discussion about whether to say anything at all about\n + \"thin packs\" here[1]. I think it's good to mention it for the curious\n + reader willing to read the technical docs, but let's explicitly say\n + that there's no \"thick pack\", and that the difference shouldn't\n + matter.\n +\n + 1. http://lore.kernel.org/git/xmqqk0mbt5rj.fsf@gitster.g\n \n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n @@ Documentation/git-bundle.txt: SYNOPSIS\n +header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n +\n +Like the the packed archive format itself bundles can either be\n -+self-contained or thin (see \"--thin\" in linkgit:git-pack-objects[1]).\n ++self-contained, or be created using exclusions.\n ++\n ++Bundles created using revision exclusions are \"thin packs\" created\n ++using the `--thin` option to linkgit:git-pack-objects[1], and\n ++unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].\n ++\n ++There is no option to create a \"thick pack\" when using revision\n ++exclusions, users should not be concerned about the difference. By\n ++using \"thin packs\" bundles created using exclusions are smaller in\n ++size. That they're \"thin\" under the hood is merely noted here as a\n ++curiosity, and as a reference to other documentation\n +\n +See link:technical/bundle-format.html[the `bundle-format`\n -+documentation] for more details.\n ++documentation] for more details and the discussion of \"thin pack\" in\n ++link:technical/pack-format.html[the pack format documentation] for\n ++further details.\n \n OPTIONS\n -------\n2: 6a312fbdb01 ! 2: 444b06740bc bundle doc: split out open v.s. closed discussion from \n @@ Metadata\n Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - bundle doc: split out open v.s. closed discussion from \n + bundle doc: elaborate on object prerequisites\n \n - Split out the discussion of why you should or should not create \"open\n - bundles\" into a new section, away from the discussion of our handling\n - of the rev-args syntax.\n + Split out the discussion bout \"object prerequisites\" into its own\n + section, and add some more examples of the common cases.\n \n See 2e0afafebd (Add git-bundle: move objects and references by\n archive, 2007-02-22) for the introduction of the documentation being\n @@ Commit message\n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/git-bundle.txt ##\n -@@ Documentation/git-bundle.txt: header indicating what references are contained within the bundle. The\n - header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n +@@ Documentation/git-bundle.txt: header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n \n Like the the packed archive format itself bundles can either be\n --self-contained or thin (see \"--thin\" in linkgit:git-pack-objects[1]).\n -+self-contained or thin, see the \"OPEN (THIN) AND CLOSED BUNDLES\"\n -+section below.\n + self-contained, or be created using exclusions.\n ++See the \"OBJECT PREREQUISITES\" section below.\n \n - See link:technical/bundle-format.html[the `bundle-format`\n - documentation] for more details.\n + Bundles created using revision exclusions are \"thin packs\" created\n + using the `--thin` option to linkgit:git-pack-objects[1], and\n @@ Documentation/git-bundle.txt: contained in the union of the given bases. Each basis can be\n specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n `master~10..master`, `--since=10.days.ago master`).\n \n -It is very important that the basis used be held by the destination.\n --It is okay to err on the side of caution, causing the bundle file\n --to contain objects already in the destination, as these are ignored\n --when unpacking at the destination.\n -+OPEN AND CLOSED BUNDLES\n -+-----------------------\n ++OBJECT PREREQUISITES\n ++--------------------\n +\n -+When creating bundles it is possible to create bundle tips that are\n -+either closed or open under reachability, i.e. those that contain all\n -+the history needed to get to a given point (closed), and those that do\n -+not (open). A revision such as \"master\" will produce a closed tip, a\n -+range such as \"master~2..master\" will not (unless the full history is\n -+contained within that range).\n ++When creating bundles it is possible to create a fully self-contained\n ++bundle with all the prerequisite objects, as well as providing\n ++negative revisions to exclude prerequisite objects.\n +\n -+When creating \"open\" bundles it is very important that the basis used\n -+be held by the destination. It is okay to err on the side of caution,\n -+causing the bundle file to contain objects already in the destination,\n -+as these are ignored when unpacking at the destination.\n ++A revision such as `new` will produce a tip with all the prerequisite\n ++objects needed for the `new` reference.\n ++\n ++A revision range such as `old..new` will produce a bundle tip that'll\n ++require any objects existing before `new` to already be present in the\n ++repository performing the 'git bundle unbundle' operation.\n ++\n ++A self-contained bundle without any prerequisites can be extracted\n ++into anywhere, even into an empty repository, or be cloned from\n ++(i.e., `new`, but not `old..new`).\n ++\n + It is okay to err on the side of caution, causing the bundle file\n + to contain objects already in the destination, as these are ignored\n + when unpacking at the destination.\n \n - `git clone` can use any bundle created without negative refspecs\n - (e.g., `new`, but not `old..new`).\n -@@ Documentation/git-bundle.txt: If you want to provide the same set of refs that a clone directly\n +-`git clone` can use any bundle created without negative refspecs\n +-(e.g., `new`, but not `old..new`).\n + If you want to match `git clone --mirror`, which would include your\n + refs such as `refs/remotes/*`, use `--all`.\n + If you want to provide the same set of refs that a clone directly\n from the source repository would get, use `--branches --tags` for\n the ``.\n \n -+THIN BUNDLES\n -+------------\n -+\n -+Bundles that are \"open\" (see above) are created \"thin\" by using the\n -+`--thin` option to linkgit:git-pack-objects[1]. Whether a bundle (or\n -+packfile) is \"thin\" is a subset of whether it's \"open\". What \"thin\"\n -+means is that such a packfile can store an object in a deltified form\n -+against a base object that is not in the same packfile.\n -+\n -+To put it another way, when creating \"open\" bundles we assume that the\n -+objects leading up to the starting range(s) already exist in the\n -+recipient repository, which allows us to save space. When we run 'git\n -+bundle unbundle' we invoke linkgit:git-index-pack[1] with the\n -+`--fix-thin` option.\n -+\n -+See the discussion of \"thin pack\" in\n -+link:technical/pack-format.html[the pack format documentation] for\n -+further details.\n ++The 'git bundle verify' command can be used to check whether your\n ++recipient repository has the required prerequisite commits for a\n ++bundle.\n +\n EXAMPLES\n --------\n3: 47b8dacb4aa ! 3: 6d8f2f27088 bundle doc: elaborate on rev<->ref restriction\n @@ Documentation/git-bundle.txt: unbundle ::\n +fatal: Refusing to create empty bundle.\n +----------------\n \n - OPEN AND CLOSED BUNDLES\n - -----------------------\n + OBJECT PREREQUISITES\n + --------------------\n-- \n2.32.0.632.g49a94b9226d\n\n"},{"id":"429030","messageId":"patch-2.3-444b06740bc-20210702T112254Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210702T112254Z-avarab@gmail.com","subject":"[PATCH v5 2/3] bundle doc: elaborate on object prerequisites","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-02T11:26:54Z","receivedAt":"2021-07-02T11:27:04Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Split out the discussion bout \"object prerequisites\" into its own\nsection, and add some more examples of the common cases.\n\nSee 2e0afafebd (Add git-bundle: move objects and references by\narchive, 2007-02-22) for the introduction of the documentation being\nchanged here.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 26 +++++++++++++++++++++++---\n 1 file changed, 23 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 9c743aed49f..f5430029b8c 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -45,6 +45,7 @@ header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n \n Like the the packed archive format itself bundles can either be\n self-contained, or be created using exclusions.\n+See the \"OBJECT PREREQUISITES\" section below.\n \n Bundles created using revision exclusions are \"thin packs\" created\n using the `--thin` option to linkgit:git-pack-objects[1], and\n@@ -153,19 +154,38 @@ contained in the union of the given bases. Each basis can be\n specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n `master~10..master`, `--since=10.days.ago master`).\n \n-It is very important that the basis used be held by the destination.\n+OBJECT PREREQUISITES\n+--------------------\n+\n+When creating bundles it is possible to create a fully self-contained\n+bundle with all the prerequisite objects, as well as providing\n+negative revisions to exclude prerequisite objects.\n+\n+A revision such as `new` will produce a tip with all the prerequisite\n+objects needed for the `new` reference.\n+\n+A revision range such as `old..new` will produce a bundle tip that'll\n+require any objects existing before `new` to already be present in the\n+repository performing the 'git bundle unbundle' operation.\n+\n+A self-contained bundle without any prerequisites can be extracted\n+into anywhere, even into an empty repository, or be cloned from\n+(i.e., `new`, but not `old..new`).\n+\n It is okay to err on the side of caution, causing the bundle file\n to contain objects already in the destination, as these are ignored\n when unpacking at the destination.\n \n-`git clone` can use any bundle created without negative refspecs\n-(e.g., `new`, but not `old..new`).\n If you want to match `git clone --mirror`, which would include your\n refs such as `refs/remotes/*`, use `--all`.\n If you want to provide the same set of refs that a clone directly\n from the source repository would get, use `--branches --tags` for\n the ``.\n \n+The 'git bundle verify' command can be used to check whether your\n+recipient repository has the required prerequisite commits for a\n+bundle.\n+\n EXAMPLES\n --------\n \n-- \n2.32.0.632.g49a94b9226d\n\n"},{"id":"429031","messageId":"patch-3.3-6d8f2f27088-20210702T112254Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210702T112254Z-avarab@gmail.com","subject":"[PATCH v5 3/3] bundle doc: elaborate on rev<->ref restriction","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-02T11:26:55Z","receivedAt":"2021-07-02T11:27:04Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Elaborate on the restriction that you cannot provide a revision that\ndoesn't resolve to a reference in the \"SPECIFYING REFERENCES\" section\nwith examples.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------\n 1 file changed, 39 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex f5430029b8c..9a96afedaf3 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -145,14 +145,45 @@ unbundle ::\n SPECIFYING REFERENCES\n ---------------------\n \n-'git bundle' will only package references that are shown by\n-'git show-ref': this includes heads, tags, and remote heads. References\n-such as `master~1` cannot be packaged, but are perfectly suitable for\n-defining the basis. More than one reference may be packaged, and more\n-than one basis can be specified. The objects packaged are those not\n-contained in the union of the given bases. Each basis can be\n-specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n-`master~10..master`, `--since=10.days.ago master`).\n+Revisions must accompanied by reference names to be packaged in a\n+bundle, since the header of the bundle is in a format similar to 'git\n+show-ref'.\n+\n+More than one reference may be packaged, and more than one basis can\n+be specified. The objects packaged are those not contained in the\n+union of the given bases.\n+\n+The 'git bundle create' command resolves the reference names for you\n+using the same rules as `git rev-parse --abbrev-ref=loose`. Each\n+basis can be specified explicitly (e.g. `^master~10`), or implicitly\n+(e.g. `master~10..master`, `--since=10.days.ago master`).\n+\n+All of these simple cases are OK (assuming we have a \"master\" and\n+\"next\" branch):\n+\n+----------------\n+$ git bundle create master.bundle master\n+$ echo master | git bundle create master.bundle --stdin\n+$ git bundle create master-and-next.bundle master next\n+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin\n+----------------\n+\n+And so are these (and the same but omitted `--stdin` examples):\n+\n+----------------\n+$ git bundle create recent-master.bundle master~10..master\n+$ git bundle create recent-updates.bundle master~10..master next~5..next\n+----------------\n+\n+A revision name or a range whose right-hand-side cannot be resolved to\n+a reference is not accepted:\n+\n+----------------\n+$ git bundle create HEAD.bundle $(git rev-parse HEAD)\n+fatal: Refusing to create empty bundle.\n+$ git bundle create master-yesterday.bundle master~10..master~5\n+fatal: Refusing to create empty bundle.\n+----------------\n \n OBJECT PREREQUISITES\n --------------------\n-- \n2.32.0.632.g49a94b9226d\n\n"},{"id":"429056","messageId":"xmqq7di8rbtj.fsf@gitster.g","threadId":"55869","inReplyTo":"patch-2.3-444b06740bc-20210702T112254Z-avarab@gmail.com","subject":"Re: [PATCH v5 2/3] bundle doc: elaborate on object prerequisites","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-07-02T15:10:32Z","receivedAt":"2021-07-02T15:10:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Split out the discussion bout \"object prerequisites\" into its own\n> section, and add some more examples of the common cases.\n>\n> See 2e0afafebd (Add git-bundle: move objects and references by\n> archive, 2007-02-22) for the introduction of the documentation being\n> changed here.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/git-bundle.txt | 26 +++++++++++++++++++++++---\n> 1 file changed, 23 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\n> index 9c743aed49f..f5430029b8c 100644\n> --- a/Documentation/git-bundle.txt\n> +++ b/Documentation/git-bundle.txt\n> @@ -45,6 +45,7 @@ header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n> \n> Like the the packed archive format itself bundles can either be\n> self-contained, or be created using exclusions.\n> +See the \"OBJECT PREREQUISITES\" section below.\n> \n> Bundles created using revision exclusions are \"thin packs\" created\n> using the `--thin` option to linkgit:git-pack-objects[1], and\n> @@ -153,19 +154,38 @@ contained in the union of the given bases. Each basis can be\n> specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n> `master~10..master`, `--since=10.days.ago master`).\n> \n> -It is very important that the basis used be held by the destination.\n> +OBJECT PREREQUISITES\n> +--------------------\n> +\n> +When creating bundles it is possible to create a fully self-contained\n> +bundle with all the prerequisite objects, as well as providing\n> +negative revisions to exclude prerequisite objects.\n> +\n> +A revision such as `new` will produce a tip with all the prerequisite\n> +objects needed for the `new` reference.\n\nThe above two paragraphs use the word \"prerequisites\" in a confusing\nway. The original meaning of the word in the context of talking\nabout a bundle is \"you must have these commits in the receiving\nrepository for the bundle to be unbundle-able\".\n\n\"git bundle create recent.bndl old..new\" creates a bundle that\nrequires 'old' (and everything reachable from it) to exist in the\nreceiving repository. We call the object 'old' (not the objects\nreachable from it) the prerequisite of the bundle.\n\n\"git bundle create full.bndl new\" creates a bundle that needs no\nprerequistes.\n\nIt is confusing to say that full.bndl has all the prerequisite\nobjects needed. It is correct to say that it has all the objects\nreachable from 'new', but if we wanted to say that, we did not have\nto introduce the new term \"prerequisite\" when we invented the bundle\nformat. The concept \"prerequisite\" tries to convey is different.\n\nSo, the two paragraphs above use the word \"prerequisite\" when it\nwants to talk about \"reachable objects\" (except for one use---the\none in \"to exclude prerequisite objects\" is correctly used), which\nis confusing. Here is the first paragraph with probably a better\nphrasing.\n\n\t... it is possible to create a self-contained bundle that\n\tcan be unbundled in an empty repository, as well as\n\tproviding negative revisions to exclude objects needed in\n\tthe earlier parts of the history.\n\nAs to the second paragraph:\n\n\t... will produce a bundle without any prerequisites. It can\n\tbe unbundled in any repository to obtain a full history that\n\tleads to the commit `new`.\n\nBy the way, I needed to read \"a revision such as `new` will produce\n...\" three times before realizing that the reader must fill quite a\nlot of missing words to understand what the sentence wanted to say,\nwhich is:\n\n\t(feeding) a revision such as `new` (to \"git bundle create\"\n\tas the revision range argument) will produce ...\n\nI think it is easier to follow if you spelled the command out, e.g.\n\n A command\n\n $ git bundle create full.bndl new\n\n will create a bundle file that contains all the objects\n reachable from the branch 'new'.\n\n> +A revision range such as `old..new` will produce a bundle tip that'll\n> +require any objects existing before `new` to already be present in the\n> +repository performing the 'git bundle unbundle' operation.\n\nGetting warmer ;-). In this case, 'old' is the prerequisite, so\n\n ... that'll require the commit 'old' (and any objects reachable\n from it) to exist for the bundle to be \"unbundle\"-able.\n\nwould be correct.\n\n> +A self-contained bundle without any prerequisites can be extracted\n> +into anywhere, even into an empty repository, or be cloned from\n> +(i.e., `new`, but not `old..new`).\n> +\n\nThis is entirely correct.\n\n> +The 'git bundle verify' command can be used to check whether your\n> +recipient repository has the required prerequisite commits for a\n> +bundle.\n\nSo is this.\n\nThanks.\n"},{"id":"430625","messageId":"cover-0.3-00000000000-20210720T141611Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210702T112254Z-avarab@gmail.com","subject":"[PATCH v6 0/3] bundle doc: generalize & elaborate","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-20T14:20:23Z","receivedAt":"2021-07-20T14:27:29Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"A v6 of improvements to the \"git bundle\" documentation. See\nhttps://lore.kernel.org/git/cover-0.3-00000000000-20210702T112254Z-avarab@gmail.com/\nfor v5.\n\nJunio, I think this addresess the points you raised in\nhttps://lore.kernel.org/git/xmqq7di8rbtj.fsf@gitster.g/\n\nI used your suggested wording, but changed \"empty repository\" to \"a\nrepository with no common history\" for the purposes of the\ndocumentation that's trying to talk about what you can unbundle where\nwithout ambiguity.\n\nÆvar Arnfjörð Bjarmason (3):\n bundle doc: rewrite the \"DESCRIPTION\" section\n bundle doc: elaborate on object prerequisites\n bundle doc: elaborate on rev<->ref restriction\n\n Documentation/git-bundle.txt | 141 ++++++++++++++++++++++++++++-------\n 1 file changed, 115 insertions(+), 26 deletions(-)\n\nRange-diff against v5:\n1: 3b447500da9 = 1: d5360bb6f74 bundle doc: rewrite the \"DESCRIPTION\" section\n2: 444b06740bc ! 2: a0f95ce3a1d bundle doc: elaborate on object prerequisites\n @@ Documentation/git-bundle.txt: contained in the union of the given bases. Each b\n +OBJECT PREREQUISITES\n +--------------------\n +\n -+When creating bundles it is possible to create a fully self-contained\n -+bundle with all the prerequisite objects, as well as providing\n -+negative revisions to exclude prerequisite objects.\n ++When creating bundles it is possible to create a self-contained bundle\n ++that can be unbundled in a repository with no common history, as well\n ++as providing negative revisions to exclude objects needed in the\n ++earlier parts of the history.\n +\n -+A revision such as `new` will produce a tip with all the prerequisite\n -+objects needed for the `new` reference.\n ++Feeding a revision such as `new` to `git bundle create` will create a\n ++bundle file that contains all the objects reachable from the revision\n ++`new`. That bundle can be unbundled in any repository to obtain a full\n ++history that leads to the revision `new`:\n ++\n ++----------------\n ++$ git bundle create full.bundle new\n ++----------------\n +\n +A revision range such as `old..new` will produce a bundle tip that'll\n -+require any objects existing before `new` to already be present in the\n -+repository performing the 'git bundle unbundle' operation.\n ++that'll require the revision `old` (and any objects reachable from it)\n ++to exist for the bundle to be \"unbundle\"-able:\n ++\n ++----------------\n ++$ git bundle create full.bundle old..new\n ++----------------\n +\n +A self-contained bundle without any prerequisites can be extracted\n +into anywhere, even into an empty repository, or be cloned from\n3: 6d8f2f27088 = 3: 6d66d4480ff bundle doc: elaborate on rev<->ref restriction\n-- \n2.32.0.874.ge7a9d58bfcf\n\n"},{"id":"430626","messageId":"patch-2.3-a0f95ce3a1d-20210720T141611Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210720T141611Z-avarab@gmail.com","subject":"[PATCH v6 2/3] bundle doc: elaborate on object prerequisites","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-20T14:20:25Z","receivedAt":"2021-07-20T14:27:33Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Split out the discussion bout \"object prerequisites\" into its own\nsection, and add some more examples of the common cases.\n\nSee 2e0afafebd (Add git-bundle: move objects and references by\narchive, 2007-02-22) for the introduction of the documentation being\nchanged here.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 37 +++++++++++++++++++++++++++++++++---\n 1 file changed, 34 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 9c743aed49f..d5627b8cc51 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -45,6 +45,7 @@ header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n \n Like the the packed archive format itself bundles can either be\n self-contained, or be created using exclusions.\n+See the \"OBJECT PREREQUISITES\" section below.\n \n Bundles created using revision exclusions are \"thin packs\" created\n using the `--thin` option to linkgit:git-pack-objects[1], and\n@@ -153,19 +154,49 @@ contained in the union of the given bases. Each basis can be\n specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n `master~10..master`, `--since=10.days.ago master`).\n \n-It is very important that the basis used be held by the destination.\n+OBJECT PREREQUISITES\n+--------------------\n+\n+When creating bundles it is possible to create a self-contained bundle\n+that can be unbundled in a repository with no common history, as well\n+as providing negative revisions to exclude objects needed in the\n+earlier parts of the history.\n+\n+Feeding a revision such as `new` to `git bundle create` will create a\n+bundle file that contains all the objects reachable from the revision\n+`new`. That bundle can be unbundled in any repository to obtain a full\n+history that leads to the revision `new`:\n+\n+----------------\n+$ git bundle create full.bundle new\n+----------------\n+\n+A revision range such as `old..new` will produce a bundle tip that'll\n+that'll require the revision `old` (and any objects reachable from it)\n+to exist for the bundle to be \"unbundle\"-able:\n+\n+----------------\n+$ git bundle create full.bundle old..new\n+----------------\n+\n+A self-contained bundle without any prerequisites can be extracted\n+into anywhere, even into an empty repository, or be cloned from\n+(i.e., `new`, but not `old..new`).\n+\n It is okay to err on the side of caution, causing the bundle file\n to contain objects already in the destination, as these are ignored\n when unpacking at the destination.\n \n-`git clone` can use any bundle created without negative refspecs\n-(e.g., `new`, but not `old..new`).\n If you want to match `git clone --mirror`, which would include your\n refs such as `refs/remotes/*`, use `--all`.\n If you want to provide the same set of refs that a clone directly\n from the source repository would get, use `--branches --tags` for\n the ``.\n \n+The 'git bundle verify' command can be used to check whether your\n+recipient repository has the required prerequisite commits for a\n+bundle.\n+\n EXAMPLES\n --------\n \n-- \n2.32.0.874.ge7a9d58bfcf\n\n"},{"id":"430627","messageId":"patch-3.3-6d66d4480ff-20210720T141611Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210720T141611Z-avarab@gmail.com","subject":"[PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-20T14:20:26Z","receivedAt":"2021-07-20T14:27:47Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Elaborate on the restriction that you cannot provide a revision that\ndoesn't resolve to a reference in the \"SPECIFYING REFERENCES\" section\nwith examples.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------\n 1 file changed, 39 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex d5627b8cc51..e7a685e533e 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -145,14 +145,45 @@ unbundle ::\n SPECIFYING REFERENCES\n ---------------------\n \n-'git bundle' will only package references that are shown by\n-'git show-ref': this includes heads, tags, and remote heads. References\n-such as `master~1` cannot be packaged, but are perfectly suitable for\n-defining the basis. More than one reference may be packaged, and more\n-than one basis can be specified. The objects packaged are those not\n-contained in the union of the given bases. Each basis can be\n-specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n-`master~10..master`, `--since=10.days.ago master`).\n+Revisions must accompanied by reference names to be packaged in a\n+bundle, since the header of the bundle is in a format similar to 'git\n+show-ref'.\n+\n+More than one reference may be packaged, and more than one basis can\n+be specified. The objects packaged are those not contained in the\n+union of the given bases.\n+\n+The 'git bundle create' command resolves the reference names for you\n+using the same rules as `git rev-parse --abbrev-ref=loose`. Each\n+basis can be specified explicitly (e.g. `^master~10`), or implicitly\n+(e.g. `master~10..master`, `--since=10.days.ago master`).\n+\n+All of these simple cases are OK (assuming we have a \"master\" and\n+\"next\" branch):\n+\n+----------------\n+$ git bundle create master.bundle master\n+$ echo master | git bundle create master.bundle --stdin\n+$ git bundle create master-and-next.bundle master next\n+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin\n+----------------\n+\n+And so are these (and the same but omitted `--stdin` examples):\n+\n+----------------\n+$ git bundle create recent-master.bundle master~10..master\n+$ git bundle create recent-updates.bundle master~10..master next~5..next\n+----------------\n+\n+A revision name or a range whose right-hand-side cannot be resolved to\n+a reference is not accepted:\n+\n+----------------\n+$ git bundle create HEAD.bundle $(git rev-parse HEAD)\n+fatal: Refusing to create empty bundle.\n+$ git bundle create master-yesterday.bundle master~10..master~5\n+fatal: Refusing to create empty bundle.\n+----------------\n \n OBJECT PREREQUISITES\n --------------------\n-- \n2.32.0.874.ge7a9d58bfcf\n\n"},{"id":"430628","messageId":"patch-1.3-d5360bb6f74-20210720T141611Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210720T141611Z-avarab@gmail.com","subject":"[PATCH v6 1/3] bundle doc: rewrite the \"DESCRIPTION\" section","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-20T14:20:24Z","receivedAt":"2021-07-20T14:28:01Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Rewrite the \"DESCRIPTION\" section for \"git bundle\" to start by talking\nabout what bundles are in general terms, rather than diving directly\ninto one example of what they might be used for.\n\nThis changes documentation that's been substantially the same ever\nsince the command was added in 2e0afafebd8 (Add git-bundle: move\nobjects and references by archive, 2007-02-22).\n\nI've split up the DESCRIPTION into that section and a \"BUNDLE FORMAT\"\nsection, it briefly discusses the format, but then links to the\ntechnical/bundle-format.txt documentation.\n\nThe \"the user must specify a basis\" part of this is discussed below in\n\"SPECIFYING REFERENCES\", and will be further elaborated on in a\nsubsequent commit. So I'm removing that part and letting the mention\nof \"revision exclusions\" suffice.\n\nThere was a discussion about whether to say anything at all about\n\"thin packs\" here[1]. I think it's good to mention it for the curious\nreader willing to read the technical docs, but let's explicitly say\nthat there's no \"thick pack\", and that the difference shouldn't\nmatter.\n\n1. http://lore.kernel.org/git/xmqqk0mbt5rj.fsf@gitster.g\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 57 ++++++++++++++++++++++++++----------\n 1 file changed, 42 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 53804cad4b6..9c743aed49f 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -18,21 +18,48 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Some workflows require that one or more branches of development on one\n-machine be replicated on another machine, but the two machines cannot\n-be directly connected, and therefore the interactive Git protocols (git,\n-ssh, http) cannot be used.\n-\n-The 'git bundle' command packages objects and references in an archive\n-at the originating machine, which can then be imported into another\n-repository using 'git fetch', 'git pull', or 'git clone',\n-after moving the archive by some means (e.g., by sneakernet).\n-\n-As no\n-direct connection between the repositories exists, the user must specify a\n-basis for the bundle that is held by the destination repository: the\n-bundle assumes that all objects in the basis are already in the\n-destination repository.\n+Create, unpack, and manipulate \"bundle\" files. Bundles are used for\n+the \"offline\" transfer of Git objects without an active \"server\"\n+sitting on the other side of the network connection.\n+\n+They can be used to create both incremental and full backups of a\n+repository, and to relay the state of the references in one repository\n+to another.\n+\n+Git commands that fetch or otherwise \"read\" via protocols such as\n+`ssh://` and `https://` can also operate on bundle files. It is\n+possible linkgit:git-clone[1] a new repository from a bundle, to use\n+linkgit:git-fetch[1] to fetch from one, and to list the references\n+contained within it with linkgit:git-ls-remote[1]. There's no\n+corresponding \"write\" support, i.e.a 'git push' into a bundle is not\n+supported.\n+\n+See the \"EXAMPLES\" section below for examples of how to use bundles.\n+\n+BUNDLE FORMAT\n+-------------\n+\n+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a\n+header indicating what references are contained within the bundle. The\n+header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n+\n+Like the the packed archive format itself bundles can either be\n+self-contained, or be created using exclusions.\n+\n+Bundles created using revision exclusions are \"thin packs\" created\n+using the `--thin` option to linkgit:git-pack-objects[1], and\n+unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].\n+\n+There is no option to create a \"thick pack\" when using revision\n+exclusions, users should not be concerned about the difference. By\n+using \"thin packs\" bundles created using exclusions are smaller in\n+size. That they're \"thin\" under the hood is merely noted here as a\n+curiosity, and as a reference to other documentation\n+\n+See link:technical/bundle-format.html[the `bundle-format`\n+documentation] for more details and the discussion of \"thin pack\" in\n+link:technical/pack-format.html[the pack format documentation] for\n+further details.\n \n OPTIONS\n -------\n-- \n2.32.0.874.ge7a9d58bfcf\n\n"},{"id":"430683","messageId":"xmqqsg08hhs0.fsf@gitster.g","threadId":"55869","inReplyTo":"patch-2.3-a0f95ce3a1d-20210720T141611Z-avarab@gmail.com","subject":"Re: [PATCH v6 2/3] bundle doc: elaborate on object prerequisites","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-07-20T20:06:23Z","receivedAt":"2021-07-20T20:08:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> +A revision range such as `old..new` will produce a bundle tip that'll\n> +that'll require the revision `old` (and any objects reachable from it)\n> +to exist for the bundle to be \"unbundle\"-able:\n\nWill squash in the following while queuing.\n\nThanks.\n\ndiff --git c/Documentation/git-bundle.txt w/Documentation/git-bundle.txt\nindex e7a685e533..6a45ced017 100644\n--- c/Documentation/git-bundle.txt\n+++ w/Documentation/git-bundle.txt\n@@ -202,8 +202,8 @@ history that leads to the revision `new`:\n $ git bundle create full.bundle new\n ----------------\n \n-A revision range such as `old..new` will produce a bundle tip that'll\n-that'll require the revision `old` (and any objects reachable from it)\n+A revision range such as `old..new` will produce a bundle file that\n+will require the revision `old` (and any objects reachable from it)\n to exist for the bundle to be \"unbundle\"-able:\n \n ----------------\n"},{"id":"430693","messageId":"xmqqo8awhh5z.fsf@gitster.g","threadId":"55869","inReplyTo":"patch-3.3-6d66d4480ff-20210720T141611Z-avarab@gmail.com","subject":"Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-07-20T20:19:36Z","receivedAt":"2021-07-20T20:43:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> +Revisions must accompanied by reference names to be packaged in a\n> +bundle, since the header of the bundle is in a format similar to 'git\n> +show-ref'.\n\nThis may be an improvement in the way how the description refers to\n\"show-ref\", but we do not have to say anything about \"show-ref\" ;-)\n\nThe reason we should give readers why they must give refs while\ncreating a bundle, I think, is because the only way to access the\ncontents of the bundle is to fetch refs from it, and the refs given\nto the command when the bundle was created becomes the refs that can\nbe fetched from the bundle.\n\nThanks.\n\n"},{"id":"430746","messageId":"68ea4cc0-b9d3-a7fb-7c22-fa828f9dc52f@iee.email","threadId":"55869","inReplyTo":"xmqqo8awhh5z.fsf@gitster.g","subject":"Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2021-07-21T09:27:40Z","receivedAt":"2021-07-21T09:35:28Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 20/07/2021 21:19, Junio C Hamano wrote:\n> Ævar Arnfjörð Bjarmason writes:\n>\n>> +Revisions must accompanied by reference names to be packaged in a\n>> +bundle, since the header of the bundle is in a format similar to 'git\n>> +show-ref'.\n> This may be an improvement in the way how the description refers to\n> \"show-ref\", but we do not have to say anything about \"show-ref\" ;-)\n>\n> The reason we should give readers why they must give refs while\n> creating a bundle, I think, is because the only way to access the\n> contents of the bundle is to fetch refs from it, and the refs given\n> to the command when the bundle was created becomes the refs that can\n> be fetched from the bundle.\n>\n> Thanks.\n>\nShould the `list-heads` option be mentioned for investigating existing\nbundles?\n--\nPhilip\n"},{"id":"430776","messageId":"xmqqim13eh9z.fsf@gitster.g","threadId":"55869","inReplyTo":"68ea4cc0-b9d3-a7fb-7c22-fa828f9dc52f@iee.email","subject":"Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-07-21T16:57:44Z","receivedAt":"2021-07-21T16:57:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> Should the `list-heads` option be mentioned for investigating existing\n> bundles?\n\nI think 'list-heads' has been listed in the options section. I\nhowever may encourage people to use \"git ls-remote one.bndl\" over\n\"git bundle list-heads one.bndl\"---they do the same thing, no?\n\nThanks.\n\n\n\n"},{"id":"430907","messageId":"27ad38c9-699e-0a9b-1bef-3c5d2950cd02@iee.email","threadId":"55869","inReplyTo":"xmqqim13eh9z.fsf@gitster.g","subject":"Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2021-07-22T11:37:27Z","receivedAt":"2021-07-22T11:37:31Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 21/07/2021 17:57, Junio C Hamano wrote:\n> Philip Oakley writes:\n>\n>> Should the `list-heads` option be mentioned for investigating existing\n>> bundles?\n> I think 'list-heads' has been listed in the options section. \n\nTrue, it's why I was suggesting pointing at that route for the extra\ndetails that are beyond just a set of refs.\n\n> I\n> however may encourage people to use \"git ls-remote one.bndl\" over\n> \"git bundle list-heads one.bndl\"---they do the same thing, no?\n\nIt is good to provide both directions to the user. The formats may be\ndifferent but the content is essentially the same, and redirecting users\nto the more core command is useful.\n\n>\n> Thanks.\n>\n>\n>\n\n"},{"id":"430909","messageId":"87v952tvrz.fsf@evledraar.gmail.com","threadId":"55869","inReplyTo":"27ad38c9-699e-0a9b-1bef-3c5d2950cd02@iee.email","subject":"Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-22T11:46:58Z","receivedAt":"2021-07-22T11:47:29Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Thu, Jul 22 2021, Philip Oakley wrote:\n\n> On 21/07/2021 17:57, Junio C Hamano wrote:\n>> Philip Oakley writes:\n>>\n>>> Should the `list-heads` option be mentioned for investigating existing\n>>> bundles?\n>> I think 'list-heads' has been listed in the options section. \n>\n> True, it's why I was suggesting pointing at that route for the extra\n> details that are beyond just a set of refs.\n>\n>> I\n>> however may encourage people to use \"git ls-remote one.bndl\" over\n>> \"git bundle list-heads one.bndl\"---they do the same thing, no?\n>\n> It is good to provide both directions to the user. The formats may be\n> different but the content is essentially the same, and redirecting users\n> to the more core command is useful.\n>\n\nI'll work those suggestions into a future update of the docs I have\nqueued, but for now I think talking about list-heads v.s. ls-remote\ndoesn't have much directly to do with this particular series, correct?\n"},{"id":"430977","messageId":"697ca0f3-a897-a20b-48e4-bf439697afb5@iee.email","threadId":"55869","inReplyTo":"87v952tvrz.fsf@evledraar.gmail.com","subject":"Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2021-07-22T23:14:46Z","receivedAt":"2021-07-22T23:14:50Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 22/07/2021 12:46, Ævar Arnfjörð Bjarmason wrote:\n> On Thu, Jul 22 2021, Philip Oakley wrote:\n>\n>> On 21/07/2021 17:57, Junio C Hamano wrote:\n>>> Philip Oakley writes:\n>>>\n>>>> Should the `list-heads` option be mentioned for investigating existing\n>>>> bundles?\n>>> I think 'list-heads' has been listed in the options section. \n>> True, it's why I was suggesting pointing at that route for the extra\n>> details that are beyond just a set of refs.\n>>\n>>> I\n>>> however may encourage people to use \"git ls-remote one.bndl\" over\n>>> \"git bundle list-heads one.bndl\"---they do the same thing, no?\n>> It is good to provide both directions to the user. The formats may be\n>> different but the content is essentially the same, and redirecting users\n>> to the more core command is useful.\n>>\n> I'll work those suggestions into a future update of the docs I have\n> queued, but for now I think talking about list-heads v.s. ls-remote\n> doesn't have much directly to do with this particular series, correct?\nTrue.\n\nHowever I'm still not really clear about the distinction between the\n'basis' and the `header references` (that is, the text doesn't make it\nclear).\n\nfor the future updates, it would also be good if the `--all` and\n`--branches --tags` text was also shown in the examples - I continue to\nget StackOverflow points for my Q&A on that ;-)\n\nPhilip\n"},{"id":"431266","messageId":"cover-0.3-0000000000-20210727T002001Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-00000000000-20210702T112254Z-avarab@gmail.com","subject":"[PATCH v7 0/3] bundle doc: generalize & elaborate","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-27T00:24:18Z","receivedAt":"2021-07-27T00:24:29Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"This v7 hopefully addresses the outstanding comments on v6.\n\nThe mention of \"show-ref\" is gone (more confusing than not), and this\nincludes Junio's queued squash.\n\nI left the further clarification of \"basis\" and \"header references\"\nmentioned in [1] be. I think the former refers to the \"basis can be\nspecified\" wording in 3/3, which isn't new, but in that regard mostly\nmoves existing documentation around.\n\nThis documentation can definitely be improved further, but given that\nthis is in v7 and we're changing smaller and smaller things I'd like\nto not add anything new to it for now, and hopefully get it merged\ndown & then build on top of it for any further changes.\n\n1. https://lore.kernel.org/git/697ca0f3-a897-a20b-48e4-bf439697afb5@iee.email/\n\nÆvar Arnfjörð Bjarmason (3):\n bundle doc: rewrite the \"DESCRIPTION\" section\n bundle doc: elaborate on object prerequisites\n bundle doc: elaborate on rev<->ref restriction\n\n Documentation/git-bundle.txt | 140 ++++++++++++++++++++++++++++-------\n 1 file changed, 114 insertions(+), 26 deletions(-)\n\nRange-diff against v6:\n1: 3b447500da ! 1: b8f8a20e78 bundle doc: rewrite the \"DESCRIPTION\" section\n @@ Documentation/git-bundle.txt: SYNOPSIS\n +-------------\n +\n +Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a\n -+header indicating what references are contained within the bundle. The\n -+header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n ++header indicating what references are contained within the bundle.\n +\n +Like the the packed archive format itself bundles can either be\n +self-contained, or be created using exclusions.\n2: 444b06740b ! 2: 5f344bd24a bundle doc: elaborate on object prerequisites\n @@ Commit message\n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/git-bundle.txt ##\n -@@ Documentation/git-bundle.txt: header is (mostly) in the format emitted by linkgit:git-show-ref[1].\n +@@ Documentation/git-bundle.txt: header indicating what references are contained within the bundle.\n \n Like the the packed archive format itself bundles can either be\n self-contained, or be created using exclusions.\n @@ Documentation/git-bundle.txt: contained in the union of the given bases. Each b\n +OBJECT PREREQUISITES\n +--------------------\n +\n -+When creating bundles it is possible to create a fully self-contained\n -+bundle with all the prerequisite objects, as well as providing\n -+negative revisions to exclude prerequisite objects.\n ++When creating bundles it is possible to create a self-contained bundle\n ++that can be unbundled in a repository with no common history, as well\n ++as providing negative revisions to exclude objects needed in the\n ++earlier parts of the history.\n +\n -+A revision such as `new` will produce a tip with all the prerequisite\n -+objects needed for the `new` reference.\n ++Feeding a revision such as `new` to `git bundle create` will create a\n ++bundle file that contains all the objects reachable from the revision\n ++`new`. That bundle can be unbundled in any repository to obtain a full\n ++history that leads to the revision `new`:\n +\n -+A revision range such as `old..new` will produce a bundle tip that'll\n -+require any objects existing before `new` to already be present in the\n -+repository performing the 'git bundle unbundle' operation.\n ++----------------\n ++$ git bundle create full.bundle new\n ++----------------\n ++\n ++A revision range such as `old..new` will produce a bundle file that\n ++will require the revision `old` (and any objects reachable from it)\n ++to exist for the bundle to be \"unbundle\"-able:\n ++\n ++----------------\n ++$ git bundle create full.bundle old..new\n ++----------------\n +\n +A self-contained bundle without any prerequisites can be extracted\n +into anywhere, even into an empty repository, or be cloned from\n3: 6d8f2f2708 = 3: 88e7ad1cf4 bundle doc: elaborate on rev<->ref restriction\n-- \n2.32.0.988.g1a6a4b2c5f\n\n"},{"id":"431267","messageId":"patch-1.3-b8f8a20e78-20210727T002001Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-0000000000-20210727T002001Z-avarab@gmail.com","subject":"[PATCH v7 1/3] bundle doc: rewrite the \"DESCRIPTION\" section","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-27T00:24:19Z","receivedAt":"2021-07-27T00:24:32Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Rewrite the \"DESCRIPTION\" section for \"git bundle\" to start by talking\nabout what bundles are in general terms, rather than diving directly\ninto one example of what they might be used for.\n\nThis changes documentation that's been substantially the same ever\nsince the command was added in 2e0afafebd8 (Add git-bundle: move\nobjects and references by archive, 2007-02-22).\n\nI've split up the DESCRIPTION into that section and a \"BUNDLE FORMAT\"\nsection, it briefly discusses the format, but then links to the\ntechnical/bundle-format.txt documentation.\n\nThe \"the user must specify a basis\" part of this is discussed below in\n\"SPECIFYING REFERENCES\", and will be further elaborated on in a\nsubsequent commit. So I'm removing that part and letting the mention\nof \"revision exclusions\" suffice.\n\nThere was a discussion about whether to say anything at all about\n\"thin packs\" here[1]. I think it's good to mention it for the curious\nreader willing to read the technical docs, but let's explicitly say\nthat there's no \"thick pack\", and that the difference shouldn't\nmatter.\n\n1. http://lore.kernel.org/git/xmqqk0mbt5rj.fsf@gitster.g\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 56 ++++++++++++++++++++++++++----------\n 1 file changed, 41 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 53804cad4b..339c5b4727 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -18,21 +18,47 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Some workflows require that one or more branches of development on one\n-machine be replicated on another machine, but the two machines cannot\n-be directly connected, and therefore the interactive Git protocols (git,\n-ssh, http) cannot be used.\n-\n-The 'git bundle' command packages objects and references in an archive\n-at the originating machine, which can then be imported into another\n-repository using 'git fetch', 'git pull', or 'git clone',\n-after moving the archive by some means (e.g., by sneakernet).\n-\n-As no\n-direct connection between the repositories exists, the user must specify a\n-basis for the bundle that is held by the destination repository: the\n-bundle assumes that all objects in the basis are already in the\n-destination repository.\n+Create, unpack, and manipulate \"bundle\" files. Bundles are used for\n+the \"offline\" transfer of Git objects without an active \"server\"\n+sitting on the other side of the network connection.\n+\n+They can be used to create both incremental and full backups of a\n+repository, and to relay the state of the references in one repository\n+to another.\n+\n+Git commands that fetch or otherwise \"read\" via protocols such as\n+`ssh://` and `https://` can also operate on bundle files. It is\n+possible linkgit:git-clone[1] a new repository from a bundle, to use\n+linkgit:git-fetch[1] to fetch from one, and to list the references\n+contained within it with linkgit:git-ls-remote[1]. There's no\n+corresponding \"write\" support, i.e.a 'git push' into a bundle is not\n+supported.\n+\n+See the \"EXAMPLES\" section below for examples of how to use bundles.\n+\n+BUNDLE FORMAT\n+-------------\n+\n+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a\n+header indicating what references are contained within the bundle.\n+\n+Like the the packed archive format itself bundles can either be\n+self-contained, or be created using exclusions.\n+\n+Bundles created using revision exclusions are \"thin packs\" created\n+using the `--thin` option to linkgit:git-pack-objects[1], and\n+unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].\n+\n+There is no option to create a \"thick pack\" when using revision\n+exclusions, users should not be concerned about the difference. By\n+using \"thin packs\" bundles created using exclusions are smaller in\n+size. That they're \"thin\" under the hood is merely noted here as a\n+curiosity, and as a reference to other documentation\n+\n+See link:technical/bundle-format.html[the `bundle-format`\n+documentation] for more details and the discussion of \"thin pack\" in\n+link:technical/pack-format.html[the pack format documentation] for\n+further details.\n \n OPTIONS\n -------\n-- \n2.32.0.988.g1a6a4b2c5f\n\n"},{"id":"431268","messageId":"patch-2.3-5f344bd24a-20210727T002001Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-0000000000-20210727T002001Z-avarab@gmail.com","subject":"[PATCH v7 2/3] bundle doc: elaborate on object prerequisites","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-27T00:24:20Z","receivedAt":"2021-07-27T00:24:33Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Split out the discussion bout \"object prerequisites\" into its own\nsection, and add some more examples of the common cases.\n\nSee 2e0afafebd (Add git-bundle: move objects and references by\narchive, 2007-02-22) for the introduction of the documentation being\nchanged here.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 37 +++++++++++++++++++++++++++++++++---\n 1 file changed, 34 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 339c5b4727..f1f84ce2c4 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -44,6 +44,7 @@ header indicating what references are contained within the bundle.\n \n Like the the packed archive format itself bundles can either be\n self-contained, or be created using exclusions.\n+See the \"OBJECT PREREQUISITES\" section below.\n \n Bundles created using revision exclusions are \"thin packs\" created\n using the `--thin` option to linkgit:git-pack-objects[1], and\n@@ -152,19 +153,49 @@ contained in the union of the given bases. Each basis can be\n specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n `master~10..master`, `--since=10.days.ago master`).\n \n-It is very important that the basis used be held by the destination.\n+OBJECT PREREQUISITES\n+--------------------\n+\n+When creating bundles it is possible to create a self-contained bundle\n+that can be unbundled in a repository with no common history, as well\n+as providing negative revisions to exclude objects needed in the\n+earlier parts of the history.\n+\n+Feeding a revision such as `new` to `git bundle create` will create a\n+bundle file that contains all the objects reachable from the revision\n+`new`. That bundle can be unbundled in any repository to obtain a full\n+history that leads to the revision `new`:\n+\n+----------------\n+$ git bundle create full.bundle new\n+----------------\n+\n+A revision range such as `old..new` will produce a bundle file that\n+will require the revision `old` (and any objects reachable from it)\n+to exist for the bundle to be \"unbundle\"-able:\n+\n+----------------\n+$ git bundle create full.bundle old..new\n+----------------\n+\n+A self-contained bundle without any prerequisites can be extracted\n+into anywhere, even into an empty repository, or be cloned from\n+(i.e., `new`, but not `old..new`).\n+\n It is okay to err on the side of caution, causing the bundle file\n to contain objects already in the destination, as these are ignored\n when unpacking at the destination.\n \n-`git clone` can use any bundle created without negative refspecs\n-(e.g., `new`, but not `old..new`).\n If you want to match `git clone --mirror`, which would include your\n refs such as `refs/remotes/*`, use `--all`.\n If you want to provide the same set of refs that a clone directly\n from the source repository would get, use `--branches --tags` for\n the ``.\n \n+The 'git bundle verify' command can be used to check whether your\n+recipient repository has the required prerequisite commits for a\n+bundle.\n+\n EXAMPLES\n --------\n \n-- \n2.32.0.988.g1a6a4b2c5f\n\n"},{"id":"431269","messageId":"patch-3.3-88e7ad1cf4-20210727T002001Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-0000000000-20210727T002001Z-avarab@gmail.com","subject":"[PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-27T00:24:21Z","receivedAt":"2021-07-27T00:24:34Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Elaborate on the restriction that you cannot provide a revision that\ndoesn't resolve to a reference in the \"SPECIFYING REFERENCES\" section\nwith examples.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------\n 1 file changed, 39 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex f1f84ce2c4..0f28c41409 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -144,14 +144,45 @@ unbundle ::\n SPECIFYING REFERENCES\n ---------------------\n \n-'git bundle' will only package references that are shown by\n-'git show-ref': this includes heads, tags, and remote heads. References\n-such as `master~1` cannot be packaged, but are perfectly suitable for\n-defining the basis. More than one reference may be packaged, and more\n-than one basis can be specified. The objects packaged are those not\n-contained in the union of the given bases. Each basis can be\n-specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n-`master~10..master`, `--since=10.days.ago master`).\n+Revisions must accompanied by reference names to be packaged in a\n+bundle, since the header of the bundle is in a format similar to 'git\n+show-ref'.\n+\n+More than one reference may be packaged, and more than one basis can\n+be specified. The objects packaged are those not contained in the\n+union of the given bases.\n+\n+The 'git bundle create' command resolves the reference names for you\n+using the same rules as `git rev-parse --abbrev-ref=loose`. Each\n+basis can be specified explicitly (e.g. `^master~10`), or implicitly\n+(e.g. `master~10..master`, `--since=10.days.ago master`).\n+\n+All of these simple cases are OK (assuming we have a \"master\" and\n+\"next\" branch):\n+\n+----------------\n+$ git bundle create master.bundle master\n+$ echo master | git bundle create master.bundle --stdin\n+$ git bundle create master-and-next.bundle master next\n+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin\n+----------------\n+\n+And so are these (and the same but omitted `--stdin` examples):\n+\n+----------------\n+$ git bundle create recent-master.bundle master~10..master\n+$ git bundle create recent-updates.bundle master~10..master next~5..next\n+----------------\n+\n+A revision name or a range whose right-hand-side cannot be resolved to\n+a reference is not accepted:\n+\n+----------------\n+$ git bundle create HEAD.bundle $(git rev-parse HEAD)\n+fatal: Refusing to create empty bundle.\n+$ git bundle create master-yesterday.bundle master~10..master~5\n+fatal: Refusing to create empty bundle.\n+----------------\n \n OBJECT PREREQUISITES\n --------------------\n-- \n2.32.0.988.g1a6a4b2c5f\n\n"},{"id":"431399","messageId":"42d4fb18-f9ee-006d-b20a-af8708096fd8@iee.email","threadId":"55869","inReplyTo":"patch-3.3-88e7ad1cf4-20210727T002001Z-avarab@gmail.com","subject":"Re: [PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2021-07-28T15:17:33Z","receivedAt":"2021-07-28T15:17:47Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 27/07/2021 01:24, Ævar Arnfjörð Bjarmason wrote:\n> Elaborate on the restriction that you cannot provide a revision that\n> doesn't resolve to a reference in the \"SPECIFYING REFERENCES\" section\n> with examples.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------\n> 1 file changed, 39 insertions(+), 8 deletions(-)\n>\n> diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\n> index f1f84ce2c4..0f28c41409 100644\n> --- a/Documentation/git-bundle.txt\n> +++ b/Documentation/git-bundle.txt\n> @@ -144,14 +144,45 @@ unbundle ::\n> SPECIFYING REFERENCES\n> ---------------------\n> \n> -'git bundle' will only package references that are shown by\n> -'git show-ref': this includes heads, tags, and remote heads. References\n> -such as `master~1` cannot be packaged, but are perfectly suitable for\n> -defining the basis. More than one reference may be packaged, and more\n> -than one basis can be specified. The objects packaged are those not\n> -contained in the union of the given bases. Each basis can be\n> -specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n> -`master~10..master`, `--since=10.days.ago master`).\n> +Revisions must accompanied by reference names to be packaged in a\n> +bundle, since the header of the bundle is in a format similar to 'git\n> +show-ref'.\n> +\n> +More than one reference may be packaged, and more than one basis can\n> +be specified. The objects packaged are those not contained in the\n> +union of the given bases.\n> +\n> +The 'git bundle create' command resolves the reference names for you\n> +using the same rules as `git rev-parse --abbrev-ref=loose`. Each\n> +basis can be specified explicitly (e.g. `^master~10`), or implicitly\n> +(e.g. `master~10..master`, `--since=10.days.ago master`).\n> +\n> +All of these simple cases are OK (assuming we have a \"master\" and\n> +\"next\" branch):\n> +\n> +----------------\n> +$ git bundle create master.bundle master\n> +$ echo master | git bundle create master.bundle --stdin\n> +$ git bundle create master-and-next.bundle master next\n> +$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin\n> +----------------\n> +\n> +And so are these (and the same but omitted `--stdin` examples):\n> +\n> +----------------\n> +$ git bundle create recent-master.bundle master~10..master\n> +$ git bundle create recent-updates.bundle master~10..master next~5..next\n> +----------------\n> +\n> +A revision name or a range whose right-hand-side cannot be resolved to\n> +a reference is not accepted:\n> +\n> +----------------\n> +$ git bundle create HEAD.bundle $(git rev-parse HEAD)\n> +fatal: Refusing to create empty bundle.\n> +$ git bundle create master-yesterday.bundle master~10..master~5\n> +fatal: Refusing to create empty bundle.\n\nI like this example showing the need for a reference name to be part of\nthe basis, clarifying that part of the description.\n\nPhilip\n\n> +----------------\n> \n> OBJECT PREREQUISITES\n> --------------------\n\n"},{"id":"431414","messageId":"xmqqa6m69uvh.fsf@gitster.g","threadId":"55869","inReplyTo":"patch-3.3-88e7ad1cf4-20210727T002001Z-avarab@gmail.com","subject":"Re: [PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-07-28T18:05:38Z","receivedAt":"2021-07-28T18:05:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> +Revisions must accompanied by reference names to be packaged in a\n> +bundle, since the header of the bundle is in a format similar to 'git\n> +show-ref'.\n\nAs I already said in the review of v6, I do not think \"header has a\nformat similar to show-ref\" is not something we need to say so\nprominently to the user.\n\n\nThe reason we should give readers why they must give refs while\ncreating a bundle, I think, is because the only way to access the\ncontents of the bundle is to fetch refs from it, and the refs given\nto the command when the bundle was created becomes the refs that can\nbe fetched from the bundle.\n\nAnd that is what the readers should be told here, I think.\n\n\n> +More than one reference may be packaged, and more than one basis can\n> +be specified. The objects packaged are those not contained in the\n> +union of the given bases.\n> +\n> +The 'git bundle create' command resolves the reference names for you\n> +using the same rules as `git rev-parse --abbrev-ref=loose`. Each\n> +basis can be specified explicitly (e.g. `^master~10`), or implicitly\n> +(e.g. `master~10..master`, `--since=10.days.ago master`).\n\nAlso, we introduced \"prerequisite objects\" in the previous step, but\nhere we say \"basis\". The readers would be helped greatly if we were\na bit more consistent.\n\n> ...\n> +A revision name or a range whose right-hand-side cannot be resolved to\n> +a reference is not accepted:\n> +\n> +----------------\n> +$ git bundle create HEAD.bundle $(git rev-parse HEAD)\n> +fatal: Refusing to create empty bundle.\n> +$ git bundle create master-yesterday.bundle master~10..master~5\n> +fatal: Refusing to create empty bundle.\n> +----------------\n\nThis is a good example, as Philip already said.\n\nThanks.\n"},{"id":"431621","messageId":"cover-v8-0.4-00000000000-20210731T082120Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-0.3-0000000000-20210727T002001Z-avarab@gmail.com","subject":"[PATCH v8 0/3] bundle doc: generalize & elaborate","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-31T08:23:03Z","receivedAt":"2021-07-31T08:23:16Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"As mentioned in v7 I got rid of the comparisons of the bundle header\nto the format of show-ref:\nhttps://lore.kernel.org/git/cover-0.3-0000000000-20210727T002001Z-avarab@gmail.com\n\nExcept I managed to miss that it was in two places in the series,\nsorry. Here's an update with what I meant to send in v7.\n\nJunio also mentioned it being confusing that we mix \"basis\" and\n\"object prerequisites\", I agree, but wanted to keep these changes\nminimal, so I wasn't rewording the existing occurances of \"basis\".\n\nThis now has a minimal patch-on-top which follows up and rewords those\nexisting and moved-around occurrences of \"basis\" to \"[commit|object]\nprerequisite(s)\".\n\n1. https://lore.kernel.org/git/xmqqa6m69uvh.fsf@gitster.g/#t\n\nÆvar Arnfjörð Bjarmason (4):\n bundle doc: rewrite the \"DESCRIPTION\" section\n bundle doc: elaborate on object prerequisites\n bundle doc: elaborate on rev<->ref restriction\n bundle doc: replace \"basis\" with \"prerequsite(s)\"\n\n Documentation/git-bundle.txt | 147 ++++++++++++++++++++++++++++-------\n 1 file changed, 117 insertions(+), 30 deletions(-)\n\nRange-diff against v7:\n1: b8f8a20e789 = 1: b8f8a20e789 bundle doc: rewrite the \"DESCRIPTION\" section\n2: 5f344bd24aa = 2: 5f344bd24aa bundle doc: elaborate on object prerequisites\n3: 88e7ad1cf49 ! 3: 0e702337c7f bundle doc: elaborate on rev<->ref restriction\n @@ Documentation/git-bundle.txt: unbundle ::\n -specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n -`master~10..master`, `--since=10.days.ago master`).\n +Revisions must accompanied by reference names to be packaged in a\n -+bundle, since the header of the bundle is in a format similar to 'git\n -+show-ref'.\n ++bundle.\n +\n +More than one reference may be packaged, and more than one basis can\n +be specified. The objects packaged are those not contained in the\n-: ----------- > 4: 1f3dcd42863 bundle doc: replace \"basis\" with \"prerequsite(s)\"\n-- \n2.32.0.1069.g545f0888808\n\n"},{"id":"431622","messageId":"patch-v8-1.4-b8f8a20e789-20210731T082120Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-v8-0.4-00000000000-20210731T082120Z-avarab@gmail.com","subject":"[PATCH v8 1/4] bundle doc: rewrite the \"DESCRIPTION\" section","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-31T08:23:04Z","receivedAt":"2021-07-31T08:23:16Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Rewrite the \"DESCRIPTION\" section for \"git bundle\" to start by talking\nabout what bundles are in general terms, rather than diving directly\ninto one example of what they might be used for.\n\nThis changes documentation that's been substantially the same ever\nsince the command was added in 2e0afafebd8 (Add git-bundle: move\nobjects and references by archive, 2007-02-22).\n\nI've split up the DESCRIPTION into that section and a \"BUNDLE FORMAT\"\nsection, it briefly discusses the format, but then links to the\ntechnical/bundle-format.txt documentation.\n\nThe \"the user must specify a basis\" part of this is discussed below in\n\"SPECIFYING REFERENCES\", and will be further elaborated on in a\nsubsequent commit. So I'm removing that part and letting the mention\nof \"revision exclusions\" suffice.\n\nThere was a discussion about whether to say anything at all about\n\"thin packs\" here[1]. I think it's good to mention it for the curious\nreader willing to read the technical docs, but let's explicitly say\nthat there's no \"thick pack\", and that the difference shouldn't\nmatter.\n\n1. http://lore.kernel.org/git/xmqqk0mbt5rj.fsf@gitster.g\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 56 ++++++++++++++++++++++++++----------\n 1 file changed, 41 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 53804cad4b6..339c5b47276 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -18,21 +18,47 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Some workflows require that one or more branches of development on one\n-machine be replicated on another machine, but the two machines cannot\n-be directly connected, and therefore the interactive Git protocols (git,\n-ssh, http) cannot be used.\n-\n-The 'git bundle' command packages objects and references in an archive\n-at the originating machine, which can then be imported into another\n-repository using 'git fetch', 'git pull', or 'git clone',\n-after moving the archive by some means (e.g., by sneakernet).\n-\n-As no\n-direct connection between the repositories exists, the user must specify a\n-basis for the bundle that is held by the destination repository: the\n-bundle assumes that all objects in the basis are already in the\n-destination repository.\n+Create, unpack, and manipulate \"bundle\" files. Bundles are used for\n+the \"offline\" transfer of Git objects without an active \"server\"\n+sitting on the other side of the network connection.\n+\n+They can be used to create both incremental and full backups of a\n+repository, and to relay the state of the references in one repository\n+to another.\n+\n+Git commands that fetch or otherwise \"read\" via protocols such as\n+`ssh://` and `https://` can also operate on bundle files. It is\n+possible linkgit:git-clone[1] a new repository from a bundle, to use\n+linkgit:git-fetch[1] to fetch from one, and to list the references\n+contained within it with linkgit:git-ls-remote[1]. There's no\n+corresponding \"write\" support, i.e.a 'git push' into a bundle is not\n+supported.\n+\n+See the \"EXAMPLES\" section below for examples of how to use bundles.\n+\n+BUNDLE FORMAT\n+-------------\n+\n+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a\n+header indicating what references are contained within the bundle.\n+\n+Like the the packed archive format itself bundles can either be\n+self-contained, or be created using exclusions.\n+\n+Bundles created using revision exclusions are \"thin packs\" created\n+using the `--thin` option to linkgit:git-pack-objects[1], and\n+unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].\n+\n+There is no option to create a \"thick pack\" when using revision\n+exclusions, users should not be concerned about the difference. By\n+using \"thin packs\" bundles created using exclusions are smaller in\n+size. That they're \"thin\" under the hood is merely noted here as a\n+curiosity, and as a reference to other documentation\n+\n+See link:technical/bundle-format.html[the `bundle-format`\n+documentation] for more details and the discussion of \"thin pack\" in\n+link:technical/pack-format.html[the pack format documentation] for\n+further details.\n \n OPTIONS\n -------\n-- \n2.32.0.1069.g545f0888808\n\n"},{"id":"431623","messageId":"patch-v8-2.4-5f344bd24aa-20210731T082120Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-v8-0.4-00000000000-20210731T082120Z-avarab@gmail.com","subject":"[PATCH v8 2/4] bundle doc: elaborate on object prerequisites","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-31T08:23:05Z","receivedAt":"2021-07-31T08:23:22Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Split out the discussion bout \"object prerequisites\" into its own\nsection, and add some more examples of the common cases.\n\nSee 2e0afafebd (Add git-bundle: move objects and references by\narchive, 2007-02-22) for the introduction of the documentation being\nchanged here.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 37 +++++++++++++++++++++++++++++++++---\n 1 file changed, 34 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 339c5b47276..f1f84ce2c42 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -44,6 +44,7 @@ header indicating what references are contained within the bundle.\n \n Like the the packed archive format itself bundles can either be\n self-contained, or be created using exclusions.\n+See the \"OBJECT PREREQUISITES\" section below.\n \n Bundles created using revision exclusions are \"thin packs\" created\n using the `--thin` option to linkgit:git-pack-objects[1], and\n@@ -152,19 +153,49 @@ contained in the union of the given bases. Each basis can be\n specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n `master~10..master`, `--since=10.days.ago master`).\n \n-It is very important that the basis used be held by the destination.\n+OBJECT PREREQUISITES\n+--------------------\n+\n+When creating bundles it is possible to create a self-contained bundle\n+that can be unbundled in a repository with no common history, as well\n+as providing negative revisions to exclude objects needed in the\n+earlier parts of the history.\n+\n+Feeding a revision such as `new` to `git bundle create` will create a\n+bundle file that contains all the objects reachable from the revision\n+`new`. That bundle can be unbundled in any repository to obtain a full\n+history that leads to the revision `new`:\n+\n+----------------\n+$ git bundle create full.bundle new\n+----------------\n+\n+A revision range such as `old..new` will produce a bundle file that\n+will require the revision `old` (and any objects reachable from it)\n+to exist for the bundle to be \"unbundle\"-able:\n+\n+----------------\n+$ git bundle create full.bundle old..new\n+----------------\n+\n+A self-contained bundle without any prerequisites can be extracted\n+into anywhere, even into an empty repository, or be cloned from\n+(i.e., `new`, but not `old..new`).\n+\n It is okay to err on the side of caution, causing the bundle file\n to contain objects already in the destination, as these are ignored\n when unpacking at the destination.\n \n-`git clone` can use any bundle created without negative refspecs\n-(e.g., `new`, but not `old..new`).\n If you want to match `git clone --mirror`, which would include your\n refs such as `refs/remotes/*`, use `--all`.\n If you want to provide the same set of refs that a clone directly\n from the source repository would get, use `--branches --tags` for\n the ``.\n \n+The 'git bundle verify' command can be used to check whether your\n+recipient repository has the required prerequisite commits for a\n+bundle.\n+\n EXAMPLES\n --------\n \n-- \n2.32.0.1069.g545f0888808\n\n"},{"id":"431624","messageId":"patch-v8-3.4-0e702337c7f-20210731T082120Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-v8-0.4-00000000000-20210731T082120Z-avarab@gmail.com","subject":"[PATCH v8 3/4] bundle doc: elaborate on rev<->ref restriction","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-31T08:23:06Z","receivedAt":"2021-07-31T08:23:23Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Elaborate on the restriction that you cannot provide a revision that\ndoesn't resolve to a reference in the \"SPECIFYING REFERENCES\" section\nwith examples.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 46 +++++++++++++++++++++++++++++-------\n 1 file changed, 38 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex f1f84ce2c42..f36939ab014 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -144,14 +144,44 @@ unbundle ::\n SPECIFYING REFERENCES\n ---------------------\n \n-'git bundle' will only package references that are shown by\n-'git show-ref': this includes heads, tags, and remote heads. References\n-such as `master~1` cannot be packaged, but are perfectly suitable for\n-defining the basis. More than one reference may be packaged, and more\n-than one basis can be specified. The objects packaged are those not\n-contained in the union of the given bases. Each basis can be\n-specified explicitly (e.g. `^master~10`), or implicitly (e.g.\n-`master~10..master`, `--since=10.days.ago master`).\n+Revisions must accompanied by reference names to be packaged in a\n+bundle.\n+\n+More than one reference may be packaged, and more than one basis can\n+be specified. The objects packaged are those not contained in the\n+union of the given bases.\n+\n+The 'git bundle create' command resolves the reference names for you\n+using the same rules as `git rev-parse --abbrev-ref=loose`. Each\n+basis can be specified explicitly (e.g. `^master~10`), or implicitly\n+(e.g. `master~10..master`, `--since=10.days.ago master`).\n+\n+All of these simple cases are OK (assuming we have a \"master\" and\n+\"next\" branch):\n+\n+----------------\n+$ git bundle create master.bundle master\n+$ echo master | git bundle create master.bundle --stdin\n+$ git bundle create master-and-next.bundle master next\n+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin\n+----------------\n+\n+And so are these (and the same but omitted `--stdin` examples):\n+\n+----------------\n+$ git bundle create recent-master.bundle master~10..master\n+$ git bundle create recent-updates.bundle master~10..master next~5..next\n+----------------\n+\n+A revision name or a range whose right-hand-side cannot be resolved to\n+a reference is not accepted:\n+\n+----------------\n+$ git bundle create HEAD.bundle $(git rev-parse HEAD)\n+fatal: Refusing to create empty bundle.\n+$ git bundle create master-yesterday.bundle master~10..master~5\n+fatal: Refusing to create empty bundle.\n+----------------\n \n OBJECT PREREQUISITES\n --------------------\n-- \n2.32.0.1069.g545f0888808\n\n"},{"id":"431625","messageId":"patch-v8-4.4-1f3dcd42863-20210731T082120Z-avarab@gmail.com","threadId":"55869","inReplyTo":"cover-v8-0.4-00000000000-20210731T082120Z-avarab@gmail.com","subject":"[PATCH v8 4/4] bundle doc: replace \"basis\" with \"prerequsite(s)\"","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-07-31T08:23:07Z","receivedAt":"2021-07-31T08:23:25Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"In the preceding commits we introduced new documentation that talks\nabout \"[commit|object] prerequsite(s)\", but also faithfully moved\naround existing documentation that talks about the \"basis\".\n\nLet's change both that moved-around documentation and other existing\ndocumentation in the file to consistently use \"[commit|object]\"\nprerequisite(s)\" instead of talking about \"basis\". The mention of\n\"basis\" isn't wrong, but readers will be helped by us using only one\nterm throughout the document for this concept.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-bundle.txt | 14 +++++++-------\n 1 file changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex f36939ab014..ac0d0038350 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -147,13 +147,13 @@ SPECIFYING REFERENCES\n Revisions must accompanied by reference names to be packaged in a\n bundle.\n \n-More than one reference may be packaged, and more than one basis can\n+More than one reference may be packaged, and more than one set of prerequisite objects can\n be specified. The objects packaged are those not contained in the\n-union of the given bases.\n+union of the prerequisites.\n \n The 'git bundle create' command resolves the reference names for you\n using the same rules as `git rev-parse --abbrev-ref=loose`. Each\n-basis can be specified explicitly (e.g. `^master~10`), or implicitly\n+prerequisite can be specified explicitly (e.g. `^master~10`), or implicitly\n (e.g. `master~10..master`, `--since=10.days.ago master`).\n \n All of these simple cases are OK (assuming we have a \"master\" and\n@@ -236,7 +236,7 @@ but we can move data from A to B via some mechanism (CD, email, etc.).\n We want to update R2 with development made on the branch master in R1.\n \n To bootstrap the process, you can first create a bundle that does not have\n-any basis. You can use a tag to remember up to what commit you last\n+any prerequisites. You can use a tag to remember up to what commit you last\n processed, in order to make it easy to later update the other repository\n with an incremental bundle:\n \n@@ -287,7 +287,7 @@ machineB$ git pull\n \n If you know up to what commit the intended recipient repository should\n have the necessary objects, you can use that knowledge to specify the\n-basis, giving a cut-off point to limit the revisions and objects that go\n+prerequisites, giving a cut-off point to limit the revisions and objects that go\n in the resulting bundle. The previous example used the lastR2bundle tag\n for this purpose, but you can use any other options that you would give to\n the linkgit:git-log[1] command. Here are more examples:\n@@ -298,7 +298,7 @@ You can use a tag that is present in both:\n $ git bundle create mybundle v1.0.0..master\n ----------------\n \n-You can use a basis based on time:\n+You can use a prerequisite based on time:\n \n ----------------\n $ git bundle create mybundle --since=10.days master\n@@ -311,7 +311,7 @@ $ git bundle create mybundle -10 master\n ----------------\n \n You can run `git-bundle verify` to see if you can extract from a bundle\n-that was created with a basis:\n+that was created with a prerequisite:\n \n ----------------\n $ git bundle verify mybundle\n-- \n2.32.0.1069.g545f0888808\n\n"}]}