From patchwork Sat Jul 31 08:23:04 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: 12412369 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 F0B91C432BE for ; Sat, 31 Jul 2021 08:23:16 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id D31F860F39 for ; Sat, 31 Jul 2021 08:23:16 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232525AbhGaIXV (ORCPT ); Sat, 31 Jul 2021 04:23:21 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49604 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232048AbhGaIXT (ORCPT ); Sat, 31 Jul 2021 04:23:19 -0400 Received: from mail-wr1-x42c.google.com (mail-wr1-x42c.google.com [IPv6:2a00:1450:4864:20::42c]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9964FC0613CF for ; Sat, 31 Jul 2021 01:23:12 -0700 (PDT) Received: by mail-wr1-x42c.google.com with SMTP id b7so14392217wri.8 for ; Sat, 31 Jul 2021 01:23:12 -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=M+kj+2kPVc0X1GHPFENrqXCHIa08ZM6iwBGFRPciBMg=; b=np4eJCAhMvhzkvPv4DRMNFBGyIgQCn3lOldH0d2d7dwN+HQVmgNoaDaV5tjFcWW4hc eQY+i+6kzvk74FK5JkuLxPEma/0Ebcy41y2YmOTkU20JcpzKJBRCSwWM2MZmmcb3EpII nGyEhyWky/Eke/AIVvOnFbOxzMoPUBJlm/d0+wh+95HQWUG2GSEaAD2GdDPabnk6gh54 bVeoFq9seY6b1dKeYI4AxxycVDj9iS8EDm6TadZ9hPBOcXfkTZsYCrxCu40vAFlxx11Z kjP/2VMuqA0ml2Kad2xuGLmmKko0M5S4Z58u5OaU0ukyWBmUkhO5IDoMxNfHQm7SYvm2 KLgw== 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=M+kj+2kPVc0X1GHPFENrqXCHIa08ZM6iwBGFRPciBMg=; b=Y531oWB4kSvKNtBpinKObKLj53pVUkL6GiUjNCACOC16j53qTkr0aY/Xf/zXGcJtaS LNbjhynAU6pfsGYTz+9WVOjC+xxwfKNuT/JFbP5g/BY29nryvSslONWrmlO8wl3u+RE2 lgKkp5lykCWwIW5Aa71tKfcR0APTF4WzdHr0BtKPsRQl+TLJ3NH+Yy2bi/ZbsrGu8Cg4 i/np6CYv4i+EqOAlIeC3Agi11QXr8VpNGv4MXRgqUSeeTIBqJr7372mvZDWjSML6LjFd 22oTgVmwhR2RVRbl6UBaetIO8rgGPEVG7gwGirq/BUy5BUsanXWniARBpPlVkP7q8fl8 2udw== X-Gm-Message-State: AOAM533kNNV/lnag5qRIdXUv8FGGaUdPDEHylgpm2duAqLFP9/KBq/GV TVCb9yA8GllrbtOk9R+uRi8vs10zaPoAIQ== X-Google-Smtp-Source: ABdhPJwkcND11HUQ2HXvIuWuH6r91qTZV4EUiXgpQYy58JfPqgm9BmfvqM4r2FpzqgFy5CDs52EbDg== X-Received: by 2002:a5d:4b4e:: with SMTP id w14mr7177738wrs.341.1627719790984; Sat, 31 Jul 2021 01:23:10 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id n11sm4877548wrs.81.2021.07.31.01.23.10 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 31 Jul 2021 01:23:10 -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 v8 1/4] bundle doc: rewrite the "DESCRIPTION" section Date: Sat, 31 Jul 2021 10:23:04 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.1069.g545f0888808 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 53804cad4b6..339c5b47276 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 Sat Jul 31 08:23:05 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: 12412371 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 331F3C4338F for ; Sat, 31 Jul 2021 08:23:22 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 1A9A460F39 for ; Sat, 31 Jul 2021 08:23:22 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232590AbhGaIXX (ORCPT ); Sat, 31 Jul 2021 04:23:23 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49606 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232405AbhGaIXU (ORCPT ); Sat, 31 Jul 2021 04:23:20 -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 53687C06175F for ; Sat, 31 Jul 2021 01:23:13 -0700 (PDT) Received: by mail-wr1-x432.google.com with SMTP id h14so14357816wrx.10 for ; Sat, 31 Jul 2021 01:23:13 -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=CFW/gkq6Ph9OsZu0Q2/6N2wyLn7ybSoQXk+pkbDSkU8=; b=Y46B/CsglhwoVOq7w6UZKnJ9lpzK6NtervOdphby4RI1ISNqDc8wufR2t7RSu6UbRF u0r51FAq1CVlqfrQmicBXpdo9dj9Y8DclEhoScml8P/EI+2G+RlbJxvpiDvmsRgwUnP2 2ByqXIrb/iFpfJ6ixBrCTIi9s0JbXwJtTY+Jo52tt9EeRgJko71phmHM7lWgOYz+sKAS 0TQe+RBTvx5JdFR4qlHV0TSU9mkcDWG23g6QJEqTMEXKuwXiPfX0IvuicV0bTlJX4mzc 0liFffzxfTXOZU+LG74VcKni3w4d3c0uaJtLUrt46oO2v+5p81QPpp0QOroq0JFQedUJ Vyfw== 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=CFW/gkq6Ph9OsZu0Q2/6N2wyLn7ybSoQXk+pkbDSkU8=; b=DbTM4AN8e8Aw/4OoRCe9GWlq6KxlBaBL5PdvKr6840HPvznRIDNTrTEby2ppoWBa4A Nvl6rTc6PEEyNnKzm2ZfXTd+txj4nrlhzY/UAu1C8Iyzo7DVHjDFB5UUZv0+cN+E3bk4 I9ytGnMzmy/F64l5Z+pZXNwxxHhDsdhXKGDyKzC11dumbZnYfsCXHGBaIgkVTYsYI/Ir tHSh5utJQpYV4B6sM+MXRZBcuGA3xIAjqnxsONwtRM4ryXa8pvJUCNvpPNCGUaL+i1+S scQuAJVmGjnxKjAi/dNU9kShSy64S65A9OASMPubI4RX1wguPFjsrB8fYOtfuj97+GO1 9QBw== X-Gm-Message-State: AOAM530f2ms5hRtGUljtaDTcm3feKUfP3OaUoUHV9netrN/TjS0UPYfN QlJxl/LysnbzI/g91ph3GRd4vfu7p1p4HQ== X-Google-Smtp-Source: ABdhPJyWcFiy4bz5bR6OVcevJ76IWN19JF1avZnRj8swhRGtx8EAfaK9z3i+4bpIjLp+GCDECh/e4g== X-Received: by 2002:adf:80e8:: with SMTP id 95mr7242032wrl.388.1627719791708; Sat, 31 Jul 2021 01:23:11 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id n11sm4877548wrs.81.2021.07.31.01.23.11 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 31 Jul 2021 01:23:11 -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 v8 2/4] bundle doc: elaborate on object prerequisites Date: Sat, 31 Jul 2021 10:23:05 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.1069.g545f0888808 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 339c5b47276..f1f84ce2c42 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 Sat Jul 31 08:23:06 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: 12412373 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 B5ACBC4320A for ; Sat, 31 Jul 2021 08:23:23 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 91FB560F39 for ; Sat, 31 Jul 2021 08:23:23 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232657AbhGaIX2 (ORCPT ); Sat, 31 Jul 2021 04:23:28 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49614 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232363AbhGaIXU (ORCPT ); Sat, 31 Jul 2021 04:23:20 -0400 Received: from mail-wm1-x32b.google.com (mail-wm1-x32b.google.com [IPv6:2a00:1450:4864:20::32b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 16129C0613D3 for ; Sat, 31 Jul 2021 01:23:14 -0700 (PDT) Received: by mail-wm1-x32b.google.com with SMTP id n28-20020a05600c3b9cb02902552e60df56so7840662wms.0 for ; Sat, 31 Jul 2021 01:23:14 -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=qmXQghiUngzCbpZCA03C1W+Q3Rx5LmUsBiZxDFAv5yk=; b=iXOlRVWgfuEtxTmsrpaVkGCLTj7ym9CeOLjcTNJCKs4BrLSw6CDiaE8/VmsqVJRrWN OsnMso8phuEfy3+5lq4MRs3nGdBCWDNH5mRQYzFFv3HfHVC8SorwH8s8xThIJk8YH6q1 25VvOrbEie6HvtcyoAD03AzzofEXSJpXhp6iL0Jxx5AJvPxgT9AehtZL73TZVxp1bPNw qAW186OZRqhUcw282lgNz4+5N+I2h3d+a56P4IMmA7zaftuxoIX3A/hC0IAPlRJoYIpJ GWzVlG2VGxA9NERwI2u/phVTXD0vqA4UkibYA+zEo+xZCp7YX7bJp5hfrk9uFIjY3XsM K24A== 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=qmXQghiUngzCbpZCA03C1W+Q3Rx5LmUsBiZxDFAv5yk=; b=jVqY/I0zQeIOJVLvhW4GhjDrZZCaK1aHGfdcSx8g6VhKgA6YXSmrzbuuI2RdDxbNbm 6AvUQEpprgf5T09Cu5oe8wUXkt9lepAPfjVQnNi6sJu7OmWccHeCluJHzDwS4FuSwPOI 6T9jTkKVxlfw9xO9L+rRkPuhCJqR6cb8adnHmAKNyChgYYG9TZM88KbmACseRVgSBTcd NduAHmE+FVemFLLZ/XP/IEykkX5JCalnteczEJ/X7Zm1NPFaAU951jfLrO8b3Sr9FJA5 cj0rTCZldnQ9Kxn3yaJHecQw1c+HqkG245bk3Mt7ribaXzdHDD2CtN8HTCyTFrSrV9Ki OvAA== X-Gm-Message-State: AOAM531UktPMxtO97qwNXwyXN7O6IBxCIL+b6YCqIS9r0arfY4zODrIO JtW3jp20vt35QvlM7tVO/M+QD9f7sJHckA== X-Google-Smtp-Source: ABdhPJz8qi/ZdxODDJJFAf59pRtrCtXzhkepnIx3p00zqdGW9KVZXlS53dpbwDw0NKfOzEp1wd7Itw== X-Received: by 2002:a05:600c:4141:: with SMTP id h1mr6911707wmm.83.1627719792477; Sat, 31 Jul 2021 01:23:12 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id n11sm4877548wrs.81.2021.07.31.01.23.11 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 31 Jul 2021 01:23:11 -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 v8 3/4] bundle doc: elaborate on rev<->ref restriction Date: Sat, 31 Jul 2021 10:23:06 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.1069.g545f0888808 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 | 46 +++++++++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 8 deletions(-) diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index f1f84ce2c42..f36939ab014 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -144,14 +144,44 @@ 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. + +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 -------------------- From patchwork Sat Jul 31 08:23:07 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: 12412375 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 684F6C4338F for ; Sat, 31 Jul 2021 08:23:25 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 4EF5260F39 for ; Sat, 31 Jul 2021 08:23:25 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232635AbhGaIX3 (ORCPT ); Sat, 31 Jul 2021 04:23:29 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49618 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232543AbhGaIXV (ORCPT ); Sat, 31 Jul 2021 04:23:21 -0400 Received: from mail-wm1-x32d.google.com (mail-wm1-x32d.google.com [IPv6:2a00:1450:4864:20::32d]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id CC00EC0613D5 for ; Sat, 31 Jul 2021 01:23:14 -0700 (PDT) Received: by mail-wm1-x32d.google.com with SMTP id n28-20020a05600c3b9cb02902552e60df56so7840678wms.0 for ; Sat, 31 Jul 2021 01:23:14 -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=oxCjJUYxP/oT3e7qiXs1xIlVmX7K4tlRHed4RoLOLcw=; b=FVs2iQFGjA+alKyzIGK9MMiA5FO6t9AhCUr9eh9vPtCVOLM2m5CnXRgf25nYoHYjqM v3hSNo9g44EUG99qLJGJIcRX6Zv2JjeOctIpgkfd+7SmpsUY2ZPB5R4lyN1Sh3BglC5a TTAhUytYb0xipZWcqbVbbW71VwPvMHmFe1SrK4j58+cnJxy6Davbmu4kS8YCDg0AWnhY zgmqFHqW32j6CVU/OLxGf+3+E4Rem6ngAY/J1mLB5k29NYW5BhUgpJ23B7oFxBkIhPO1 +LDJCDtgjPQgFn06OGHE/Q3V26gV8FNJipcSakd29v4LLW4eowRWpcgxdyAZFhcDYBgs Iz5w== 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=oxCjJUYxP/oT3e7qiXs1xIlVmX7K4tlRHed4RoLOLcw=; b=m7U0CDRGIGjbjoluKIvWXZoYVszh9vogs7Q/eJKbhpNwCRmQMRbrSzGrVzLjZPyKfx pna3MRu9uwnSvyRenstqetoekQ4WVtsYt2TyUY6DcLIEAALfDhc7sT0sZfuI/nwniOY/ UTmgpjpGVQ4TFWs3Rx8aRD/raldUbQDaa4ERlvk2nYD1W4wEB0Imt7QxKHUGlWzBl6mJ fapzzG7+g7xIA1IAGEyyWUdsukVeMBUztzv+VtRbClGkx43x3qrANpVGiqYUwsfLWNi7 MgS0i+7DlBzC+MQemL2cbfnHN8WeIz4hLIk1kbfCMinUN9QJYjhptfkLRr44bo/hL6ls Q5aA== X-Gm-Message-State: AOAM530sui7717UuZN/s7NEiYQIrYSwAFeY59gBxAUxtuYCGryEClITH rmZvLPCM/Xg/172SJEGm9FiWzBw5nxJwtA== X-Google-Smtp-Source: ABdhPJwC4PjBjyOJI1mXeFRaYoJwNY6fuvyBYcSnaRt2XMjA2y+V2Uz8+9MrkC53eNzVoNN9StdmGw== X-Received: by 2002:a1c:a98a:: with SMTP id s132mr6856737wme.131.1627719793164; Sat, 31 Jul 2021 01:23:13 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id n11sm4877548wrs.81.2021.07.31.01.23.12 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 31 Jul 2021 01:23:12 -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 v8 4/4] bundle doc: replace "basis" with "prerequsite(s)" Date: Sat, 31 Jul 2021 10:23:07 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.1069.g545f0888808 In-Reply-To: References: MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org In the preceding commits we introduced new documentation that talks about "[commit|object] prerequsite(s)", but also faithfully moved around existing documentation that talks about the "basis". Let's change both that moved-around documentation and other existing documentation in the file to consistently use "[commit|object]" prerequisite(s)" instead of talking about "basis". The mention of "basis" isn't wrong, but readers will be helped by us using only one term throughout the document for this concept. Signed-off-by: Ævar Arnfjörð Bjarmason --- Documentation/git-bundle.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index f36939ab014..ac0d0038350 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -147,13 +147,13 @@ SPECIFYING REFERENCES Revisions must accompanied by reference names to be packaged in a bundle. -More than one reference may be packaged, and more than one basis can +More than one reference may be packaged, and more than one set of prerequisite objects can be specified. The objects packaged are those not contained in the -union of the given bases. +union of the prerequisites. 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 +prerequisite 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 @@ -236,7 +236,7 @@ but we can move data from A to B via some mechanism (CD, email, etc.). We want to update R2 with development made on the branch master in R1. To bootstrap the process, you can first create a bundle that does not have -any basis. You can use a tag to remember up to what commit you last +any prerequisites. You can use a tag to remember up to what commit you last processed, in order to make it easy to later update the other repository with an incremental bundle: @@ -287,7 +287,7 @@ machineB$ git pull If you know up to what commit the intended recipient repository should have the necessary objects, you can use that knowledge to specify the -basis, giving a cut-off point to limit the revisions and objects that go +prerequisites, giving a cut-off point to limit the revisions and objects that go in the resulting bundle. The previous example used the lastR2bundle tag for this purpose, but you can use any other options that you would give to the linkgit:git-log[1] command. Here are more examples: @@ -298,7 +298,7 @@ You can use a tag that is present in both: $ git bundle create mybundle v1.0.0..master ---------------- -You can use a basis based on time: +You can use a prerequisite based on time: ---------------- $ git bundle create mybundle --since=10.days master @@ -311,7 +311,7 @@ $ git bundle create mybundle -10 master ---------------- You can run `git-bundle verify` to see if you can extract from a bundle -that was created with a basis: +that was created with a prerequisite: ---------------- $ git bundle verify mybundle