From patchwork Tue Jul 27 00:24:19 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: 12401121 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.7 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 8E91DC4338F for ; Tue, 27 Jul 2021 00:24:32 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 7740A60F6E for ; Tue, 27 Jul 2021 00:24:32 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234377AbhGZXoD (ORCPT ); Mon, 26 Jul 2021 19:44:03 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:53998 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233770AbhGZXoB (ORCPT ); Mon, 26 Jul 2021 19:44:01 -0400 Received: from mail-wr1-x429.google.com (mail-wr1-x429.google.com [IPv6:2a00:1450:4864:20::429]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E057DC061757 for ; Mon, 26 Jul 2021 17:24:28 -0700 (PDT) Received: by mail-wr1-x429.google.com with SMTP id r2so13122319wrl.1 for ; Mon, 26 Jul 2021 17:24:28 -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=TrIRMMYvK316XeOix5nCKunawZSOcfNahbVQJILldVY=; b=DkmVQzaX+iL7/DWf/9kpqLorbpJdFFhCGCbwvb4t6bY5zzTypF7FK5tIB9njqorbQL lhgke3XTdr/eKWILA/yDwqnVMM6mT7rX8MvqTqBSb/p9W9znDunskEra/YB90f+73eNX hcdeinsGhf3lXQN8diuVLq/jBQgCulAZSSkrnNnKI7BUwtRa+5+OpYoSZHkswetJf1L3 l3FGmK84lhm+N6rSCTohY8ktAkXEDxkYr8RXfSeK/EyqFoV1RiftdxA5c2OHNc0nmSw/ o6pkkpVwYBB1yLotRmgYk8Y8gj7WqJF/MW/OpKvwzBZEcnVw/GFrQKqy4IXk1ARkIB+A UlcA== 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=TrIRMMYvK316XeOix5nCKunawZSOcfNahbVQJILldVY=; b=n4fI/DNFsDaGdRUKsa+XZBEVKCp0o3yS6fiUF2cDU2BwCgjpIxze2/tcV1Msz1GV+h w5tGJrKtVUFYUJylpQ3KujDe51eaV/mJ/zbPw3iwUY3H/Z3XpAM4DSR4RUJPMEY1vT2Y 01hygoKek1GDfn68j4gXt/8dO6chgoQ+fXsmCjIqkQrQaVdFJ+13Utxi+oMRVnAzFQ8B KMiaBmWK/USmzHp3U3PV62eK0V2L3KfFztWTnidCZ3g9hfptau1gM/Li3ObI1jxwvs+7 xHke6EUkT/4X/MBqOTsJ25ooxUb/vq5bvnCpfDyh/4KbiiFGRG+4S1XCT0bgqJgDm74p 9H9Q== X-Gm-Message-State: AOAM5323awVz3v/T7jGywHPDkg2wGwnirik8eZVf09z9AfE0yOeBGD7M fFLLov6sL8zWEFyJAilnGD1VwbZruwTIUg== X-Google-Smtp-Source: ABdhPJznFGboRqkSieAGB+kD/gTwXpmXA1KdHCJo3DYSU70qwspKuzBuK8gK3ik6RnLTNy5F/kqkdA== X-Received: by 2002:adf:f7cc:: with SMTP id a12mr21048111wrq.278.1627345467211; Mon, 26 Jul 2021 17:24:27 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id l2sm1115872wmq.0.2021.07.26.17.24.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 26 Jul 2021 17:24:26 -0700 (PDT) From: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= To: git@vger.kernel.org Cc: Junio C Hamano , Johannes Schindelin , Philip Oakley , =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBC?= =?utf-8?b?amFybWFzb24=?= Subject: [PATCH v7 1/3] bundle doc: rewrite the "DESCRIPTION" section Date: Tue, 27 Jul 2021 02:24:19 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.988.g1a6a4b2c5f 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 | 56 ++++++++++++++++++++++++++---------- 1 file changed, 41 insertions(+), 15 deletions(-) diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 53804cad4b..339c5b4727 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -18,21 +18,47 @@ 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. + +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 Tue Jul 27 00:24:20 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: 12401123 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.7 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 A5FCFC4320A for ; Tue, 27 Jul 2021 00:24:33 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 86A1160F91 for ; Tue, 27 Jul 2021 00:24:33 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234397AbhGZXoE (ORCPT ); Mon, 26 Jul 2021 19:44:04 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54002 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234335AbhGZXoC (ORCPT ); Mon, 26 Jul 2021 19:44:02 -0400 Received: from mail-wm1-x335.google.com (mail-wm1-x335.google.com [IPv6:2a00:1450:4864:20::335]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id BF0A8C061760 for ; Mon, 26 Jul 2021 17:24:29 -0700 (PDT) Received: by mail-wm1-x335.google.com with SMTP id l4-20020a05600c1d04b02902506f89ad2dso905887wms.1 for ; Mon, 26 Jul 2021 17:24:29 -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=8zwJJhksFQ5yRI33eYjk6PQt/07LTtw4z6X0N7XcQZA=; b=bfvJNqld9xoYgNZqy7DX/jr6Ct9l0vnhsFTbbQcCFzJUpcnkU4A+kiJJgr+P1hoR30 5lJVEh0iLpXewOKLyNHeulkyYw6av58oP24rNiAuxy80PDRH4eR0VqP6b5i9fJJNApf1 pZbA0O7QPYcYh//CMNs1AA/qFzf7YY1A4wahiRQ4E7k09FWkemPEPkAaaEd/EXXgXgwE 7MFnFP3m0CxDsKzrgRBaasUx/NisCgzt8IZezmk8M/FzYxi3T2gWdSJx2vkKKJGbi0nP LpgXWTPGQh8AQuxdLrzaJ/H1xAcO28T0zrTAlUGZzjsX2hJ7GeJM2i5oc3s086e9XKCx yqmw== 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=8zwJJhksFQ5yRI33eYjk6PQt/07LTtw4z6X0N7XcQZA=; b=I+4DvQvDJsFb7gDzYohukGyyl0oVGECAk6yjcnCWz8CdJszlAAenUPyTi0MAT+fh8T XH4fqiIcv4EiNiUWFx8rC1TivKqwDI2asoVfycSqw7TJshD2Y/2eIFTr88tswpjEIKXz J6ePDCDJ38UlIKowurzzX+4aBt0HdlBJ8ag8QtKKcphsh/PQBOexpkA61iaeJKzPfHYk eIH6LMQyJVkt3KPMaQFVDeZR5GUm3MOdhUit5G6gDM6yaW+v61QpdyAqOOzsTMGNyb4x U6TxiG7zdqPRLsnOUu360WG+mojVDi7gRlxLyQC4Bdcp5cFd1Y3KqRKq41TwQtP8XYoY dGeA== X-Gm-Message-State: AOAM5328o8QfeM1M5LAlpYupp7YF6ngfm6vbYWONhaEUO9tK51Q1aztr Y8vQr2aX5FQAeGHWu+qDOE0RVcg1yth/Hw== X-Google-Smtp-Source: ABdhPJz+m0s7GxnHYxC+6xnk6vyKT9KUiKXLdDTZjq0xrbKnTQLqrZDhstIgtjnM28mJqVUTdLtYbw== X-Received: by 2002:a7b:c045:: with SMTP id u5mr1312225wmc.158.1627345468084; Mon, 26 Jul 2021 17:24:28 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id l2sm1115872wmq.0.2021.07.26.17.24.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 26 Jul 2021 17:24:27 -0700 (PDT) From: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= To: git@vger.kernel.org Cc: Junio C Hamano , Johannes Schindelin , Philip Oakley , =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBC?= =?utf-8?b?amFybWFzb24=?= Subject: [PATCH v7 2/3] bundle doc: elaborate on object prerequisites Date: Tue, 27 Jul 2021 02:24:20 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.988.g1a6a4b2c5f 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 | 37 +++++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 339c5b4727..f1f84ce2c4 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -44,6 +44,7 @@ header indicating what references are contained within the bundle. 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 @@ -152,19 +153,49 @@ 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 self-contained bundle +that can be unbundled in a repository with no common history, as well +as providing negative revisions to exclude objects needed in the +earlier parts of the history. + +Feeding a revision such as `new` to `git bundle create` will create a +bundle file that contains all the objects reachable from the revision +`new`. That bundle can be unbundled in any repository to obtain a full +history that leads to the revision `new`: + +---------------- +$ git bundle create full.bundle new +---------------- + +A revision range such as `old..new` will produce a bundle file that +will require the revision `old` (and any objects reachable from it) +to exist for the bundle to be "unbundle"-able: + +---------------- +$ git bundle create full.bundle old..new +---------------- + +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 Tue Jul 27 00:24:21 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: 12401125 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.7 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 B07F6C432BE for ; Tue, 27 Jul 2021 00:24:34 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 995E560F6E for ; Tue, 27 Jul 2021 00:24:34 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234404AbhGZXoF (ORCPT ); Mon, 26 Jul 2021 19:44:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54008 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234352AbhGZXoD (ORCPT ); Mon, 26 Jul 2021 19:44:03 -0400 Received: from mail-wm1-x336.google.com (mail-wm1-x336.google.com [IPv6:2a00:1450:4864:20::336]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A1B95C061764 for ; Mon, 26 Jul 2021 17:24:30 -0700 (PDT) Received: by mail-wm1-x336.google.com with SMTP id u15so3021486wmj.1 for ; Mon, 26 Jul 2021 17:24:30 -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=GAufCCFBLA47ou8BtLBDm1yVN7AVOO2kz0ntvGKJAhA=; b=s3c6U1Boqr13jW+z2bBIGiPlV/RXaSXxNUrtfc9PVuifjP/rh1KCx6nDX7TebMBEBa 0QRyHh3vNzQ0YEFJ4dWRSNEUTmC0NeiFtacS2lLw+5fFtICwDf8v46spy20wJyGJCNjE +UfO2HwcuNcEz6jql/Y54H/XoPkS5xY1IjjtP4FcnLNCNBfKUPOeVATiP/WlBLKoU2Dh qvxxAaxFTqURYqSNyBCBF+9AuwiW5VHpCPcV2NCgbmqYDHCPkhM/SsqpvzOlDbtM7iUo tgy8jTPxbHYlLV9a4/LXrBzm4ewx6mUqAf9Dnp/assIMxOcT50GQhT8RU/M0XCKssSL+ hnjA== 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=GAufCCFBLA47ou8BtLBDm1yVN7AVOO2kz0ntvGKJAhA=; b=m935stIVOBeIjClZWDJIpSdCEI+5GcnMtedMduj3ntj3hqGrLYxB7pU6WaHreQfljv 9Nj65OJgImgmrysu2PNJ4C0fUxpoJ+hgjW2OrBlVqREaklDgAGy7w1UcvcfTLx3adOhM KuBmq21DVj+ZTNKya4EYZqLrp6nJL1JQiWIzb+LIlYPSxy7Lr81A9DWWkxgk7BlJ1ir+ +UeneH2WO9l8Ypb8wqT0CtHjEQa5UB0WQc+dyM95NJ35Dzo1nNarzgQBL3UP4RePtmw7 HtFULjpPaV2WOTrUDweFK42z/LQVFAOzDa3YUpjsZ0GrSRdzKeSpaoi4n5utBT80XwQm T+LA== X-Gm-Message-State: AOAM530Oc0ljoYOolH75/ywQXA0Lk+VIlDltQpt+qeqoNnHz1CBzEF9q v6dldxYXXZjbsKJwmRQHsHQiBnUJi2hAng== X-Google-Smtp-Source: ABdhPJysvXr/MD5Rk1LNms3biD4ZG+j/rSAkEeJTgQLp4bL1KL9UOOVxOUMLAXXcrqhIYUU1GJq3fQ== X-Received: by 2002:a05:600c:3795:: with SMTP id o21mr5460573wmr.90.1627345469026; Mon, 26 Jul 2021 17:24:29 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id l2sm1115872wmq.0.2021.07.26.17.24.28 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 26 Jul 2021 17:24:28 -0700 (PDT) From: =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= To: git@vger.kernel.org Cc: Junio C Hamano , Johannes Schindelin , Philip Oakley , =?utf-8?b?w4Z2YXIgQXJuZmrDtnLDsCBC?= =?utf-8?b?amFybWFzb24=?= Subject: [PATCH v7 3/3] bundle doc: elaborate on rev<->ref restriction Date: Tue, 27 Jul 2021 02:24:21 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.988.g1a6a4b2c5f 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 f1f84ce2c4..0f28c41409 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -144,14 +144,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 --------------------