From patchwork Wed Jun 30 09:16:26 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: 12351709 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 481DAC11F69 for ; Wed, 30 Jun 2021 09:16:38 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 22FA961D07 for ; Wed, 30 Jun 2021 09:16:38 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233828AbhF3JTF (ORCPT ); Wed, 30 Jun 2021 05:19:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41086 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233772AbhF3JTC (ORCPT ); Wed, 30 Jun 2021 05:19:02 -0400 Received: from mail-wr1-x42f.google.com (mail-wr1-x42f.google.com [IPv6:2a00:1450:4864:20::42f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 1B8D1C061756 for ; Wed, 30 Jun 2021 02:16:33 -0700 (PDT) Received: by mail-wr1-x42f.google.com with SMTP id i94so2722569wri.4 for ; Wed, 30 Jun 2021 02:16:33 -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=NZH0UFIZHzSv2PrzGs6l/0bruWY+6C9eT5tMUsuTMIU=; b=RYqWuSN/ZFsZTA7rnzVvKH0cHEJbBo7kfYm3+VdLlqNczIEsZh6uZnFrqigeg640P/ mjK/GiauVzMDPP2WD3HyKtMSDbTc2adi9hpfT3+KpBVKlZJ05k2EAfgU3CGmj036qMtY cgM4YU9Xo53Yf0hiJ68me+4oR2mrlhj/DXULToiIcGV0P/MrMG4l7mWUslTPskL4hBW/ bfbHy4rUAnXR3aBOsWTRnSnL7NystmiStyN0ci0jxfilTUehQqmYjpn19jkTn7I7OAdq GisFf+Gr6oXwYYDYGwWZceqZHiCSfZhJzyA3N9PiMsG2mo6eARzddz5ZjCHy2RGBJLQJ 9W4Q== 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=NZH0UFIZHzSv2PrzGs6l/0bruWY+6C9eT5tMUsuTMIU=; b=PJBrWLHuxScq2iqqfymOdl1plOaZWCb7/NhAjeRoah3ARxb4XVcyJn2YaNsVFbmDoL BuP1hYNJULZoji+41koFcadxxlqeoakxEm1ZHIWmwvRD3sGR1XlOyqlkpX1H7icv/3/L xqnmDmkH263SWVif3BsqwmYxBllADiD7eUunQ9FbiIEwjRNHEucTYMHuILwTPpYYecZJ QaA+1R4iE+qN9q8TdFUhr+JeyNTmukEU6d3qjHazMhinT51iK7UXJyip4CaWdJRGZRhV msloVBcsgw0pZ9M5Lj1thnmbP3oop5PYiD5UF0+T2cXb4jExd70cd/DWOI8S2pryH2XJ 9bZw== X-Gm-Message-State: AOAM532N73BJsiW55twB1z6rc5AUeHQ51xfqvGZ+/7OWSV9bAg2ry2r3 w0qGVl60JZl5szuxZd30o05JZbQzuaH0hA== X-Google-Smtp-Source: ABdhPJzWGtJHIbJttMy465p/TkRFPu9utE2XOUWaHjrdB7s9alfaCoHS5lN6JoATwWm4TZNEPl7sjg== X-Received: by 2002:adf:ce07:: with SMTP id p7mr5269525wrn.70.1625044591497; Wed, 30 Jun 2021 02:16:31 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id p2sm20372711wro.16.2021.06.30.02.16.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 30 Jun 2021 02:16:30 -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 v4 1/3] bundle doc: rewrite the "DESCRIPTION" section Date: Wed, 30 Jun 2021 11:16:26 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.613.g8e17abc2eb 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", 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 --- 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 ------- From patchwork Wed Jun 30 09:16:27 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: 12351707 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 A912FC11F65 for ; Wed, 30 Jun 2021 09:16:37 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 90D8461D02 for ; Wed, 30 Jun 2021 09:16:37 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233827AbhF3JTF (ORCPT ); Wed, 30 Jun 2021 05:19:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41088 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233541AbhF3JTC (ORCPT ); Wed, 30 Jun 2021 05:19:02 -0400 Received: from mail-wr1-x432.google.com (mail-wr1-x432.google.com [IPv6:2a00:1450:4864:20::432]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C8543C06175F for ; Wed, 30 Jun 2021 02:16:33 -0700 (PDT) Received: by mail-wr1-x432.google.com with SMTP id u6so2708578wrs.5 for ; Wed, 30 Jun 2021 02:16:33 -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=BuYXLHFsgDO0bPR+A3QKT3jSxa5O19P3tSEcm2nbMdU=; b=P0OhuUEKLBtFtVVjFxIE8KBiVBSg28cCIqNZ3mJY9Bkf1YwDHxC23NyVvCjShUB6ST Ej0TwbLQBKM1ZZ7jZtU0tLR38VipE83EZYu8aul4x8CysNlqRLWXCK97XvL0wPROzfA/ 4VlksY3gGxvroPz9ysfP++M1+dE30cxhCA/qimCnaYTfZIla+uTXJVEUAuEorlCXCxvM dz3MQNdd8wKz8B77Zhc8Jo/nukYj//5Ro0mUiD5lYqVjoojftt8tWrMm3XmFzL5aXRuI NfJwkfVNyB7Zt1BhFubSuK9Ta5QS8SLtNzk3q8YhnATqujgRZ5tCHvQ6ylO9KKe79vwN 1piA== 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=BuYXLHFsgDO0bPR+A3QKT3jSxa5O19P3tSEcm2nbMdU=; b=JfE1kdb5HA7XxgZ3DGblxVQtAxE4oMCpFfH8v1LY9ludZ57kugTHPVNjPwMD4fUXRX BTqSP8/LMRnpP7ZaV/eDDGw136kzd+JFUuInyZFBv7ouwfBna0gADS72X6Pi6WK4Pq4t IuHuXBjNSP1mUfA5yuG+NjU6JkwK5XEj8XUh/aLh+vfAnqeL3dbFAglSloEXQAVX+MRk 4dhgjMerL4ip8bl9vFewSyh3QPSsx9zcnKUuh10Qa44BGLRG1SrLvbQA0ocvWMHva2bv If6q72mjLBTDwyUICn1fq1sM/TnneuXatR4ZTPii0PHPaKFA3CTtOMolRpKgkNNmycp3 IJDw== X-Gm-Message-State: AOAM531QZJIt6GuNDvCwMGmZujJaUQQMnKTNY/lIxESEpgqQZdurGLPF EvCkVaI6wSy0L2Ykmj8zf5YQeQz5rqflBw== X-Google-Smtp-Source: ABdhPJx2Y3nniO9C8rMVffiJr6F/BUIj3bnI502HjKXzj3XKzQvefU+/Qe8fzFfY/uoKObDy0RnBKw== X-Received: by 2002:a5d:5405:: with SMTP id g5mr11666129wrv.12.1625044592194; Wed, 30 Jun 2021 02:16:32 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id p2sm20372711wro.16.2021.06.30.02.16.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 30 Jun 2021 02:16:31 -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 v4 2/3] bundle doc: split out open v.s. closed discussion from Date: Wed, 30 Jun 2021 11:16:27 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.613.g8e17abc2eb In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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 --- 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 ``. +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 -------- From patchwork Wed Jun 30 09:16:28 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: 12351711 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 CDC75C11F68 for ; Wed, 30 Jun 2021 09:16:38 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id AFDA161D02 for ; Wed, 30 Jun 2021 09:16:38 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233832AbhF3JTG (ORCPT ); Wed, 30 Jun 2021 05:19:06 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:41094 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233806AbhF3JTE (ORCPT ); Wed, 30 Jun 2021 05:19:04 -0400 Received: from mail-wr1-x433.google.com (mail-wr1-x433.google.com [IPv6:2a00:1450:4864:20::433]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 88246C061766 for ; Wed, 30 Jun 2021 02:16:34 -0700 (PDT) Received: by mail-wr1-x433.google.com with SMTP id u8so2691960wrq.8 for ; Wed, 30 Jun 2021 02:16:34 -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=6kObgg6KR0OuJcPS0ZBL8S6t+t5XRok3syjamTk+XZM=; b=WBlDsq4qy0o3YY/vTVcIAvGrCWcnTIb0fpD+Hoo1B2ANK9bTC7N5kg6MhnWGE1rv1T a2oBzQ5EXQzdsUCJ4g0QmDMplnKbv9eK2WqzFfqLTKvdQ2V40GeqIY1+XSogYWdIO0wq 41ujuvtYjQ12C0fGrAcxOFPX1KeVoBQg4Lkh5K5JBrnls+DL7si2ac0JHYlp4MKuPB+a QHumA3h0H4zjUOcBrf4g579hpOaVPQrRibbzstQrhHOqsgzeODwf5RaC87KmbvXaNQIY FIBBuGVZKzKX0Qg/AEkSv2HI6AC0NIeXBQcRInFJLTBCfNdr0nSKmtqYYxKz4IKFhPuU fppw== 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=6kObgg6KR0OuJcPS0ZBL8S6t+t5XRok3syjamTk+XZM=; b=aZrSJKpXQGoGI+l6S/qFFQZIUKh7SBwsqe7BGGtYIflEQdmj+O6xrhHz3dacNtF2WX xCaiS7ZspJEb48J89BviUWM9ZEbfdCDqnVZ9b6U2du6RGTOMHOTdq5m4sqaMKQoB7xu7 asVYn/vjTQNSx0QZa8mLY5LAuXh8JSAa86Dfc/NvqrkQoRJqTPictJFOS9l6cmD4Wqbv Miu7saMfyK9zeLSlWo1VbB3uRxbr4qfb07HXAiYGML7aMiC3qg6GhfihkYShaUPZSycr MSiqKSE3bfroW2p+B4n5XyhvbWBVdjnM3pXjWIdZJegxFFzgXCWQO59QQtyKvSB/kyVH 5WYg== X-Gm-Message-State: AOAM533VPS3Aeu89u/o1RcOJZEIwjk7zleIKvwc389mpdEvu7I3PPeWu grP3SgvoAkjQsW7hxoPxLFZC76azG8xblw== X-Google-Smtp-Source: ABdhPJxHM5YmwiUc1iEVQ4D6k/TUewcqwX+YHrAsFkGFsrcTd4+13sKoASe9hcOT++Gd817qhi4qaQ== X-Received: by 2002:a5d:6d87:: with SMTP id l7mr9229584wrs.222.1625044592954; Wed, 30 Jun 2021 02:16:32 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id p2sm20372711wro.16.2021.06.30.02.16.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 30 Jun 2021 02:16:32 -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 v4 3/3] bundle doc: elaborate on rev<->ref restriction Date: Wed, 30 Jun 2021 11:16:28 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.613.g8e17abc2eb 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 3bb3b71526c..2216b9f2843 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -133,14 +133,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. +---------------- OPEN AND CLOSED BUNDLES -----------------------