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).
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx>
---
I didn't think I needed to type "make" to check a doc-only change, but
as it turns out v1 of this doesn't compile git because the script to
generate command-list.h doesn't know how to escape the quotes in the
C-string it generates.
This is probably better in either case, sorry about the noise.
Range-diff against v1:
1: 4e736877d1 ! 1: bc6a6d8922 bundle doc: rewrite the "DESCRIPTION" section
@@ Documentation/git-bundle.txt: git-bundle(1)
NAME
----
-git-bundle - Move objects and refs by archive
-+git-bundle - Create, unpack and manipulate "bundles"
++git-bundle - Create, unpack and manipulate bundles
SYNOPSIS
Documentation/git-bundle.txt | 31 ++++++++++++++++++++++---------
1 file changed, 22 insertions(+), 9 deletions(-)
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b..cdc4e0b51b 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -3,7 +3,7 @@ git-bundle(1)
NAME
----
-git-bundle - Move objects and refs by archive
+git-bundle - Create, unpack and manipulate bundles
SYNOPSIS
@@ -18,15 +18,25 @@ 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.
+Create, unpack and manipulate "bundles" (.bundle) files. Bundles are
+.pack files (see linkgit:git-pack-objects[1]) with a header indicating
+what references are contained within the bundle. The header is in the
+format emitted by linkgit:git-show-ref[1].
-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).
+Like the the packed archive format itself bundles can either be
+self-contained or thin (see "--thin" in linkgit:git-pack-objects[1]).
+
+Bundles are useful for numerous purposes. They were originally
+designed to facilitate the transfer of repository data between
+repositories which could not be directly connect to each other, and
+therefore the interactive Git protocols (git, ssh, http) could not be
+used.
+
+In that scenario a bundle is produced on the originating machine. It
+is then transferred to the other machine (e.g. by sneakernet), and
+unpacked on the other end. The unpacking can happen either with
+linkgit:git-clone[1] (which knows how to clone from bundle files), or
+by "git bundle unbundle".
As no
direct connection between the repositories exists, the user must specify a
@@ -34,6 +44,9 @@ 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.
+Similarly, bundles are commonly used to produce incremental backups of
+git repositories. See the "EXAMPLES" section below.
+
OPTIONS
-------
--
2.32.0.rc3.434.gd8aed1f08a7
