git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: git@vger.kernel.org
Cc: "Junio C Hamano" <gitster@pobox.com>,
	"Johannes Schindelin" <Johannes.Schindelin@gmx.de>,
	"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Subject: [PATCH v3 1/3] bundle doc: rewrite the "DESCRIPTION" section
Date: Thu, 24 Jun 2021 21:40:26 +0200	[thread overview]
Message-ID: <patch-1.3-2824133f423-20210624T193730Z-avarab@gmail.com> (raw)
In-Reply-To: <cover-0.3-00000000000-20210624T193730Z-avarab@gmail.com>

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 | 43 +++++++++++++++++++++++-------------
 1 file changed, 28 insertions(+), 15 deletions(-)

diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 53804cad4b6..1b02f8b7468 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -18,21 +18,34 @@ 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.
+
+Other git commands that understand 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].
+
+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.610.gd639e370050


  reply	other threads:[~2021-06-24 19:40 UTC|newest]

Thread overview: 41+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-06-07 14:37 [PATCH] bundle doc: rewrite the "DESCRIPTION" section Ævar Arnfjörð Bjarmason
2021-06-07 16:56 ` [PATCH v2] " Ævar Arnfjörð Bjarmason
2021-06-07 23:35   ` Junio C Hamano
2021-06-24 19:40   ` [PATCH v3 0/3] bundle doc: generaliz & elaborate Ævar Arnfjörð Bjarmason
2021-06-24 19:40     ` Ævar Arnfjörð Bjarmason [this message]
2021-06-29  4:52       ` [PATCH v3 1/3] bundle doc: rewrite the "DESCRIPTION" section Junio C Hamano
2021-06-24 19:40     ` [PATCH v3 2/3] bundle doc: split out thin v.s. not discussion from <rev-arg> Ævar Arnfjörð Bjarmason
2021-06-29  4:52       ` Junio C Hamano
2021-06-24 19:40     ` [PATCH v3 3/3] bundle doc: elaborate on rev<->ref restriction Ævar Arnfjörð Bjarmason
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 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
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 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
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 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
2021-07-20 20:19             ` Junio C Hamano
2021-07-21  9:27               ` Philip Oakley
2021-07-21 16:57                 ` Junio C Hamano
2021-07-22 11:37                   ` Philip Oakley
2021-07-22 11:46                     ` Ævar Arnfjörð Bjarmason
2021-07-22 23:14                       ` Philip Oakley
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           ` [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
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             ` [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

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=patch-1.3-2824133f423-20210624T193730Z-avarab@gmail.com \
    --to=avarab@gmail.com \
    --cc=Johannes.Schindelin@gmx.de \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).