bundle doc: elaborate on rev<->ref restriction
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Jul 31, 2021 at 10:23 UTC
0bb92f3a3a0034247868b4fcd901c18654b76c4d
1 file changed
+38
-8
Documentation/git-bundle.txt
+38
-8
@@ -144,14 +144,44 @@ unbundle <file>::
144
SPECIFYING REFERENCES
145
---------------------
146
147
-'git bundle' will only package references that are shown by
148
-'git show-ref': this includes heads, tags, and remote heads. References
149
-such as `master~1` cannot be packaged, but are perfectly suitable for
150
-defining the basis. More than one reference may be packaged, and more
151
-than one basis can be specified. The objects packaged are those not
152
-contained in the union of the given bases. Each basis can be
153
-specified explicitly (e.g. `^master~10`), or implicitly (e.g.
154
-`master~10..master`, `--since=10.days.ago master`).
147
+Revisions must accompanied by reference names to be packaged in a
148
+bundle.
149
+
150
+More than one reference may be packaged, and more than one basis can
151
+be specified. The objects packaged are those not contained in the
152
+union of the given bases.
153
+
154
+The 'git bundle create' command resolves the reference names for you
155
+using the same rules as `git rev-parse --abbrev-ref=loose`. Each
156
+basis can be specified explicitly (e.g. `^master~10`), or implicitly
157
+(e.g. `master~10..master`, `--since=10.days.ago master`).
158
+
159
+All of these simple cases are OK (assuming we have a "master" and
160
+"next" branch):
161
+
162
+----------------
163
+$ git bundle create master.bundle master
164
+$ echo master | git bundle create master.bundle --stdin
165
+$ git bundle create master-and-next.bundle master next
166
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
167
+----------------
168
+
169
+And so are these (and the same but omitted `--stdin` examples):
170
+
171
+----------------
172
+$ git bundle create recent-master.bundle master~10..master
173
+$ git bundle create recent-updates.bundle master~10..master next~5..next
174
+----------------
175
+
176
+A revision name or a range whose right-hand-side cannot be resolved to
177
+a reference is not accepted:
178
+
179
+----------------
180
+$ git bundle create HEAD.bundle $(git rev-parse HEAD)
181
+fatal: Refusing to create empty bundle.
182
+$ git bundle create master-yesterday.bundle master~10..master~5
183
+fatal: Refusing to create empty bundle.
184
+----------------
185
186
OBJECT PREREQUISITES
187
--------------------