* [PATCH v4 1/3] bundle doc: rewrite the "DESCRIPTION" section
2021-06-30 9:16 ` [PATCH v4 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
@ 2021-06-30 9:16 ` Ævar Arnfjörð Bjarmason
2021-06-30 9:16 ` [PATCH v4 2/3] bundle doc: split out open v.s. closed discussion from <rev-arg> Ævar Arnfjörð Bjarmason
` (2 subsequent siblings)
3 siblings, 0 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-30 9:16 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin,
Ævar Arnfjörð Bjarmason
Rewrite the "DESCRIPTION" section for "git bundle" to start by talking
about what bundles are in general terms, rather than diving directly
into one example of what they might be used for.
This changes documentation that's been substantially the same ever
since the command was added in 2e0afafebd8 (Add git-bundle: move
objects and references by archive, 2007-02-22).
I've split up the DESCRIPTION into that section and a "BUNDLE FORMAT"
section, it briefly discusses the format, but then links to the
technical/bundle-format.txt documentation.
The "the user must specify a basis" part of this is discussed below in
"SPECIFYING REFERENCES", so I'm removing that part and letting the
brief mention of "thin" suffice.
To the extent that we should say more on the topic that documentation
will be improved by subsequent commits.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 45 ++++++++++++++++++++++++------------
1 file changed, 30 insertions(+), 15 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b6..e19c2b83c91 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -18,21 +18,36 @@ SYNOPSIS
DESCRIPTION
-----------
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
-
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
-
-As no
-direct connection between the repositories exists, the user must specify a
-basis for the bundle that is held by the destination repository: the
-bundle assumes that all objects in the basis are already in the
-destination repository.
+Create, unpack, and manipulate "bundle" files. Bundles are used for
+the "offline" transfer of Git objects without an active "server"
+sitting on the other side of the network connection.
+
+They can be used to create both incremental and full backups of a
+repository, and to relay the state of the references in one repository
+to another.
+
+Git commands that fetch or otherwise "read" via protocols such as
+`ssh://` and `https://` can also operate on bundle files. It is
+possible linkgit:git-clone[1] a new repository from a bundle, to use
+linkgit:git-fetch[1] to fetch from one, and to list the references
+contained within it with linkgit:git-ls-remote[1]. There's no
+corresponding "write" support, i.e.a 'git push' into a bundle is not
+supported.
+
+See the "EXAMPLES" section below for examples of how to use bundles.
+
+BUNDLE FORMAT
+-------------
+
+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
+header indicating what references are contained within the bundle. The
+header is (mostly) in the format emitted by linkgit:git-show-ref[1].
+
+Like the the packed archive format itself bundles can either be
+self-contained or thin (see "--thin" in linkgit:git-pack-objects[1]).
+
+See link:technical/bundle-format.html[the `bundle-format`
+documentation] for more details.
OPTIONS
-------
--
2.32.0.613.g8e17abc2eb
^ permalink raw reply related [flat|nested] 41+ messages in thread* [PATCH v4 2/3] bundle doc: split out open v.s. closed discussion from <rev-arg>
2021-06-30 9:16 ` [PATCH v4 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-06-30 9:16 ` [PATCH v4 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
@ 2021-06-30 9:16 ` Ævar Arnfjörð Bjarmason
2021-06-30 21:13 ` Junio C Hamano
2021-06-30 9:16 ` [PATCH v4 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
2021-07-02 11:26 ` [PATCH v5 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
3 siblings, 1 reply; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-30 9:16 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin,
Ævar Arnfjörð Bjarmason
Split out the discussion of why you should or should not create "open
bundles" into a new section, away from the discussion of our handling
of the rev-args syntax.
See 2e0afafebd (Add git-bundle: move objects and references by
archive, 2007-02-22) for the introduction of the documentation being
changed here.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 40 +++++++++++++++++++++++++++++++-----
1 file changed, 35 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index e19c2b83c91..3bb3b71526c 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -44,7 +44,8 @@ header indicating what references are contained within the bundle. The
header is (mostly) in the format emitted by linkgit:git-show-ref[1].
Like the the packed archive format itself bundles can either be
-self-contained or thin (see "--thin" in linkgit:git-pack-objects[1]).
+self-contained or thin, see the "OPEN (THIN) AND CLOSED BUNDLES"
+section below.
See link:technical/bundle-format.html[the `bundle-format`
documentation] for more details.
@@ -141,10 +142,20 @@ contained in the union of the given bases. Each basis can be
specified explicitly (e.g. `^master~10`), or implicitly (e.g.
`master~10..master`, `--since=10.days.ago master`).
-It is very important that the basis used be held by the destination.
-It is okay to err on the side of caution, causing the bundle file
-to contain objects already in the destination, as these are ignored
-when unpacking at the destination.
+OPEN AND CLOSED BUNDLES
+-----------------------
+
+When creating bundles it is possible to create bundle tips that are
+either closed or open under reachability, i.e. those that contain all
+the history needed to get to a given point (closed), and those that do
+not (open). A revision such as "master" will produce a closed tip, a
+range such as "master~2..master" will not (unless the full history is
+contained within that range).
+
+When creating "open" bundles it is very important that the basis used
+be held by the destination. It is okay to err on the side of caution,
+causing the bundle file to contain objects already in the destination,
+as these are ignored when unpacking at the destination.
`git clone` can use any bundle created without negative refspecs
(e.g., `new`, but not `old..new`).
@@ -154,6 +165,25 @@ If you want to provide the same set of refs that a clone directly
from the source repository would get, use `--branches --tags` for
the `<git-rev-list-args>`.
+THIN BUNDLES
+------------
+
+Bundles that are "open" (see above) are created "thin" by using the
+`--thin` option to linkgit:git-pack-objects[1]. Whether a bundle (or
+packfile) is "thin" is a subset of whether it's "open". What "thin"
+means is that such a packfile can store an object in a deltified form
+against a base object that is not in the same packfile.
+
+To put it another way, when creating "open" bundles we assume that the
+objects leading up to the starting range(s) already exist in the
+recipient repository, which allows us to save space. When we run 'git
+bundle unbundle' we invoke linkgit:git-index-pack[1] with the
+`--fix-thin` option.
+
+See the discussion of "thin pack" in
+link:technical/pack-format.html[the pack format documentation] for
+further details.
+
EXAMPLES
--------
--
2.32.0.613.g8e17abc2eb
^ permalink raw reply related [flat|nested] 41+ messages in thread
* Re: [PATCH v4 2/3] bundle doc: split out open v.s. closed discussion from <rev-arg>
2021-06-30 9:16 ` [PATCH v4 2/3] bundle doc: split out open v.s. closed discussion from <rev-arg> Ævar Arnfjörð Bjarmason
@ 2021-06-30 21:13 ` Junio C Hamano
0 siblings, 0 replies; 41+ messages in thread
From: Junio C Hamano @ 2021-06-30 21:13 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Johannes Schindelin
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> Split out the discussion of why you should or should not create "open
> bundles" into a new section, away from the discussion of our handling
> of the rev-args syntax.
I changed my mind about this part.
* There is no option to create a bundle with one or more
prerequisite commits with a non-thin packfile as its payload
part. So "THIN BUNDLE" is an unnecessary new jargon and concept
that does not help readers at all, because there is no "thick
bundle" that has prerequisite commits. Let's not introduce such
a new word.
* We do not call DAG in our history with bottom end (i.e. a range
with one or more uninteresting commits) an "open history". Let's
not invent the words, "open" vs "close", to describe the history
recorded in a bundle, either.
We do already have an appropriate phrase we can use to explain what
you wrote in open/close section: "the prerequisite commits" (find it
in the description of "verify" subcommand) and that has been a
concept well understood for a long time, ever since 2e0afafe (Add
git-bundle: move objects and references by archive, 2007-02-22)
introduced the bundle format. Let's use that phrase, instead of
inventing a new word.
In short, there are two kinds of bundles.
- A bundle with one or more prerequisite commits can only be
extracted in a repository that already has all these prerequisite
commits and the history behind them, and "git bundle verify" is
an easy way to check if your recipient repository has the
prerequisites. The payload in such a bundle is always a thin
packfile, but such a technical detail does not concern readers.
- A bundle without any prerequisites can be extracted into
anywhere, even into an empty repository, or cloned from it.
And that should be sufficient to base your new paragraph(s).
Sorry for having made a potentially confusing comment earlier. What
I said about open vs thin was technically correct (i.e. there wasn't
fundamental reason why a bundle with prerequisites MUST use a thin
pack as its payload---we designed it that way because such a bundle
MUST be extracted in a repository with these prerequisites present,
hence it was OK to assume that a --fix-thin would work while
extracting such a bundle), but it is irrelevant in practice because
you cannot ask for a thick packfile to be created when creating such
a bundle anyway.
Thanks.
^ permalink raw reply [flat|nested] 41+ messages in thread
* [PATCH v4 3/3] bundle doc: elaborate on rev<->ref restriction
2021-06-30 9:16 ` [PATCH v4 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-06-30 9:16 ` [PATCH v4 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
2021-06-30 9:16 ` [PATCH v4 2/3] bundle doc: split out open v.s. closed discussion from <rev-arg> Ævar Arnfjörð Bjarmason
@ 2021-06-30 9:16 ` Ævar Arnfjörð Bjarmason
2021-07-02 11:26 ` [PATCH v5 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
3 siblings, 0 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-06-30 9:16 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin,
Ævar Arnfjörð Bjarmason
Elaborate on the restriction that you cannot provide a revision that
doesn't resolve to a reference in the "SPECIFYING REFERENCES" section
with examples.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------
1 file changed, 39 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 3bb3b71526c..2216b9f2843 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -133,14 +133,45 @@ unbundle <file>::
SPECIFYING REFERENCES
---------------------
-'git bundle' will only package references that are shown by
-'git show-ref': this includes heads, tags, and remote heads. References
-such as `master~1` cannot be packaged, but are perfectly suitable for
-defining the basis. More than one reference may be packaged, and more
-than one basis can be specified. The objects packaged are those not
-contained in the union of the given bases. Each basis can be
-specified explicitly (e.g. `^master~10`), or implicitly (e.g.
-`master~10..master`, `--since=10.days.ago master`).
+Revisions must accompanied by reference names to be packaged in a
+bundle, since the header of the bundle is in a format similar to 'git
+show-ref'.
+
+More than one reference may be packaged, and more than one basis can
+be specified. The objects packaged are those not contained in the
+union of the given bases.
+
+The 'git bundle create' command resolves the reference names for you
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
+basis can be specified explicitly (e.g. `^master~10`), or implicitly
+(e.g. `master~10..master`, `--since=10.days.ago master`).
+
+All of these simple cases are OK (assuming we have a "master" and
+"next" branch):
+
+----------------
+$ git bundle create master.bundle master
+$ echo master | git bundle create master.bundle --stdin
+$ git bundle create master-and-next.bundle master next
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
+----------------
+
+And so are these (and the same but omitted `--stdin` examples):
+
+----------------
+$ git bundle create recent-master.bundle master~10..master
+$ git bundle create recent-updates.bundle master~10..master next~5..next
+----------------
+
+A revision name or a range whose right-hand-side cannot be resolved to
+a reference is not accepted:
+
+----------------
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.
+----------------
OPEN AND CLOSED BUNDLES
-----------------------
--
2.32.0.613.g8e17abc2eb
^ permalink raw reply related [flat|nested] 41+ messages in thread
* [PATCH v5 0/3] bundle doc: generalize & elaborate
2021-06-30 9:16 ` [PATCH v4 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
` (2 preceding siblings ...)
2021-06-30 9:16 ` [PATCH v4 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
@ 2021-07-02 11:26 ` Ævar Arnfjörð Bjarmason
2021-07-02 11:26 ` [PATCH v5 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
` (4 more replies)
3 siblings, 5 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-02 11:26 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin,
Ævar Arnfjörð Bjarmason
A v5 of improvements to the "git bundle" documentation. See
http://lore.kernel.org/git/cover-0.3-00000000000-20210630T091548Z-avarab@gmail.com
for v4.
This hopefully addresses Junio's concern in
https://lore.kernel.org/git/xmqqk0mbt5rj.fsf@gitster.g/
I didn't remove the discussion of "thin packs" entirely, but now the
whole section about "open" v.s. "closed" doesn't use that wording at
all, we now talk only about whether a bundle includes prerequisite
commits, and use the same language as git-rev-list does when referring
to "exclusions'.
The mention of "think pack" is left in the "BUNDLE FORMAT"
section. It's made clear that it doesn't matter to the end result, but
that it's noted as a reference to other docs. We then go on to link to
the bundle & pack technical format docs for the overly curious.
Ævar Arnfjörð Bjarmason (3):
bundle doc: rewrite the "DESCRIPTION" section
bundle doc: elaborate on object prerequisites
bundle doc: elaborate on rev<->ref restriction
Documentation/git-bundle.txt | 130 ++++++++++++++++++++++++++++-------
1 file changed, 104 insertions(+), 26 deletions(-)
Range-diff against v4:
1: d10060a237e ! 1: 3b447500da9 bundle doc: rewrite the "DESCRIPTION" section
@@ Commit message
technical/bundle-format.txt documentation.
The "the user must specify a basis" part of this is discussed below in
- "SPECIFYING REFERENCES", so I'm removing that part and letting the
- brief mention of "thin" suffice.
+ "SPECIFYING REFERENCES", and will be further elaborated on in a
+ subsequent commit. So I'm removing that part and letting the mention
+ of "revision exclusions" suffice.
- To the extent that we should say more on the topic that documentation
- will be improved by subsequent commits.
+ There was a discussion about whether to say anything at all about
+ "thin packs" here[1]. I think it's good to mention it for the curious
+ reader willing to read the technical docs, but let's explicitly say
+ that there's no "thick pack", and that the difference shouldn't
+ matter.
+
+ 1. http://lore.kernel.org/git/xmqqk0mbt5rj.fsf@gitster.g
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
@@ Documentation/git-bundle.txt: SYNOPSIS
+header is (mostly) in the format emitted by linkgit:git-show-ref[1].
+
+Like the the packed archive format itself bundles can either be
-+self-contained or thin (see "--thin" in linkgit:git-pack-objects[1]).
++self-contained, or be created using exclusions.
++
++Bundles created using revision exclusions are "thin packs" created
++using the `--thin` option to linkgit:git-pack-objects[1], and
++unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].
++
++There is no option to create a "thick pack" when using revision
++exclusions, users should not be concerned about the difference. By
++using "thin packs" bundles created using exclusions are smaller in
++size. That they're "thin" under the hood is merely noted here as a
++curiosity, and as a reference to other documentation
+
+See link:technical/bundle-format.html[the `bundle-format`
-+documentation] for more details.
++documentation] for more details and the discussion of "thin pack" in
++link:technical/pack-format.html[the pack format documentation] for
++further details.
OPTIONS
-------
2: 6a312fbdb01 ! 2: 444b06740bc bundle doc: split out open v.s. closed discussion from <rev-arg>
@@ Metadata
Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Commit message ##
- bundle doc: split out open v.s. closed discussion from <rev-arg>
+ bundle doc: elaborate on object prerequisites
- Split out the discussion of why you should or should not create "open
- bundles" into a new section, away from the discussion of our handling
- of the rev-args syntax.
+ Split out the discussion bout "object prerequisites" into its own
+ section, and add some more examples of the common cases.
See 2e0afafebd (Add git-bundle: move objects and references by
archive, 2007-02-22) for the introduction of the documentation being
@@ Commit message
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Documentation/git-bundle.txt ##
-@@ Documentation/git-bundle.txt: header indicating what references are contained within the bundle. The
- header is (mostly) in the format emitted by linkgit:git-show-ref[1].
+@@ Documentation/git-bundle.txt: header is (mostly) in the format emitted by linkgit:git-show-ref[1].
Like the the packed archive format itself bundles can either be
--self-contained or thin (see "--thin" in linkgit:git-pack-objects[1]).
-+self-contained or thin, see the "OPEN (THIN) AND CLOSED BUNDLES"
-+section below.
+ self-contained, or be created using exclusions.
++See the "OBJECT PREREQUISITES" section below.
- See link:technical/bundle-format.html[the `bundle-format`
- documentation] for more details.
+ Bundles created using revision exclusions are "thin packs" created
+ using the `--thin` option to linkgit:git-pack-objects[1], and
@@ Documentation/git-bundle.txt: contained in the union of the given bases. Each basis can be
specified explicitly (e.g. `^master~10`), or implicitly (e.g.
`master~10..master`, `--since=10.days.ago master`).
-It is very important that the basis used be held by the destination.
--It is okay to err on the side of caution, causing the bundle file
--to contain objects already in the destination, as these are ignored
--when unpacking at the destination.
-+OPEN AND CLOSED BUNDLES
-+-----------------------
++OBJECT PREREQUISITES
++--------------------
+
-+When creating bundles it is possible to create bundle tips that are
-+either closed or open under reachability, i.e. those that contain all
-+the history needed to get to a given point (closed), and those that do
-+not (open). A revision such as "master" will produce a closed tip, a
-+range such as "master~2..master" will not (unless the full history is
-+contained within that range).
++When creating bundles it is possible to create a fully self-contained
++bundle with all the prerequisite objects, as well as providing
++negative revisions to exclude prerequisite objects.
+
-+When creating "open" bundles it is very important that the basis used
-+be held by the destination. It is okay to err on the side of caution,
-+causing the bundle file to contain objects already in the destination,
-+as these are ignored when unpacking at the destination.
++A revision such as `new` will produce a tip with all the prerequisite
++objects needed for the `new` reference.
++
++A revision range such as `old..new` will produce a bundle tip that'll
++require any objects existing before `new` to already be present in the
++repository performing the 'git bundle unbundle' operation.
++
++A self-contained bundle without any prerequisites can be extracted
++into anywhere, even into an empty repository, or be cloned from
++(i.e., `new`, but not `old..new`).
++
+ It is okay to err on the side of caution, causing the bundle file
+ to contain objects already in the destination, as these are ignored
+ when unpacking at the destination.
- `git clone` can use any bundle created without negative refspecs
- (e.g., `new`, but not `old..new`).
-@@ Documentation/git-bundle.txt: If you want to provide the same set of refs that a clone directly
+-`git clone` can use any bundle created without negative refspecs
+-(e.g., `new`, but not `old..new`).
+ If you want to match `git clone --mirror`, which would include your
+ refs such as `refs/remotes/*`, use `--all`.
+ If you want to provide the same set of refs that a clone directly
from the source repository would get, use `--branches --tags` for
the `<git-rev-list-args>`.
-+THIN BUNDLES
-+------------
-+
-+Bundles that are "open" (see above) are created "thin" by using the
-+`--thin` option to linkgit:git-pack-objects[1]. Whether a bundle (or
-+packfile) is "thin" is a subset of whether it's "open". What "thin"
-+means is that such a packfile can store an object in a deltified form
-+against a base object that is not in the same packfile.
-+
-+To put it another way, when creating "open" bundles we assume that the
-+objects leading up to the starting range(s) already exist in the
-+recipient repository, which allows us to save space. When we run 'git
-+bundle unbundle' we invoke linkgit:git-index-pack[1] with the
-+`--fix-thin` option.
-+
-+See the discussion of "thin pack" in
-+link:technical/pack-format.html[the pack format documentation] for
-+further details.
++The 'git bundle verify' command can be used to check whether your
++recipient repository has the required prerequisite commits for a
++bundle.
+
EXAMPLES
--------
3: 47b8dacb4aa ! 3: 6d8f2f27088 bundle doc: elaborate on rev<->ref restriction
@@ Documentation/git-bundle.txt: unbundle <file>::
+fatal: Refusing to create empty bundle.
+----------------
- OPEN AND CLOSED BUNDLES
- -----------------------
+ OBJECT PREREQUISITES
+ --------------------
--
2.32.0.632.g49a94b9226d
^ permalink raw reply [flat|nested] 41+ messages in thread* [PATCH v5 1/3] bundle doc: rewrite the "DESCRIPTION" section
2021-07-02 11:26 ` [PATCH v5 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
@ 2021-07-02 11:26 ` Ævar Arnfjörð Bjarmason
2021-07-02 11:26 ` [PATCH v5 2/3] bundle doc: elaborate on object prerequisites Ævar Arnfjörð Bjarmason
` (3 subsequent siblings)
4 siblings, 0 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-02 11:26 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin,
Ævar Arnfjörð Bjarmason
Rewrite the "DESCRIPTION" section for "git bundle" to start by talking
about what bundles are in general terms, rather than diving directly
into one example of what they might be used for.
This changes documentation that's been substantially the same ever
since the command was added in 2e0afafebd8 (Add git-bundle: move
objects and references by archive, 2007-02-22).
I've split up the DESCRIPTION into that section and a "BUNDLE FORMAT"
section, it briefly discusses the format, but then links to the
technical/bundle-format.txt documentation.
The "the user must specify a basis" part of this is discussed below in
"SPECIFYING REFERENCES", and will be further elaborated on in a
subsequent commit. So I'm removing that part and letting the mention
of "revision exclusions" suffice.
There was a discussion about whether to say anything at all about
"thin packs" here[1]. I think it's good to mention it for the curious
reader willing to read the technical docs, but let's explicitly say
that there's no "thick pack", and that the difference shouldn't
matter.
1. http://lore.kernel.org/git/xmqqk0mbt5rj.fsf@gitster.g
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 57 ++++++++++++++++++++++++++----------
1 file changed, 42 insertions(+), 15 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b6..9c743aed49f 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -18,21 +18,48 @@ SYNOPSIS
DESCRIPTION
-----------
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
-
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
-
-As no
-direct connection between the repositories exists, the user must specify a
-basis for the bundle that is held by the destination repository: the
-bundle assumes that all objects in the basis are already in the
-destination repository.
+Create, unpack, and manipulate "bundle" files. Bundles are used for
+the "offline" transfer of Git objects without an active "server"
+sitting on the other side of the network connection.
+
+They can be used to create both incremental and full backups of a
+repository, and to relay the state of the references in one repository
+to another.
+
+Git commands that fetch or otherwise "read" via protocols such as
+`ssh://` and `https://` can also operate on bundle files. It is
+possible linkgit:git-clone[1] a new repository from a bundle, to use
+linkgit:git-fetch[1] to fetch from one, and to list the references
+contained within it with linkgit:git-ls-remote[1]. There's no
+corresponding "write" support, i.e.a 'git push' into a bundle is not
+supported.
+
+See the "EXAMPLES" section below for examples of how to use bundles.
+
+BUNDLE FORMAT
+-------------
+
+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
+header indicating what references are contained within the bundle. The
+header is (mostly) in the format emitted by linkgit:git-show-ref[1].
+
+Like the the packed archive format itself bundles can either be
+self-contained, or be created using exclusions.
+
+Bundles created using revision exclusions are "thin packs" created
+using the `--thin` option to linkgit:git-pack-objects[1], and
+unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].
+
+There is no option to create a "thick pack" when using revision
+exclusions, users should not be concerned about the difference. By
+using "thin packs" bundles created using exclusions are smaller in
+size. That they're "thin" under the hood is merely noted here as a
+curiosity, and as a reference to other documentation
+
+See link:technical/bundle-format.html[the `bundle-format`
+documentation] for more details and the discussion of "thin pack" in
+link:technical/pack-format.html[the pack format documentation] for
+further details.
OPTIONS
-------
--
2.32.0.632.g49a94b9226d
^ permalink raw reply related [flat|nested] 41+ messages in thread* [PATCH v5 2/3] bundle doc: elaborate on object prerequisites
2021-07-02 11:26 ` [PATCH v5 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-07-02 11:26 ` [PATCH v5 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
@ 2021-07-02 11:26 ` Ævar Arnfjörð Bjarmason
2021-07-02 15:10 ` Junio C Hamano
2021-07-02 11:26 ` [PATCH v5 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
` (2 subsequent siblings)
4 siblings, 1 reply; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-02 11:26 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin,
Ævar Arnfjörð Bjarmason
Split out the discussion bout "object prerequisites" into its own
section, and add some more examples of the common cases.
See 2e0afafebd (Add git-bundle: move objects and references by
archive, 2007-02-22) for the introduction of the documentation being
changed here.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 26 +++++++++++++++++++++++---
1 file changed, 23 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 9c743aed49f..f5430029b8c 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -45,6 +45,7 @@ header is (mostly) in the format emitted by linkgit:git-show-ref[1].
Like the the packed archive format itself bundles can either be
self-contained, or be created using exclusions.
+See the "OBJECT PREREQUISITES" section below.
Bundles created using revision exclusions are "thin packs" created
using the `--thin` option to linkgit:git-pack-objects[1], and
@@ -153,19 +154,38 @@ contained in the union of the given bases. Each basis can be
specified explicitly (e.g. `^master~10`), or implicitly (e.g.
`master~10..master`, `--since=10.days.ago master`).
-It is very important that the basis used be held by the destination.
+OBJECT PREREQUISITES
+--------------------
+
+When creating bundles it is possible to create a fully self-contained
+bundle with all the prerequisite objects, as well as providing
+negative revisions to exclude prerequisite objects.
+
+A revision such as `new` will produce a tip with all the prerequisite
+objects needed for the `new` reference.
+
+A revision range such as `old..new` will produce a bundle tip that'll
+require any objects existing before `new` to already be present in the
+repository performing the 'git bundle unbundle' operation.
+
+A self-contained bundle without any prerequisites can be extracted
+into anywhere, even into an empty repository, or be cloned from
+(i.e., `new`, but not `old..new`).
+
It is okay to err on the side of caution, causing the bundle file
to contain objects already in the destination, as these are ignored
when unpacking at the destination.
-`git clone` can use any bundle created without negative refspecs
-(e.g., `new`, but not `old..new`).
If you want to match `git clone --mirror`, which would include your
refs such as `refs/remotes/*`, use `--all`.
If you want to provide the same set of refs that a clone directly
from the source repository would get, use `--branches --tags` for
the `<git-rev-list-args>`.
+The 'git bundle verify' command can be used to check whether your
+recipient repository has the required prerequisite commits for a
+bundle.
+
EXAMPLES
--------
--
2.32.0.632.g49a94b9226d
^ permalink raw reply related [flat|nested] 41+ messages in thread* Re: [PATCH v5 2/3] bundle doc: elaborate on object prerequisites
2021-07-02 11:26 ` [PATCH v5 2/3] bundle doc: elaborate on object prerequisites Ævar Arnfjörð Bjarmason
@ 2021-07-02 15:10 ` Junio C Hamano
0 siblings, 0 replies; 41+ messages in thread
From: Junio C Hamano @ 2021-07-02 15:10 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Johannes Schindelin
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> Split out the discussion bout "object prerequisites" into its own
> section, and add some more examples of the common cases.
>
> See 2e0afafebd (Add git-bundle: move objects and references by
> archive, 2007-02-22) for the introduction of the documentation being
> changed here.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> Documentation/git-bundle.txt | 26 +++++++++++++++++++++++---
> 1 file changed, 23 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
> index 9c743aed49f..f5430029b8c 100644
> --- a/Documentation/git-bundle.txt
> +++ b/Documentation/git-bundle.txt
> @@ -45,6 +45,7 @@ header is (mostly) in the format emitted by linkgit:git-show-ref[1].
>
> Like the the packed archive format itself bundles can either be
> self-contained, or be created using exclusions.
> +See the "OBJECT PREREQUISITES" section below.
>
> Bundles created using revision exclusions are "thin packs" created
> using the `--thin` option to linkgit:git-pack-objects[1], and
> @@ -153,19 +154,38 @@ contained in the union of the given bases. Each basis can be
> specified explicitly (e.g. `^master~10`), or implicitly (e.g.
> `master~10..master`, `--since=10.days.ago master`).
>
> -It is very important that the basis used be held by the destination.
> +OBJECT PREREQUISITES
> +--------------------
> +
> +When creating bundles it is possible to create a fully self-contained
> +bundle with all the prerequisite objects, as well as providing
> +negative revisions to exclude prerequisite objects.
> +
> +A revision such as `new` will produce a tip with all the prerequisite
> +objects needed for the `new` reference.
The above two paragraphs use the word "prerequisites" in a confusing
way. The original meaning of the word in the context of talking
about a bundle is "you must have these commits in the receiving
repository for the bundle to be unbundle-able".
"git bundle create recent.bndl old..new" creates a bundle that
requires 'old' (and everything reachable from it) to exist in the
receiving repository. We call the object 'old' (not the objects
reachable from it) the prerequisite of the bundle.
"git bundle create full.bndl new" creates a bundle that needs no
prerequistes.
It is confusing to say that full.bndl has all the prerequisite
objects needed. It is correct to say that it has all the objects
reachable from 'new', but if we wanted to say that, we did not have
to introduce the new term "prerequisite" when we invented the bundle
format. The concept "prerequisite" tries to convey is different.
So, the two paragraphs above use the word "prerequisite" when it
wants to talk about "reachable objects" (except for one use---the
one in "to exclude prerequisite objects" is correctly used), which
is confusing. Here is the first paragraph with probably a better
phrasing.
... it is possible to create a self-contained bundle that
can be unbundled in an empty repository, as well as
providing negative revisions to exclude objects needed in
the earlier parts of the history.
As to the second paragraph:
... will produce a bundle without any prerequisites. It can
be unbundled in any repository to obtain a full history that
leads to the commit `new`.
By the way, I needed to read "a revision such as `new` will produce
..." three times before realizing that the reader must fill quite a
lot of missing words to understand what the sentence wanted to say,
which is:
(feeding) a revision such as `new` (to "git bundle create"
as the revision range argument) will produce ...
I think it is easier to follow if you spelled the command out, e.g.
A command
$ git bundle create full.bndl new
will create a bundle file that contains all the objects
reachable from the branch 'new'.
> +A revision range such as `old..new` will produce a bundle tip that'll
> +require any objects existing before `new` to already be present in the
> +repository performing the 'git bundle unbundle' operation.
Getting warmer ;-). In this case, 'old' is the prerequisite, so
... that'll require the commit 'old' (and any objects reachable
from it) to exist for the bundle to be "unbundle"-able.
would be correct.
> +A self-contained bundle without any prerequisites can be extracted
> +into anywhere, even into an empty repository, or be cloned from
> +(i.e., `new`, but not `old..new`).
> +
This is entirely correct.
> +The 'git bundle verify' command can be used to check whether your
> +recipient repository has the required prerequisite commits for a
> +bundle.
So is this.
Thanks.
^ permalink raw reply [flat|nested] 41+ messages in thread
* [PATCH v5 3/3] bundle doc: elaborate on rev<->ref restriction
2021-07-02 11:26 ` [PATCH v5 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-07-02 11:26 ` [PATCH v5 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
2021-07-02 11:26 ` [PATCH v5 2/3] bundle doc: elaborate on object prerequisites Ævar Arnfjörð Bjarmason
@ 2021-07-02 11:26 ` Ævar Arnfjörð Bjarmason
2021-07-20 14:20 ` [PATCH v6 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-07-27 0:24 ` [PATCH v7 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
4 siblings, 0 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-02 11:26 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin,
Ævar Arnfjörð Bjarmason
Elaborate on the restriction that you cannot provide a revision that
doesn't resolve to a reference in the "SPECIFYING REFERENCES" section
with examples.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------
1 file changed, 39 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index f5430029b8c..9a96afedaf3 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -145,14 +145,45 @@ unbundle <file>::
SPECIFYING REFERENCES
---------------------
-'git bundle' will only package references that are shown by
-'git show-ref': this includes heads, tags, and remote heads. References
-such as `master~1` cannot be packaged, but are perfectly suitable for
-defining the basis. More than one reference may be packaged, and more
-than one basis can be specified. The objects packaged are those not
-contained in the union of the given bases. Each basis can be
-specified explicitly (e.g. `^master~10`), or implicitly (e.g.
-`master~10..master`, `--since=10.days.ago master`).
+Revisions must accompanied by reference names to be packaged in a
+bundle, since the header of the bundle is in a format similar to 'git
+show-ref'.
+
+More than one reference may be packaged, and more than one basis can
+be specified. The objects packaged are those not contained in the
+union of the given bases.
+
+The 'git bundle create' command resolves the reference names for you
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
+basis can be specified explicitly (e.g. `^master~10`), or implicitly
+(e.g. `master~10..master`, `--since=10.days.ago master`).
+
+All of these simple cases are OK (assuming we have a "master" and
+"next" branch):
+
+----------------
+$ git bundle create master.bundle master
+$ echo master | git bundle create master.bundle --stdin
+$ git bundle create master-and-next.bundle master next
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
+----------------
+
+And so are these (and the same but omitted `--stdin` examples):
+
+----------------
+$ git bundle create recent-master.bundle master~10..master
+$ git bundle create recent-updates.bundle master~10..master next~5..next
+----------------
+
+A revision name or a range whose right-hand-side cannot be resolved to
+a reference is not accepted:
+
+----------------
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.
+----------------
OBJECT PREREQUISITES
--------------------
--
2.32.0.632.g49a94b9226d
^ permalink raw reply related [flat|nested] 41+ messages in thread
* [PATCH v6 0/3] bundle doc: generalize & elaborate
2021-07-02 11:26 ` [PATCH v5 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
` (2 preceding siblings ...)
2021-07-02 11:26 ` [PATCH v5 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
@ 2021-07-20 14:20 ` Ævar Arnfjörð Bjarmason
2021-07-20 14:20 ` [PATCH v6 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
` (2 more replies)
2021-07-27 0:24 ` [PATCH v7 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
4 siblings, 3 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-20 14:20 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin,
Ævar Arnfjörð Bjarmason
A v6 of improvements to the "git bundle" documentation. See
https://lore.kernel.org/git/cover-0.3-00000000000-20210702T112254Z-avarab@gmail.com/
for v5.
Junio, I think this addresess the points you raised in
https://lore.kernel.org/git/xmqq7di8rbtj.fsf@gitster.g/
I used your suggested wording, but changed "empty repository" to "a
repository with no common history" for the purposes of the
documentation that's trying to talk about what you can unbundle where
without ambiguity.
Ævar Arnfjörð Bjarmason (3):
bundle doc: rewrite the "DESCRIPTION" section
bundle doc: elaborate on object prerequisites
bundle doc: elaborate on rev<->ref restriction
Documentation/git-bundle.txt | 141 ++++++++++++++++++++++++++++-------
1 file changed, 115 insertions(+), 26 deletions(-)
Range-diff against v5:
1: 3b447500da9 = 1: d5360bb6f74 bundle doc: rewrite the "DESCRIPTION" section
2: 444b06740bc ! 2: a0f95ce3a1d bundle doc: elaborate on object prerequisites
@@ Documentation/git-bundle.txt: contained in the union of the given bases. Each b
+OBJECT PREREQUISITES
+--------------------
+
-+When creating bundles it is possible to create a fully self-contained
-+bundle with all the prerequisite objects, as well as providing
-+negative revisions to exclude prerequisite objects.
++When creating bundles it is possible to create a self-contained bundle
++that can be unbundled in a repository with no common history, as well
++as providing negative revisions to exclude objects needed in the
++earlier parts of the history.
+
-+A revision such as `new` will produce a tip with all the prerequisite
-+objects needed for the `new` reference.
++Feeding a revision such as `new` to `git bundle create` will create a
++bundle file that contains all the objects reachable from the revision
++`new`. That bundle can be unbundled in any repository to obtain a full
++history that leads to the revision `new`:
++
++----------------
++$ git bundle create full.bundle new
++----------------
+
+A revision range such as `old..new` will produce a bundle tip that'll
-+require any objects existing before `new` to already be present in the
-+repository performing the 'git bundle unbundle' operation.
++that'll require the revision `old` (and any objects reachable from it)
++to exist for the bundle to be "unbundle"-able:
++
++----------------
++$ git bundle create full.bundle old..new
++----------------
+
+A self-contained bundle without any prerequisites can be extracted
+into anywhere, even into an empty repository, or be cloned from
3: 6d8f2f27088 = 3: 6d66d4480ff bundle doc: elaborate on rev<->ref restriction
--
2.32.0.874.ge7a9d58bfcf
^ permalink raw reply [flat|nested] 41+ messages in thread* [PATCH v6 1/3] bundle doc: rewrite the "DESCRIPTION" section
2021-07-20 14:20 ` [PATCH v6 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
@ 2021-07-20 14:20 ` Ævar Arnfjörð Bjarmason
2021-07-20 14:20 ` [PATCH v6 2/3] bundle doc: elaborate on object prerequisites Ævar Arnfjörð Bjarmason
2021-07-20 14:20 ` [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
2 siblings, 0 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-20 14:20 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin,
Ævar Arnfjörð Bjarmason
Rewrite the "DESCRIPTION" section for "git bundle" to start by talking
about what bundles are in general terms, rather than diving directly
into one example of what they might be used for.
This changes documentation that's been substantially the same ever
since the command was added in 2e0afafebd8 (Add git-bundle: move
objects and references by archive, 2007-02-22).
I've split up the DESCRIPTION into that section and a "BUNDLE FORMAT"
section, it briefly discusses the format, but then links to the
technical/bundle-format.txt documentation.
The "the user must specify a basis" part of this is discussed below in
"SPECIFYING REFERENCES", and will be further elaborated on in a
subsequent commit. So I'm removing that part and letting the mention
of "revision exclusions" suffice.
There was a discussion about whether to say anything at all about
"thin packs" here[1]. I think it's good to mention it for the curious
reader willing to read the technical docs, but let's explicitly say
that there's no "thick pack", and that the difference shouldn't
matter.
1. http://lore.kernel.org/git/xmqqk0mbt5rj.fsf@gitster.g
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 57 ++++++++++++++++++++++++++----------
1 file changed, 42 insertions(+), 15 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b6..9c743aed49f 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -18,21 +18,48 @@ SYNOPSIS
DESCRIPTION
-----------
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
-
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
-
-As no
-direct connection between the repositories exists, the user must specify a
-basis for the bundle that is held by the destination repository: the
-bundle assumes that all objects in the basis are already in the
-destination repository.
+Create, unpack, and manipulate "bundle" files. Bundles are used for
+the "offline" transfer of Git objects without an active "server"
+sitting on the other side of the network connection.
+
+They can be used to create both incremental and full backups of a
+repository, and to relay the state of the references in one repository
+to another.
+
+Git commands that fetch or otherwise "read" via protocols such as
+`ssh://` and `https://` can also operate on bundle files. It is
+possible linkgit:git-clone[1] a new repository from a bundle, to use
+linkgit:git-fetch[1] to fetch from one, and to list the references
+contained within it with linkgit:git-ls-remote[1]. There's no
+corresponding "write" support, i.e.a 'git push' into a bundle is not
+supported.
+
+See the "EXAMPLES" section below for examples of how to use bundles.
+
+BUNDLE FORMAT
+-------------
+
+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
+header indicating what references are contained within the bundle. The
+header is (mostly) in the format emitted by linkgit:git-show-ref[1].
+
+Like the the packed archive format itself bundles can either be
+self-contained, or be created using exclusions.
+
+Bundles created using revision exclusions are "thin packs" created
+using the `--thin` option to linkgit:git-pack-objects[1], and
+unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].
+
+There is no option to create a "thick pack" when using revision
+exclusions, users should not be concerned about the difference. By
+using "thin packs" bundles created using exclusions are smaller in
+size. That they're "thin" under the hood is merely noted here as a
+curiosity, and as a reference to other documentation
+
+See link:technical/bundle-format.html[the `bundle-format`
+documentation] for more details and the discussion of "thin pack" in
+link:technical/pack-format.html[the pack format documentation] for
+further details.
OPTIONS
-------
--
2.32.0.874.ge7a9d58bfcf
^ permalink raw reply related [flat|nested] 41+ messages in thread
* [PATCH v6 2/3] bundle doc: elaborate on object prerequisites
2021-07-20 14:20 ` [PATCH v6 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-07-20 14:20 ` [PATCH v6 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
@ 2021-07-20 14:20 ` Ævar Arnfjörð Bjarmason
2021-07-20 20:06 ` Junio C Hamano
2021-07-20 14:20 ` [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
2 siblings, 1 reply; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-20 14:20 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin,
Ævar Arnfjörð Bjarmason
Split out the discussion bout "object prerequisites" into its own
section, and add some more examples of the common cases.
See 2e0afafebd (Add git-bundle: move objects and references by
archive, 2007-02-22) for the introduction of the documentation being
changed here.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 37 +++++++++++++++++++++++++++++++++---
1 file changed, 34 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 9c743aed49f..d5627b8cc51 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -45,6 +45,7 @@ header is (mostly) in the format emitted by linkgit:git-show-ref[1].
Like the the packed archive format itself bundles can either be
self-contained, or be created using exclusions.
+See the "OBJECT PREREQUISITES" section below.
Bundles created using revision exclusions are "thin packs" created
using the `--thin` option to linkgit:git-pack-objects[1], and
@@ -153,19 +154,49 @@ contained in the union of the given bases. Each basis can be
specified explicitly (e.g. `^master~10`), or implicitly (e.g.
`master~10..master`, `--since=10.days.ago master`).
-It is very important that the basis used be held by the destination.
+OBJECT PREREQUISITES
+--------------------
+
+When creating bundles it is possible to create a self-contained bundle
+that can be unbundled in a repository with no common history, as well
+as providing negative revisions to exclude objects needed in the
+earlier parts of the history.
+
+Feeding a revision such as `new` to `git bundle create` will create a
+bundle file that contains all the objects reachable from the revision
+`new`. That bundle can be unbundled in any repository to obtain a full
+history that leads to the revision `new`:
+
+----------------
+$ git bundle create full.bundle new
+----------------
+
+A revision range such as `old..new` will produce a bundle tip that'll
+that'll require the revision `old` (and any objects reachable from it)
+to exist for the bundle to be "unbundle"-able:
+
+----------------
+$ git bundle create full.bundle old..new
+----------------
+
+A self-contained bundle without any prerequisites can be extracted
+into anywhere, even into an empty repository, or be cloned from
+(i.e., `new`, but not `old..new`).
+
It is okay to err on the side of caution, causing the bundle file
to contain objects already in the destination, as these are ignored
when unpacking at the destination.
-`git clone` can use any bundle created without negative refspecs
-(e.g., `new`, but not `old..new`).
If you want to match `git clone --mirror`, which would include your
refs such as `refs/remotes/*`, use `--all`.
If you want to provide the same set of refs that a clone directly
from the source repository would get, use `--branches --tags` for
the `<git-rev-list-args>`.
+The 'git bundle verify' command can be used to check whether your
+recipient repository has the required prerequisite commits for a
+bundle.
+
EXAMPLES
--------
--
2.32.0.874.ge7a9d58bfcf
^ permalink raw reply related [flat|nested] 41+ messages in thread
* Re: [PATCH v6 2/3] bundle doc: elaborate on object prerequisites
2021-07-20 14:20 ` [PATCH v6 2/3] bundle doc: elaborate on object prerequisites Ævar Arnfjörð Bjarmason
@ 2021-07-20 20:06 ` Junio C Hamano
0 siblings, 0 replies; 41+ messages in thread
From: Junio C Hamano @ 2021-07-20 20:06 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Johannes Schindelin
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> +A revision range such as `old..new` will produce a bundle tip that'll
> +that'll require the revision `old` (and any objects reachable from it)
> +to exist for the bundle to be "unbundle"-able:
Will squash in the following while queuing.
Thanks.
diff --git c/Documentation/git-bundle.txt w/Documentation/git-bundle.txt
index e7a685e533..6a45ced017 100644
--- c/Documentation/git-bundle.txt
+++ w/Documentation/git-bundle.txt
@@ -202,8 +202,8 @@ history that leads to the revision `new`:
$ git bundle create full.bundle new
----------------
-A revision range such as `old..new` will produce a bundle tip that'll
-that'll require the revision `old` (and any objects reachable from it)
+A revision range such as `old..new` will produce a bundle file that
+will require the revision `old` (and any objects reachable from it)
to exist for the bundle to be "unbundle"-able:
----------------
^ permalink raw reply related [flat|nested] 41+ messages in thread
* [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction
2021-07-20 14:20 ` [PATCH v6 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-07-20 14:20 ` [PATCH v6 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
2021-07-20 14:20 ` [PATCH v6 2/3] bundle doc: elaborate on object prerequisites Ævar Arnfjörð Bjarmason
@ 2021-07-20 14:20 ` Ævar Arnfjörð Bjarmason
2021-07-20 20:19 ` Junio C Hamano
2 siblings, 1 reply; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-20 14:20 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin,
Ævar Arnfjörð Bjarmason
Elaborate on the restriction that you cannot provide a revision that
doesn't resolve to a reference in the "SPECIFYING REFERENCES" section
with examples.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------
1 file changed, 39 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index d5627b8cc51..e7a685e533e 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -145,14 +145,45 @@ unbundle <file>::
SPECIFYING REFERENCES
---------------------
-'git bundle' will only package references that are shown by
-'git show-ref': this includes heads, tags, and remote heads. References
-such as `master~1` cannot be packaged, but are perfectly suitable for
-defining the basis. More than one reference may be packaged, and more
-than one basis can be specified. The objects packaged are those not
-contained in the union of the given bases. Each basis can be
-specified explicitly (e.g. `^master~10`), or implicitly (e.g.
-`master~10..master`, `--since=10.days.ago master`).
+Revisions must accompanied by reference names to be packaged in a
+bundle, since the header of the bundle is in a format similar to 'git
+show-ref'.
+
+More than one reference may be packaged, and more than one basis can
+be specified. The objects packaged are those not contained in the
+union of the given bases.
+
+The 'git bundle create' command resolves the reference names for you
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
+basis can be specified explicitly (e.g. `^master~10`), or implicitly
+(e.g. `master~10..master`, `--since=10.days.ago master`).
+
+All of these simple cases are OK (assuming we have a "master" and
+"next" branch):
+
+----------------
+$ git bundle create master.bundle master
+$ echo master | git bundle create master.bundle --stdin
+$ git bundle create master-and-next.bundle master next
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
+----------------
+
+And so are these (and the same but omitted `--stdin` examples):
+
+----------------
+$ git bundle create recent-master.bundle master~10..master
+$ git bundle create recent-updates.bundle master~10..master next~5..next
+----------------
+
+A revision name or a range whose right-hand-side cannot be resolved to
+a reference is not accepted:
+
+----------------
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.
+----------------
OBJECT PREREQUISITES
--------------------
--
2.32.0.874.ge7a9d58bfcf
^ permalink raw reply related [flat|nested] 41+ messages in thread
* Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction
2021-07-20 14:20 ` [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
@ 2021-07-20 20:19 ` Junio C Hamano
2021-07-21 9:27 ` Philip Oakley
0 siblings, 1 reply; 41+ messages in thread
From: Junio C Hamano @ 2021-07-20 20:19 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Johannes Schindelin
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> +Revisions must accompanied by reference names to be packaged in a
> +bundle, since the header of the bundle is in a format similar to 'git
> +show-ref'.
This may be an improvement in the way how the description refers to
"show-ref", but we do not have to say anything about "show-ref" ;-)
The reason we should give readers why they must give refs while
creating a bundle, I think, is because the only way to access the
contents of the bundle is to fetch refs from it, and the refs given
to the command when the bundle was created becomes the refs that can
be fetched from the bundle.
Thanks.
^ permalink raw reply [flat|nested] 41+ messages in thread
* Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction
2021-07-20 20:19 ` Junio C Hamano
@ 2021-07-21 9:27 ` Philip Oakley
2021-07-21 16:57 ` Junio C Hamano
0 siblings, 1 reply; 41+ messages in thread
From: Philip Oakley @ 2021-07-21 9:27 UTC (permalink / raw)
To: Junio C Hamano, Ævar Arnfjörð Bjarmason
Cc: git, Johannes Schindelin
On 20/07/2021 21:19, Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> +Revisions must accompanied by reference names to be packaged in a
>> +bundle, since the header of the bundle is in a format similar to 'git
>> +show-ref'.
> This may be an improvement in the way how the description refers to
> "show-ref", but we do not have to say anything about "show-ref" ;-)
>
> The reason we should give readers why they must give refs while
> creating a bundle, I think, is because the only way to access the
> contents of the bundle is to fetch refs from it, and the refs given
> to the command when the bundle was created becomes the refs that can
> be fetched from the bundle.
>
> Thanks.
>
Should the `list-heads` option be mentioned for investigating existing
bundles?
--
Philip
^ permalink raw reply [flat|nested] 41+ messages in thread
* Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction
2021-07-21 9:27 ` Philip Oakley
@ 2021-07-21 16:57 ` Junio C Hamano
2021-07-22 11:37 ` Philip Oakley
0 siblings, 1 reply; 41+ messages in thread
From: Junio C Hamano @ 2021-07-21 16:57 UTC (permalink / raw)
To: Philip Oakley
Cc: Ævar Arnfjörð Bjarmason, git, Johannes Schindelin
Philip Oakley <philipoakley@iee.email> writes:
> Should the `list-heads` option be mentioned for investigating existing
> bundles?
I think 'list-heads' has been listed in the options section. I
however may encourage people to use "git ls-remote one.bndl" over
"git bundle list-heads one.bndl"---they do the same thing, no?
Thanks.
^ permalink raw reply [flat|nested] 41+ messages in thread
* Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction
2021-07-21 16:57 ` Junio C Hamano
@ 2021-07-22 11:37 ` Philip Oakley
2021-07-22 11:46 ` Ævar Arnfjörð Bjarmason
0 siblings, 1 reply; 41+ messages in thread
From: Philip Oakley @ 2021-07-22 11:37 UTC (permalink / raw)
To: Junio C Hamano
Cc: Ævar Arnfjörð Bjarmason, git, Johannes Schindelin
On 21/07/2021 17:57, Junio C Hamano wrote:
> Philip Oakley <philipoakley@iee.email> writes:
>
>> Should the `list-heads` option be mentioned for investigating existing
>> bundles?
> I think 'list-heads' has been listed in the options section.
True, it's why I was suggesting pointing at that route for the extra
details that are beyond just a set of refs.
> I
> however may encourage people to use "git ls-remote one.bndl" over
> "git bundle list-heads one.bndl"---they do the same thing, no?
It is good to provide both directions to the user. The formats may be
different but the content is essentially the same, and redirecting users
to the more core command is useful.
>
> Thanks.
>
>
>
^ permalink raw reply [flat|nested] 41+ messages in thread
* Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction
2021-07-22 11:37 ` Philip Oakley
@ 2021-07-22 11:46 ` Ævar Arnfjörð Bjarmason
2021-07-22 23:14 ` Philip Oakley
0 siblings, 1 reply; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-22 11:46 UTC (permalink / raw)
To: Philip Oakley; +Cc: Junio C Hamano, git, Johannes Schindelin
On Thu, Jul 22 2021, Philip Oakley wrote:
> On 21/07/2021 17:57, Junio C Hamano wrote:
>> Philip Oakley <philipoakley@iee.email> writes:
>>
>>> Should the `list-heads` option be mentioned for investigating existing
>>> bundles?
>> I think 'list-heads' has been listed in the options section.
>
> True, it's why I was suggesting pointing at that route for the extra
> details that are beyond just a set of refs.
>
>> I
>> however may encourage people to use "git ls-remote one.bndl" over
>> "git bundle list-heads one.bndl"---they do the same thing, no?
>
> It is good to provide both directions to the user. The formats may be
> different but the content is essentially the same, and redirecting users
> to the more core command is useful.
>
I'll work those suggestions into a future update of the docs I have
queued, but for now I think talking about list-heads v.s. ls-remote
doesn't have much directly to do with this particular series, correct?
^ permalink raw reply [flat|nested] 41+ messages in thread
* Re: [PATCH v6 3/3] bundle doc: elaborate on rev<->ref restriction
2021-07-22 11:46 ` Ævar Arnfjörð Bjarmason
@ 2021-07-22 23:14 ` Philip Oakley
0 siblings, 0 replies; 41+ messages in thread
From: Philip Oakley @ 2021-07-22 23:14 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: Junio C Hamano, git, Johannes Schindelin
On 22/07/2021 12:46, Ævar Arnfjörð Bjarmason wrote:
> On Thu, Jul 22 2021, Philip Oakley wrote:
>
>> On 21/07/2021 17:57, Junio C Hamano wrote:
>>> Philip Oakley <philipoakley@iee.email> writes:
>>>
>>>> Should the `list-heads` option be mentioned for investigating existing
>>>> bundles?
>>> I think 'list-heads' has been listed in the options section.
>> True, it's why I was suggesting pointing at that route for the extra
>> details that are beyond just a set of refs.
>>
>>> I
>>> however may encourage people to use "git ls-remote one.bndl" over
>>> "git bundle list-heads one.bndl"---they do the same thing, no?
>> It is good to provide both directions to the user. The formats may be
>> different but the content is essentially the same, and redirecting users
>> to the more core command is useful.
>>
> I'll work those suggestions into a future update of the docs I have
> queued, but for now I think talking about list-heads v.s. ls-remote
> doesn't have much directly to do with this particular series, correct?
True.
However I'm still not really clear about the distinction between the
'basis' and the `header references` (that is, the text doesn't make it
clear).
for the future updates, it would also be good if the `--all` and
`--branches --tags` text was also shown in the examples - I continue to
get StackOverflow points for my Q&A on that ;-)
Philip
^ permalink raw reply [flat|nested] 41+ messages in thread
* [PATCH v7 0/3] bundle doc: generalize & elaborate
2021-07-02 11:26 ` [PATCH v5 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
` (3 preceding siblings ...)
2021-07-20 14:20 ` [PATCH v6 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
@ 2021-07-27 0:24 ` Ævar Arnfjörð Bjarmason
2021-07-27 0:24 ` [PATCH v7 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
` (3 more replies)
4 siblings, 4 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-27 0:24 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin, Philip Oakley,
Ævar Arnfjörð Bjarmason
This v7 hopefully addresses the outstanding comments on v6.
The mention of "show-ref" is gone (more confusing than not), and this
includes Junio's queued squash.
I left the further clarification of "basis" and "header references"
mentioned in [1] be. I think the former refers to the "basis can be
specified" wording in 3/3, which isn't new, but in that regard mostly
moves existing documentation around.
This documentation can definitely be improved further, but given that
this is in v7 and we're changing smaller and smaller things I'd like
to not add anything new to it for now, and hopefully get it merged
down & then build on top of it for any further changes.
1. https://lore.kernel.org/git/697ca0f3-a897-a20b-48e4-bf439697afb5@iee.email/
Ævar Arnfjörð Bjarmason (3):
bundle doc: rewrite the "DESCRIPTION" section
bundle doc: elaborate on object prerequisites
bundle doc: elaborate on rev<->ref restriction
Documentation/git-bundle.txt | 140 ++++++++++++++++++++++++++++-------
1 file changed, 114 insertions(+), 26 deletions(-)
Range-diff against v6:
1: 3b447500da ! 1: b8f8a20e78 bundle doc: rewrite the "DESCRIPTION" section
@@ Documentation/git-bundle.txt: SYNOPSIS
+-------------
+
+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
-+header indicating what references are contained within the bundle. The
-+header is (mostly) in the format emitted by linkgit:git-show-ref[1].
++header indicating what references are contained within the bundle.
+
+Like the the packed archive format itself bundles can either be
+self-contained, or be created using exclusions.
2: 444b06740b ! 2: 5f344bd24a bundle doc: elaborate on object prerequisites
@@ Commit message
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Documentation/git-bundle.txt ##
-@@ Documentation/git-bundle.txt: header is (mostly) in the format emitted by linkgit:git-show-ref[1].
+@@ Documentation/git-bundle.txt: header indicating what references are contained within the bundle.
Like the the packed archive format itself bundles can either be
self-contained, or be created using exclusions.
@@ Documentation/git-bundle.txt: contained in the union of the given bases. Each b
+OBJECT PREREQUISITES
+--------------------
+
-+When creating bundles it is possible to create a fully self-contained
-+bundle with all the prerequisite objects, as well as providing
-+negative revisions to exclude prerequisite objects.
++When creating bundles it is possible to create a self-contained bundle
++that can be unbundled in a repository with no common history, as well
++as providing negative revisions to exclude objects needed in the
++earlier parts of the history.
+
-+A revision such as `new` will produce a tip with all the prerequisite
-+objects needed for the `new` reference.
++Feeding a revision such as `new` to `git bundle create` will create a
++bundle file that contains all the objects reachable from the revision
++`new`. That bundle can be unbundled in any repository to obtain a full
++history that leads to the revision `new`:
+
-+A revision range such as `old..new` will produce a bundle tip that'll
-+require any objects existing before `new` to already be present in the
-+repository performing the 'git bundle unbundle' operation.
++----------------
++$ git bundle create full.bundle new
++----------------
++
++A revision range such as `old..new` will produce a bundle file that
++will require the revision `old` (and any objects reachable from it)
++to exist for the bundle to be "unbundle"-able:
++
++----------------
++$ git bundle create full.bundle old..new
++----------------
+
+A self-contained bundle without any prerequisites can be extracted
+into anywhere, even into an empty repository, or be cloned from
3: 6d8f2f2708 = 3: 88e7ad1cf4 bundle doc: elaborate on rev<->ref restriction
--
2.32.0.988.g1a6a4b2c5f
^ permalink raw reply [flat|nested] 41+ messages in thread* [PATCH v7 1/3] bundle doc: rewrite the "DESCRIPTION" section
2021-07-27 0:24 ` [PATCH v7 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
@ 2021-07-27 0:24 ` Ævar Arnfjörð Bjarmason
2021-07-27 0:24 ` [PATCH v7 2/3] bundle doc: elaborate on object prerequisites Ævar Arnfjörð Bjarmason
` (2 subsequent siblings)
3 siblings, 0 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-27 0:24 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin, Philip Oakley,
Ævar Arnfjörð Bjarmason
Rewrite the "DESCRIPTION" section for "git bundle" to start by talking
about what bundles are in general terms, rather than diving directly
into one example of what they might be used for.
This changes documentation that's been substantially the same ever
since the command was added in 2e0afafebd8 (Add git-bundle: move
objects and references by archive, 2007-02-22).
I've split up the DESCRIPTION into that section and a "BUNDLE FORMAT"
section, it briefly discusses the format, but then links to the
technical/bundle-format.txt documentation.
The "the user must specify a basis" part of this is discussed below in
"SPECIFYING REFERENCES", and will be further elaborated on in a
subsequent commit. So I'm removing that part and letting the mention
of "revision exclusions" suffice.
There was a discussion about whether to say anything at all about
"thin packs" here[1]. I think it's good to mention it for the curious
reader willing to read the technical docs, but let's explicitly say
that there's no "thick pack", and that the difference shouldn't
matter.
1. http://lore.kernel.org/git/xmqqk0mbt5rj.fsf@gitster.g
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 56 ++++++++++++++++++++++++++----------
1 file changed, 41 insertions(+), 15 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b..339c5b4727 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -18,21 +18,47 @@ SYNOPSIS
DESCRIPTION
-----------
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
-
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
-
-As no
-direct connection between the repositories exists, the user must specify a
-basis for the bundle that is held by the destination repository: the
-bundle assumes that all objects in the basis are already in the
-destination repository.
+Create, unpack, and manipulate "bundle" files. Bundles are used for
+the "offline" transfer of Git objects without an active "server"
+sitting on the other side of the network connection.
+
+They can be used to create both incremental and full backups of a
+repository, and to relay the state of the references in one repository
+to another.
+
+Git commands that fetch or otherwise "read" via protocols such as
+`ssh://` and `https://` can also operate on bundle files. It is
+possible linkgit:git-clone[1] a new repository from a bundle, to use
+linkgit:git-fetch[1] to fetch from one, and to list the references
+contained within it with linkgit:git-ls-remote[1]. There's no
+corresponding "write" support, i.e.a 'git push' into a bundle is not
+supported.
+
+See the "EXAMPLES" section below for examples of how to use bundles.
+
+BUNDLE FORMAT
+-------------
+
+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
+header indicating what references are contained within the bundle.
+
+Like the the packed archive format itself bundles can either be
+self-contained, or be created using exclusions.
+
+Bundles created using revision exclusions are "thin packs" created
+using the `--thin` option to linkgit:git-pack-objects[1], and
+unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].
+
+There is no option to create a "thick pack" when using revision
+exclusions, users should not be concerned about the difference. By
+using "thin packs" bundles created using exclusions are smaller in
+size. That they're "thin" under the hood is merely noted here as a
+curiosity, and as a reference to other documentation
+
+See link:technical/bundle-format.html[the `bundle-format`
+documentation] for more details and the discussion of "thin pack" in
+link:technical/pack-format.html[the pack format documentation] for
+further details.
OPTIONS
-------
--
2.32.0.988.g1a6a4b2c5f
^ permalink raw reply related [flat|nested] 41+ messages in thread* [PATCH v7 2/3] bundle doc: elaborate on object prerequisites
2021-07-27 0:24 ` [PATCH v7 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-07-27 0:24 ` [PATCH v7 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
@ 2021-07-27 0:24 ` Ævar Arnfjörð Bjarmason
2021-07-27 0:24 ` [PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
2021-07-31 8:23 ` [PATCH v8 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
3 siblings, 0 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-27 0:24 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin, Philip Oakley,
Ævar Arnfjörð Bjarmason
Split out the discussion bout "object prerequisites" into its own
section, and add some more examples of the common cases.
See 2e0afafebd (Add git-bundle: move objects and references by
archive, 2007-02-22) for the introduction of the documentation being
changed here.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 37 +++++++++++++++++++++++++++++++++---
1 file changed, 34 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 339c5b4727..f1f84ce2c4 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -44,6 +44,7 @@ header indicating what references are contained within the bundle.
Like the the packed archive format itself bundles can either be
self-contained, or be created using exclusions.
+See the "OBJECT PREREQUISITES" section below.
Bundles created using revision exclusions are "thin packs" created
using the `--thin` option to linkgit:git-pack-objects[1], and
@@ -152,19 +153,49 @@ contained in the union of the given bases. Each basis can be
specified explicitly (e.g. `^master~10`), or implicitly (e.g.
`master~10..master`, `--since=10.days.ago master`).
-It is very important that the basis used be held by the destination.
+OBJECT PREREQUISITES
+--------------------
+
+When creating bundles it is possible to create a self-contained bundle
+that can be unbundled in a repository with no common history, as well
+as providing negative revisions to exclude objects needed in the
+earlier parts of the history.
+
+Feeding a revision such as `new` to `git bundle create` will create a
+bundle file that contains all the objects reachable from the revision
+`new`. That bundle can be unbundled in any repository to obtain a full
+history that leads to the revision `new`:
+
+----------------
+$ git bundle create full.bundle new
+----------------
+
+A revision range such as `old..new` will produce a bundle file that
+will require the revision `old` (and any objects reachable from it)
+to exist for the bundle to be "unbundle"-able:
+
+----------------
+$ git bundle create full.bundle old..new
+----------------
+
+A self-contained bundle without any prerequisites can be extracted
+into anywhere, even into an empty repository, or be cloned from
+(i.e., `new`, but not `old..new`).
+
It is okay to err on the side of caution, causing the bundle file
to contain objects already in the destination, as these are ignored
when unpacking at the destination.
-`git clone` can use any bundle created without negative refspecs
-(e.g., `new`, but not `old..new`).
If you want to match `git clone --mirror`, which would include your
refs such as `refs/remotes/*`, use `--all`.
If you want to provide the same set of refs that a clone directly
from the source repository would get, use `--branches --tags` for
the `<git-rev-list-args>`.
+The 'git bundle verify' command can be used to check whether your
+recipient repository has the required prerequisite commits for a
+bundle.
+
EXAMPLES
--------
--
2.32.0.988.g1a6a4b2c5f
^ permalink raw reply related [flat|nested] 41+ messages in thread
* [PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction
2021-07-27 0:24 ` [PATCH v7 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-07-27 0:24 ` [PATCH v7 1/3] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
2021-07-27 0:24 ` [PATCH v7 2/3] bundle doc: elaborate on object prerequisites Ævar Arnfjörð Bjarmason
@ 2021-07-27 0:24 ` Ævar Arnfjörð Bjarmason
2021-07-28 15:17 ` Philip Oakley
2021-07-28 18:05 ` Junio C Hamano
2021-07-31 8:23 ` [PATCH v8 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
3 siblings, 2 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-27 0:24 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin, Philip Oakley,
Ævar Arnfjörð Bjarmason
Elaborate on the restriction that you cannot provide a revision that
doesn't resolve to a reference in the "SPECIFYING REFERENCES" section
with examples.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------
1 file changed, 39 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index f1f84ce2c4..0f28c41409 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -144,14 +144,45 @@ unbundle <file>::
SPECIFYING REFERENCES
---------------------
-'git bundle' will only package references that are shown by
-'git show-ref': this includes heads, tags, and remote heads. References
-such as `master~1` cannot be packaged, but are perfectly suitable for
-defining the basis. More than one reference may be packaged, and more
-than one basis can be specified. The objects packaged are those not
-contained in the union of the given bases. Each basis can be
-specified explicitly (e.g. `^master~10`), or implicitly (e.g.
-`master~10..master`, `--since=10.days.ago master`).
+Revisions must accompanied by reference names to be packaged in a
+bundle, since the header of the bundle is in a format similar to 'git
+show-ref'.
+
+More than one reference may be packaged, and more than one basis can
+be specified. The objects packaged are those not contained in the
+union of the given bases.
+
+The 'git bundle create' command resolves the reference names for you
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
+basis can be specified explicitly (e.g. `^master~10`), or implicitly
+(e.g. `master~10..master`, `--since=10.days.ago master`).
+
+All of these simple cases are OK (assuming we have a "master" and
+"next" branch):
+
+----------------
+$ git bundle create master.bundle master
+$ echo master | git bundle create master.bundle --stdin
+$ git bundle create master-and-next.bundle master next
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
+----------------
+
+And so are these (and the same but omitted `--stdin` examples):
+
+----------------
+$ git bundle create recent-master.bundle master~10..master
+$ git bundle create recent-updates.bundle master~10..master next~5..next
+----------------
+
+A revision name or a range whose right-hand-side cannot be resolved to
+a reference is not accepted:
+
+----------------
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.
+----------------
OBJECT PREREQUISITES
--------------------
--
2.32.0.988.g1a6a4b2c5f
^ permalink raw reply related [flat|nested] 41+ messages in thread
* Re: [PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction
2021-07-27 0:24 ` [PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
@ 2021-07-28 15:17 ` Philip Oakley
2021-07-28 18:05 ` Junio C Hamano
1 sibling, 0 replies; 41+ messages in thread
From: Philip Oakley @ 2021-07-28 15:17 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason, git
Cc: Junio C Hamano, Johannes Schindelin
On 27/07/2021 01:24, Ævar Arnfjörð Bjarmason wrote:
> Elaborate on the restriction that you cannot provide a revision that
> doesn't resolve to a reference in the "SPECIFYING REFERENCES" section
> with examples.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> Documentation/git-bundle.txt | 47 ++++++++++++++++++++++++++++++------
> 1 file changed, 39 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
> index f1f84ce2c4..0f28c41409 100644
> --- a/Documentation/git-bundle.txt
> +++ b/Documentation/git-bundle.txt
> @@ -144,14 +144,45 @@ unbundle <file>::
> SPECIFYING REFERENCES
> ---------------------
>
> -'git bundle' will only package references that are shown by
> -'git show-ref': this includes heads, tags, and remote heads. References
> -such as `master~1` cannot be packaged, but are perfectly suitable for
> -defining the basis. More than one reference may be packaged, and more
> -than one basis can be specified. The objects packaged are those not
> -contained in the union of the given bases. Each basis can be
> -specified explicitly (e.g. `^master~10`), or implicitly (e.g.
> -`master~10..master`, `--since=10.days.ago master`).
> +Revisions must accompanied by reference names to be packaged in a
> +bundle, since the header of the bundle is in a format similar to 'git
> +show-ref'.
> +
> +More than one reference may be packaged, and more than one basis can
> +be specified. The objects packaged are those not contained in the
> +union of the given bases.
> +
> +The 'git bundle create' command resolves the reference names for you
> +using the same rules as `git rev-parse --abbrev-ref=loose`. Each
> +basis can be specified explicitly (e.g. `^master~10`), or implicitly
> +(e.g. `master~10..master`, `--since=10.days.ago master`).
> +
> +All of these simple cases are OK (assuming we have a "master" and
> +"next" branch):
> +
> +----------------
> +$ git bundle create master.bundle master
> +$ echo master | git bundle create master.bundle --stdin
> +$ git bundle create master-and-next.bundle master next
> +$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
> +----------------
> +
> +And so are these (and the same but omitted `--stdin` examples):
> +
> +----------------
> +$ git bundle create recent-master.bundle master~10..master
> +$ git bundle create recent-updates.bundle master~10..master next~5..next
> +----------------
> +
> +A revision name or a range whose right-hand-side cannot be resolved to
> +a reference is not accepted:
> +
> +----------------
> +$ git bundle create HEAD.bundle $(git rev-parse HEAD)
> +fatal: Refusing to create empty bundle.
> +$ git bundle create master-yesterday.bundle master~10..master~5
> +fatal: Refusing to create empty bundle.
I like this example showing the need for a reference name to be part of
the basis, clarifying that part of the description.
Philip
> +----------------
>
> OBJECT PREREQUISITES
> --------------------
^ permalink raw reply [flat|nested] 41+ messages in thread
* Re: [PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction
2021-07-27 0:24 ` [PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
2021-07-28 15:17 ` Philip Oakley
@ 2021-07-28 18:05 ` Junio C Hamano
1 sibling, 0 replies; 41+ messages in thread
From: Junio C Hamano @ 2021-07-28 18:05 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason
Cc: git, Johannes Schindelin, Philip Oakley
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> +Revisions must accompanied by reference names to be packaged in a
> +bundle, since the header of the bundle is in a format similar to 'git
> +show-ref'.
As I already said in the review of v6, I do not think "header has a
format similar to show-ref" is not something we need to say so
prominently to the user.
The reason we should give readers why they must give refs while
creating a bundle, I think, is because the only way to access the
contents of the bundle is to fetch refs from it, and the refs given
to the command when the bundle was created becomes the refs that can
be fetched from the bundle.
And that is what the readers should be told here, I think.
> +More than one reference may be packaged, and more than one basis can
> +be specified. The objects packaged are those not contained in the
> +union of the given bases.
> +
> +The 'git bundle create' command resolves the reference names for you
> +using the same rules as `git rev-parse --abbrev-ref=loose`. Each
> +basis can be specified explicitly (e.g. `^master~10`), or implicitly
> +(e.g. `master~10..master`, `--since=10.days.ago master`).
Also, we introduced "prerequisite objects" in the previous step, but
here we say "basis". The readers would be helped greatly if we were
a bit more consistent.
> ...
> +A revision name or a range whose right-hand-side cannot be resolved to
> +a reference is not accepted:
> +
> +----------------
> +$ git bundle create HEAD.bundle $(git rev-parse HEAD)
> +fatal: Refusing to create empty bundle.
> +$ git bundle create master-yesterday.bundle master~10..master~5
> +fatal: Refusing to create empty bundle.
> +----------------
This is a good example, as Philip already said.
Thanks.
^ permalink raw reply [flat|nested] 41+ messages in thread
* [PATCH v8 0/3] bundle doc: generalize & elaborate
2021-07-27 0:24 ` [PATCH v7 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
` (2 preceding siblings ...)
2021-07-27 0:24 ` [PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
@ 2021-07-31 8:23 ` Ævar Arnfjörð Bjarmason
2021-07-31 8:23 ` [PATCH v8 1/4] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
` (3 more replies)
3 siblings, 4 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-31 8:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin, Philip Oakley,
Ævar Arnfjörð Bjarmason
As mentioned in v7 I got rid of the comparisons of the bundle header
to the format of show-ref:
https://lore.kernel.org/git/cover-0.3-0000000000-20210727T002001Z-avarab@gmail.com
Except I managed to miss that it was in two places in the series,
sorry. Here's an update with what I meant to send in v7.
Junio also mentioned it being confusing that we mix "basis" and
"object prerequisites", I agree, but wanted to keep these changes
minimal, so I wasn't rewording the existing occurances of "basis".
This now has a minimal patch-on-top which follows up and rewords those
existing and moved-around occurrences of "basis" to "[commit|object]
prerequisite(s)".
1. https://lore.kernel.org/git/xmqqa6m69uvh.fsf@gitster.g/#t
Ævar Arnfjörð Bjarmason (4):
bundle doc: rewrite the "DESCRIPTION" section
bundle doc: elaborate on object prerequisites
bundle doc: elaborate on rev<->ref restriction
bundle doc: replace "basis" with "prerequsite(s)"
Documentation/git-bundle.txt | 147 ++++++++++++++++++++++++++++-------
1 file changed, 117 insertions(+), 30 deletions(-)
Range-diff against v7:
1: b8f8a20e789 = 1: b8f8a20e789 bundle doc: rewrite the "DESCRIPTION" section
2: 5f344bd24aa = 2: 5f344bd24aa bundle doc: elaborate on object prerequisites
3: 88e7ad1cf49 ! 3: 0e702337c7f bundle doc: elaborate on rev<->ref restriction
@@ Documentation/git-bundle.txt: unbundle <file>::
-specified explicitly (e.g. `^master~10`), or implicitly (e.g.
-`master~10..master`, `--since=10.days.ago master`).
+Revisions must accompanied by reference names to be packaged in a
-+bundle, since the header of the bundle is in a format similar to 'git
-+show-ref'.
++bundle.
+
+More than one reference may be packaged, and more than one basis can
+be specified. The objects packaged are those not contained in the
-: ----------- > 4: 1f3dcd42863 bundle doc: replace "basis" with "prerequsite(s)"
--
2.32.0.1069.g545f0888808
^ permalink raw reply [flat|nested] 41+ messages in thread* [PATCH v8 1/4] bundle doc: rewrite the "DESCRIPTION" section
2021-07-31 8:23 ` [PATCH v8 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
@ 2021-07-31 8:23 ` Ævar Arnfjörð Bjarmason
2021-07-31 8:23 ` [PATCH v8 2/4] bundle doc: elaborate on object prerequisites Ævar Arnfjörð Bjarmason
` (2 subsequent siblings)
3 siblings, 0 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-31 8:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin, Philip Oakley,
Ævar Arnfjörð Bjarmason
Rewrite the "DESCRIPTION" section for "git bundle" to start by talking
about what bundles are in general terms, rather than diving directly
into one example of what they might be used for.
This changes documentation that's been substantially the same ever
since the command was added in 2e0afafebd8 (Add git-bundle: move
objects and references by archive, 2007-02-22).
I've split up the DESCRIPTION into that section and a "BUNDLE FORMAT"
section, it briefly discusses the format, but then links to the
technical/bundle-format.txt documentation.
The "the user must specify a basis" part of this is discussed below in
"SPECIFYING REFERENCES", and will be further elaborated on in a
subsequent commit. So I'm removing that part and letting the mention
of "revision exclusions" suffice.
There was a discussion about whether to say anything at all about
"thin packs" here[1]. I think it's good to mention it for the curious
reader willing to read the technical docs, but let's explicitly say
that there's no "thick pack", and that the difference shouldn't
matter.
1. http://lore.kernel.org/git/xmqqk0mbt5rj.fsf@gitster.g
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 56 ++++++++++++++++++++++++++----------
1 file changed, 41 insertions(+), 15 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b6..339c5b47276 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -18,21 +18,47 @@ SYNOPSIS
DESCRIPTION
-----------
-Some workflows require that one or more branches of development on one
-machine be replicated on another machine, but the two machines cannot
-be directly connected, and therefore the interactive Git protocols (git,
-ssh, http) cannot be used.
-
-The 'git bundle' command packages objects and references in an archive
-at the originating machine, which can then be imported into another
-repository using 'git fetch', 'git pull', or 'git clone',
-after moving the archive by some means (e.g., by sneakernet).
-
-As no
-direct connection between the repositories exists, the user must specify a
-basis for the bundle that is held by the destination repository: the
-bundle assumes that all objects in the basis are already in the
-destination repository.
+Create, unpack, and manipulate "bundle" files. Bundles are used for
+the "offline" transfer of Git objects without an active "server"
+sitting on the other side of the network connection.
+
+They can be used to create both incremental and full backups of a
+repository, and to relay the state of the references in one repository
+to another.
+
+Git commands that fetch or otherwise "read" via protocols such as
+`ssh://` and `https://` can also operate on bundle files. It is
+possible linkgit:git-clone[1] a new repository from a bundle, to use
+linkgit:git-fetch[1] to fetch from one, and to list the references
+contained within it with linkgit:git-ls-remote[1]. There's no
+corresponding "write" support, i.e.a 'git push' into a bundle is not
+supported.
+
+See the "EXAMPLES" section below for examples of how to use bundles.
+
+BUNDLE FORMAT
+-------------
+
+Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a
+header indicating what references are contained within the bundle.
+
+Like the the packed archive format itself bundles can either be
+self-contained, or be created using exclusions.
+
+Bundles created using revision exclusions are "thin packs" created
+using the `--thin` option to linkgit:git-pack-objects[1], and
+unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].
+
+There is no option to create a "thick pack" when using revision
+exclusions, users should not be concerned about the difference. By
+using "thin packs" bundles created using exclusions are smaller in
+size. That they're "thin" under the hood is merely noted here as a
+curiosity, and as a reference to other documentation
+
+See link:technical/bundle-format.html[the `bundle-format`
+documentation] for more details and the discussion of "thin pack" in
+link:technical/pack-format.html[the pack format documentation] for
+further details.
OPTIONS
-------
--
2.32.0.1069.g545f0888808
^ permalink raw reply related [flat|nested] 41+ messages in thread* [PATCH v8 2/4] bundle doc: elaborate on object prerequisites
2021-07-31 8:23 ` [PATCH v8 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-07-31 8:23 ` [PATCH v8 1/4] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
@ 2021-07-31 8:23 ` Ævar Arnfjörð Bjarmason
2021-07-31 8:23 ` [PATCH v8 3/4] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
2021-07-31 8:23 ` [PATCH v8 4/4] bundle doc: replace "basis" with "prerequsite(s)" Ævar Arnfjörð Bjarmason
3 siblings, 0 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-31 8:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin, Philip Oakley,
Ævar Arnfjörð Bjarmason
Split out the discussion bout "object prerequisites" into its own
section, and add some more examples of the common cases.
See 2e0afafebd (Add git-bundle: move objects and references by
archive, 2007-02-22) for the introduction of the documentation being
changed here.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 37 +++++++++++++++++++++++++++++++++---
1 file changed, 34 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 339c5b47276..f1f84ce2c42 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -44,6 +44,7 @@ header indicating what references are contained within the bundle.
Like the the packed archive format itself bundles can either be
self-contained, or be created using exclusions.
+See the "OBJECT PREREQUISITES" section below.
Bundles created using revision exclusions are "thin packs" created
using the `--thin` option to linkgit:git-pack-objects[1], and
@@ -152,19 +153,49 @@ contained in the union of the given bases. Each basis can be
specified explicitly (e.g. `^master~10`), or implicitly (e.g.
`master~10..master`, `--since=10.days.ago master`).
-It is very important that the basis used be held by the destination.
+OBJECT PREREQUISITES
+--------------------
+
+When creating bundles it is possible to create a self-contained bundle
+that can be unbundled in a repository with no common history, as well
+as providing negative revisions to exclude objects needed in the
+earlier parts of the history.
+
+Feeding a revision such as `new` to `git bundle create` will create a
+bundle file that contains all the objects reachable from the revision
+`new`. That bundle can be unbundled in any repository to obtain a full
+history that leads to the revision `new`:
+
+----------------
+$ git bundle create full.bundle new
+----------------
+
+A revision range such as `old..new` will produce a bundle file that
+will require the revision `old` (and any objects reachable from it)
+to exist for the bundle to be "unbundle"-able:
+
+----------------
+$ git bundle create full.bundle old..new
+----------------
+
+A self-contained bundle without any prerequisites can be extracted
+into anywhere, even into an empty repository, or be cloned from
+(i.e., `new`, but not `old..new`).
+
It is okay to err on the side of caution, causing the bundle file
to contain objects already in the destination, as these are ignored
when unpacking at the destination.
-`git clone` can use any bundle created without negative refspecs
-(e.g., `new`, but not `old..new`).
If you want to match `git clone --mirror`, which would include your
refs such as `refs/remotes/*`, use `--all`.
If you want to provide the same set of refs that a clone directly
from the source repository would get, use `--branches --tags` for
the `<git-rev-list-args>`.
+The 'git bundle verify' command can be used to check whether your
+recipient repository has the required prerequisite commits for a
+bundle.
+
EXAMPLES
--------
--
2.32.0.1069.g545f0888808
^ permalink raw reply related [flat|nested] 41+ messages in thread
* [PATCH v8 3/4] bundle doc: elaborate on rev<->ref restriction
2021-07-31 8:23 ` [PATCH v8 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
2021-07-31 8:23 ` [PATCH v8 1/4] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
2021-07-31 8:23 ` [PATCH v8 2/4] bundle doc: elaborate on object prerequisites Ævar Arnfjörð Bjarmason
@ 2021-07-31 8:23 ` Ævar Arnfjörð Bjarmason
2021-07-31 8:23 ` [PATCH v8 4/4] bundle doc: replace "basis" with "prerequsite(s)" Ævar Arnfjörð Bjarmason
3 siblings, 0 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-31 8:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin, Philip Oakley,
Ævar Arnfjörð Bjarmason
Elaborate on the restriction that you cannot provide a revision that
doesn't resolve to a reference in the "SPECIFYING REFERENCES" section
with examples.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 46 +++++++++++++++++++++++++++++-------
1 file changed, 38 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index f1f84ce2c42..f36939ab014 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -144,14 +144,44 @@ unbundle <file>::
SPECIFYING REFERENCES
---------------------
-'git bundle' will only package references that are shown by
-'git show-ref': this includes heads, tags, and remote heads. References
-such as `master~1` cannot be packaged, but are perfectly suitable for
-defining the basis. More than one reference may be packaged, and more
-than one basis can be specified. The objects packaged are those not
-contained in the union of the given bases. Each basis can be
-specified explicitly (e.g. `^master~10`), or implicitly (e.g.
-`master~10..master`, `--since=10.days.ago master`).
+Revisions must accompanied by reference names to be packaged in a
+bundle.
+
+More than one reference may be packaged, and more than one basis can
+be specified. The objects packaged are those not contained in the
+union of the given bases.
+
+The 'git bundle create' command resolves the reference names for you
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
+basis can be specified explicitly (e.g. `^master~10`), or implicitly
+(e.g. `master~10..master`, `--since=10.days.ago master`).
+
+All of these simple cases are OK (assuming we have a "master" and
+"next" branch):
+
+----------------
+$ git bundle create master.bundle master
+$ echo master | git bundle create master.bundle --stdin
+$ git bundle create master-and-next.bundle master next
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
+----------------
+
+And so are these (and the same but omitted `--stdin` examples):
+
+----------------
+$ git bundle create recent-master.bundle master~10..master
+$ git bundle create recent-updates.bundle master~10..master next~5..next
+----------------
+
+A revision name or a range whose right-hand-side cannot be resolved to
+a reference is not accepted:
+
+----------------
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.
+----------------
OBJECT PREREQUISITES
--------------------
--
2.32.0.1069.g545f0888808
^ permalink raw reply related [flat|nested] 41+ messages in thread
* [PATCH v8 4/4] bundle doc: replace "basis" with "prerequsite(s)"
2021-07-31 8:23 ` [PATCH v8 0/3] bundle doc: generalize & elaborate Ævar Arnfjörð Bjarmason
` (2 preceding siblings ...)
2021-07-31 8:23 ` [PATCH v8 3/4] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
@ 2021-07-31 8:23 ` Ævar Arnfjörð Bjarmason
3 siblings, 0 replies; 41+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2021-07-31 8:23 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Johannes Schindelin, Philip Oakley,
Ævar Arnfjörð Bjarmason
In the preceding commits we introduced new documentation that talks
about "[commit|object] prerequsite(s)", but also faithfully moved
around existing documentation that talks about the "basis".
Let's change both that moved-around documentation and other existing
documentation in the file to consistently use "[commit|object]"
prerequisite(s)" instead of talking about "basis". The mention of
"basis" isn't wrong, but readers will be helped by us using only one
term throughout the document for this concept.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-bundle.txt | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index f36939ab014..ac0d0038350 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -147,13 +147,13 @@ SPECIFYING REFERENCES
Revisions must accompanied by reference names to be packaged in a
bundle.
-More than one reference may be packaged, and more than one basis can
+More than one reference may be packaged, and more than one set of prerequisite objects can
be specified. The objects packaged are those not contained in the
-union of the given bases.
+union of the prerequisites.
The 'git bundle create' command resolves the reference names for you
using the same rules as `git rev-parse --abbrev-ref=loose`. Each
-basis can be specified explicitly (e.g. `^master~10`), or implicitly
+prerequisite can be specified explicitly (e.g. `^master~10`), or implicitly
(e.g. `master~10..master`, `--since=10.days.ago master`).
All of these simple cases are OK (assuming we have a "master" and
@@ -236,7 +236,7 @@ but we can move data from A to B via some mechanism (CD, email, etc.).
We want to update R2 with development made on the branch master in R1.
To bootstrap the process, you can first create a bundle that does not have
-any basis. You can use a tag to remember up to what commit you last
+any prerequisites. You can use a tag to remember up to what commit you last
processed, in order to make it easy to later update the other repository
with an incremental bundle:
@@ -287,7 +287,7 @@ machineB$ git pull
If you know up to what commit the intended recipient repository should
have the necessary objects, you can use that knowledge to specify the
-basis, giving a cut-off point to limit the revisions and objects that go
+prerequisites, giving a cut-off point to limit the revisions and objects that go
in the resulting bundle. The previous example used the lastR2bundle tag
for this purpose, but you can use any other options that you would give to
the linkgit:git-log[1] command. Here are more examples:
@@ -298,7 +298,7 @@ You can use a tag that is present in both:
$ git bundle create mybundle v1.0.0..master
----------------
-You can use a basis based on time:
+You can use a prerequisite based on time:
----------------
$ git bundle create mybundle --since=10.days master
@@ -311,7 +311,7 @@ $ git bundle create mybundle -10 master
----------------
You can run `git-bundle verify` to see if you can extract from a bundle
-that was created with a basis:
+that was created with a prerequisite:
----------------
$ git bundle verify mybundle
--
2.32.0.1069.g545f0888808
^ permalink raw reply related [flat|nested] 41+ messages in thread