From patchwork Fri Jul 2 11:26:53 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= X-Patchwork-Id: 12355983 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id D7137C11F69 for ; Fri, 2 Jul 2021 11:27:01 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id B72BE613F7 for ; Fri, 2 Jul 2021 11:27:01 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231768AbhGBL3c (ORCPT ); Fri, 2 Jul 2021 07:29:32 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:57306 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231437AbhGBL3b (ORCPT ); Fri, 2 Jul 2021 07:29:31 -0400 Received: from mail-wr1-x42d.google.com (mail-wr1-x42d.google.com [IPv6:2a00:1450:4864:20::42d]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C8D81C061764 for ; Fri, 2 Jul 2021 04:26:59 -0700 (PDT) Received: by mail-wr1-x42d.google.com with SMTP id m18so12074633wrv.2 for ; Fri, 02 Jul 2021 04:26:59 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=ggvapYuLHD1KBfGLJtYEaUR+mZsg0TYQpQAIl5LPCvw=; b=dLbqtwbe0LadmHIvvRel238+UJ4npIALs6NcpX1S4hdZduY6nffVS6iG6sHWeqUHAZ crWheNZcaeGaT/f+E9xjjXJvGzmkuBbfyRqTlGtlPqG5Jqp2HYCJIgpM432cFyAbV3dq waA57YzWDrIZbyIHRN8AgjHa4qGSbHTnOp8fRoKR09OJrRFeGOwnWPZ4uExilyQd+t06 hvlH0Z8GkmAoNKBffQw3yYHsz/ssQfJfEigxGPjUu8xvzUe0yL55OpLkpmiGIpKMzxld C/4KbujBlavz8bQkTb4xRSEPgTxrnplKHHT5kFe3EzzEQ1Y5zTmuLnUnokms0xjWK+RR nNrg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=ggvapYuLHD1KBfGLJtYEaUR+mZsg0TYQpQAIl5LPCvw=; b=kuNop8hvBPqnpXbF9wOIeaQwm52+nPQPcmn8m7b5G/eYzgQJxX9n2PwQMf1JktMoMN IqkBeR6Zd17mGmIUtBbtN9ngW0cCP6XlHfoASD3M61MkhgrSaU+0oa9LA1J4Kg6J4sJy yVkW5uHW+oke0oIgvZ7tmUnMH+bKrK+xhaT0UKLN5BFF0710JpeJGrzome3tW0pA0Uyv HVME4wKfjFawUBnsWB2ufZRoDkQeJ7a4W7k/D50b/cI48WvCtGZQouwemb2VOZHI7Y9n Z326lS/Bwonl5X4TeCOKigFOq8Mu6u6+y4engpXISwefLfgs3s3j+BKn8MHo2e8YbbGj eLBg== X-Gm-Message-State: AOAM531RjcaI6b0CCsZ7s2DbuNTuOxEHtkfzW7heQBZ9Q1OHA/6LW/lH ZGaaP1Wdhvt4WEFz7FC2qpnfgZ9qKrCS5A== X-Google-Smtp-Source: ABdhPJx8fF+S0NY99SUevngK7uf/WUavy76YvI52k3NKu42gEBidY/FRCwMZKD81qadR9wKiDULaWA== X-Received: by 2002:adf:fac6:: with SMTP id a6mr5377323wrs.345.1625225218100; Fri, 02 Jul 2021 04:26:58 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id m18sm2763887wmq.45.2021.07.02.04.26.57 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 02 Jul 2021 04:26:57 -0700 (PDT) From: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= To: git@vger.kernel.org Cc: Junio C Hamano , Johannes Schindelin , =?utf-8?b?w4Z2YXIgQXJu?= =?utf-8?b?ZmrDtnLDsCBCamFybWFzb24=?= Subject: [PATCH v5 1/3] bundle doc: rewrite the "DESCRIPTION" section Date: Fri, 2 Jul 2021 13:26:53 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.632.g49a94b9226d In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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 --- 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 ------- From patchwork Fri Jul 2 11:26:54 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= X-Patchwork-Id: 12355987 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6A1B0C11F69 for ; Fri, 2 Jul 2021 11:27:04 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 4FF6C613F7 for ; Fri, 2 Jul 2021 11:27:04 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231810AbhGBL3e (ORCPT ); Fri, 2 Jul 2021 07:29:34 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:57312 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231742AbhGBL3c (ORCPT ); Fri, 2 Jul 2021 07:29:32 -0400 Received: from mail-wr1-x435.google.com (mail-wr1-x435.google.com [IPv6:2a00:1450:4864:20::435]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 78D7AC061762 for ; Fri, 2 Jul 2021 04:27:00 -0700 (PDT) Received: by mail-wr1-x435.google.com with SMTP id f14so11684244wrs.6 for ; Fri, 02 Jul 2021 04:27:00 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=u+Q5Gg6LZo0fCDNyjw9HcVHVwre0dDJifCku9AuMwUM=; b=DFfRVLi5YFrcmejy+wOyUdvbVVDpVfTUvg2cxVqxrYrn1KGFv+CV2UzunSM6RxyPs3 el9jWjDY5QvBepKn952zQ46jqu49vpOcLG/BNpo0C4qZLZO/5yrUVDjcLY5ZsSPtwfag BkvZNzwliISYaIwxUX6R2K1Egf45EVXCnbl2AkxmNKLG11m6OQWv1snPmhXqrW4bKn0z /ix8a7emwCyLScnVSoBprdDjcrbZeVOYgPdLBDE9DWOps+PGCxLSv/IFLYHnNIHXOEk4 qjytQliHNnQPbi+l6S4RL3NSz9KUQEfQ4+OCe71aQHNgzcJpqbyQDzU5ezAA7yAT/gHJ QhaQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=u+Q5Gg6LZo0fCDNyjw9HcVHVwre0dDJifCku9AuMwUM=; b=NZk+M0N7Uw0ERZd4CJAd5ori0VXA8q6EsQtA0l/rXSpsKS5Bz2twPQodC1qV+g/KSx thajDP9nVdO5hF/n78Z8xAmyIHIjDslOiWHE4xd4UEjJM2OTgnq/7WaVDrQbM1ZG5R6Q zC5LsjfsoZVgNrPQsXaCOcCQfdYujbwyctQ/qvXtT4Za5EJocwcq47kBYMVD2TTbGHO/ Hza0mKerY3JmBMTG9mwvs6EY+Wi9s2f6kZ3Z1Lp/3EcK1CDn+h9GjufQIxElXpqEcPVx DXYvh4nPJEwCW4YQVwZY/S03cyGegacAe04tE6hJB1DzmoCG7IdOih3kwltxOhDDzXC1 WqCQ== X-Gm-Message-State: AOAM5304tb07w1+CqW7c4Nbqm+ICFZ+lusi4vSLnB/Qy/nsfjjkPam+O 68rFjtxfmmAYyTELEo170XbhTaS0sax/IA== X-Google-Smtp-Source: ABdhPJwi3iA9X+cRchgaHmat7e72QBq9D2dYXWIdRCB0jNQd10429Jbak7EQOofDVZoebT/7B0TKQw== X-Received: by 2002:adf:f292:: with SMTP id k18mr5185914wro.265.1625225218807; Fri, 02 Jul 2021 04:26:58 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id m18sm2763887wmq.45.2021.07.02.04.26.58 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 02 Jul 2021 04:26:58 -0700 (PDT) From: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= To: git@vger.kernel.org Cc: Junio C Hamano , Johannes Schindelin , =?utf-8?b?w4Z2YXIgQXJu?= =?utf-8?b?ZmrDtnLDsCBCamFybWFzb24=?= Subject: [PATCH v5 2/3] bundle doc: elaborate on object prerequisites Date: Fri, 2 Jul 2021 13:26:54 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.632.g49a94b9226d In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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 --- 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 ``. +The 'git bundle verify' command can be used to check whether your +recipient repository has the required prerequisite commits for a +bundle. + EXAMPLES -------- From patchwork Fri Jul 2 11:26:55 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= X-Patchwork-Id: 12355989 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id C7F33C11F6A for ; Fri, 2 Jul 2021 11:27:04 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id A918C613F4 for ; Fri, 2 Jul 2021 11:27:04 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231851AbhGBL3f (ORCPT ); Fri, 2 Jul 2021 07:29:35 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:57316 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231802AbhGBL3e (ORCPT ); Fri, 2 Jul 2021 07:29:34 -0400 Received: from mail-wr1-x436.google.com (mail-wr1-x436.google.com [IPv6:2a00:1450:4864:20::436]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 3B643C061762 for ; Fri, 2 Jul 2021 04:27:01 -0700 (PDT) Received: by mail-wr1-x436.google.com with SMTP id p8so12074247wrr.1 for ; Fri, 02 Jul 2021 04:27:01 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Y5W7k9QjEAK1Hb5opkyjXRAO6gQtXIxhKlWPQXzaW3A=; b=oqZqnSCMPYKzg4a3PFUkY6aOY8RPe2ZmqvJUTw3feL9NrAwik8KKu+yocIxCIvuhZ2 x3iOyf2U/MYqLGwUCyGHWQak+b6r3CK8oxWGrlMhZElX3pyItTTSy7il5iey33iAdPKp Wmmn2cGZ7fDoubYqqEDovozlVmw/8R1rCLSJJiQoJZlsbvD9bk7Dk9qKVK0ZFpbHl2Sn K5e+7S/ctMjCxOPPvx2A38OXlPsk20bLmVf/gL2KMqvlu1qkAP572BayhaoPIjAXYlWt iqZCK6OKH+XWmcfoOZ5Lb+DICOMmgGG9BLiBhEegzqmV3+Ato+nXyWztkIyFFV8E7yaM HRZw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=Y5W7k9QjEAK1Hb5opkyjXRAO6gQtXIxhKlWPQXzaW3A=; b=SkcNBD3glgY3CZ4y+EE4EAthY+/s2LeJV5qhSa+VIRokNvnX2fYhox1kO8KLhyL6+p /MU7lGnz/HIrNp6OIkbg1OslRp7eZvUkuqZZcxGjHaic0snpo2VLhF/jtI6ul/HZAdJq xXck40VdOf+OO47lYddAm80Kia3mky0WU0pXtTG7ha2srGmLND6HNCMvXpobqn+qW/nY 8rxfNaZa3zIKJITYNmQUX+sS+YFBqTKpx+VQHZdyJcaw055VdCnMriz4qf9w0hkZDbAa AOqVdZW42jbeyoPvPWEidEVN4r0g/+yfGLmkdAnCzfHVVYZ2uT5cjTZq0JJtoJMoTe3f MxFg== X-Gm-Message-State: AOAM530h3wrVnL2w7o3M5k29nbBw5Vkfp5ZppRhFY9wbfEab7Ge0LPPb g4+NW1IPCgeAh9tQMff5wDkwM9sZAcWWSg== X-Google-Smtp-Source: ABdhPJxPSbmqQCClDMgu5dTqjEH8UzAMRPVAgKLkFIS0jvoXSpUBLFsDXFhbiC1g3MFoByrRLH1iWw== X-Received: by 2002:adf:ebc6:: with SMTP id v6mr5191821wrn.398.1625225219660; Fri, 02 Jul 2021 04:26:59 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id m18sm2763887wmq.45.2021.07.02.04.26.58 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 02 Jul 2021 04:26:59 -0700 (PDT) From: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= To: git@vger.kernel.org Cc: Junio C Hamano , Johannes Schindelin , =?utf-8?b?w4Z2YXIgQXJu?= =?utf-8?b?ZmrDtnLDsCBCamFybWFzb24=?= Subject: [PATCH v5 3/3] bundle doc: elaborate on rev<->ref restriction Date: Fri, 2 Jul 2021 13:26:55 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.632.g49a94b9226d In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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 --- 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 :: 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 --------------------