From patchwork Thu Jun 24 19:40: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: 12343097 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 44335C49EA5 for ; Thu, 24 Jun 2021 19:40:40 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 2AC5760232 for ; Thu, 24 Jun 2021 19:40:40 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232837AbhFXTm6 (ORCPT ); Thu, 24 Jun 2021 15:42:58 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59388 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232758AbhFXTmx (ORCPT ); Thu, 24 Jun 2021 15:42:53 -0400 Received: from mail-wr1-x434.google.com (mail-wr1-x434.google.com [IPv6:2a00:1450:4864:20::434]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C0E63C061756 for ; Thu, 24 Jun 2021 12:40:32 -0700 (PDT) Received: by mail-wr1-x434.google.com with SMTP id m18so7939310wrv.2 for ; Thu, 24 Jun 2021 12:40:32 -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=6dw25b5B9jjtJqmsCvd0LpMJ1lo7EMy8Nlohi8a73jk=; b=fKjfQQ9ljMzguouNx3oaTUyulkP68GXwkm+6soJ/votBA9Byojx/bSN1qQ5ILjbXOZ msDLP8uZkyw9k4epSv0KknIKVmGNV+R07bc5fXzNzEvpOuChQYA7Ha0siEC1ffIhhD7D 3aOYj3z80qs01Qx4S3z1cl04z4SyNN+fvDgagqKhAY1wWakgX0cLfVwbtnfOEQ5ffVsg aNIlwSOxcHl8Ay24BIJCTmSHZlUc5P6Ul29NDly42rUYvRKya2kDnmIhDmbySJQ8Wt3B 895Vp6v5XV6Np5ZT/QECZfHzw35rP0BjpBe0phN0FFbyVi4Ayz7WW3MXLdudEu3W8d9D agDw== 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=6dw25b5B9jjtJqmsCvd0LpMJ1lo7EMy8Nlohi8a73jk=; b=F4frreqoNzm53thaxc+M9QgpUT30e2Vc+a0Gc9v5rUBM9jDrPMLiShU/sOpxhE7Itq sC/h2VqLcW7RhejIMm8kLxRIomghyS/l8lSed+eGy9UVXTyDGvlXSqiPcpEjEBN1LP0J Itg/g3pLgKvSGFJHoSAqRQL3V+XL2xm6gFGDpNtC5CGOuTyAEQpj8/X+w4smbHMV4BXG e24eQFUXt/wyCHd/Gsv0et6r4BJLEN3TUUwcILSslzcngaIPzwziuPH2fzoLwNJX6/yp 0aUn2qSdEUlSJp7dUSGJQ2xjT8v7REZelPHrhziOwbsuGysCKFXPyI0+G1IYzBUgT562 wjpQ== X-Gm-Message-State: AOAM530j5tYYwblnwVhsRnLO4b75TancVvoRcFQ60Qgak5xMPRZL4unb GInvveiwkCA8hwcLI3+fG+EqOO9FLQQIHw== X-Google-Smtp-Source: ABdhPJwOPwZZrmo64ZFFIF19lfCblAV/R3PL4qRfN/g9qcju0QgvYfkg6g7UlG+Nc1UacAL9IX139Q== X-Received: by 2002:adf:f68a:: with SMTP id v10mr6442672wrp.366.1624563631126; Thu, 24 Jun 2021 12:40:31 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id y20sm9286057wmi.31.2021.06.24.12.40.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 24 Jun 2021 12:40: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 v3 1/3] bundle doc: rewrite the "DESCRIPTION" section Date: Thu, 24 Jun 2021 21:40:26 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.610.gd639e370050 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 | 43 +++++++++++++++++++++++------------- 1 file changed, 28 insertions(+), 15 deletions(-) diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 53804cad4b6..1b02f8b7468 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -18,21 +18,34 @@ SYNOPSIS DESCRIPTION ----------- -Some workflows require that one or more branches of development on one -machine be replicated on another machine, but the two machines cannot -be directly connected, and therefore the interactive Git protocols (git, -ssh, http) cannot be used. - -The 'git bundle' command packages objects and references in an archive -at the originating machine, which can then be imported into another -repository using 'git fetch', 'git pull', or 'git clone', -after moving the archive by some means (e.g., by sneakernet). - -As no -direct connection between the repositories exists, the user must specify a -basis for the bundle that is held by the destination repository: the -bundle assumes that all objects in the basis are already in the -destination repository. +Create, unpack, and manipulate "bundle" files. Bundles are used for +the "offline" transfer of Git objects without an active "server" +sitting on the other side of the network connection. + +They can be used to create both incremental and full backups of a +repository, and to relay the state of the references in one repository +to another. + +Other git commands that understand protocols such as `ssh://` and +`https://` can also operate on bundle files. It is possible +linkgit:git-clone[1] a new repository from a bundle, to use +linkgit:git-fetch[1] to fetch from one, and to list the references +contained within it with linkgit:git-ls-remote[1]. + +See the "EXAMPLES" section below for examples of how to use bundles. + +BUNDLE FORMAT +------------- + +Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a +header indicating what references are contained within the bundle. The +header is (mostly) in the format emitted by linkgit:git-show-ref[1]. + +Like the the packed archive format itself bundles can either be +self-contained or thin (see "--thin" in linkgit:git-pack-objects[1]). + +See link:technical/bundle-format.html[the `bundle-format` +documentation] for more details. OPTIONS ------- From patchwork Thu Jun 24 19:40: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: 12343099 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 B3C08C49EAB for ; Thu, 24 Jun 2021 19:40:41 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 9A7B36120D for ; Thu, 24 Jun 2021 19:40:41 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232838AbhFXTm7 (ORCPT ); Thu, 24 Jun 2021 15:42:59 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59392 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232797AbhFXTmx (ORCPT ); Thu, 24 Jun 2021 15:42:53 -0400 Received: from mail-wm1-x32a.google.com (mail-wm1-x32a.google.com [IPv6:2a00:1450:4864:20::32a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9C550C06175F for ; Thu, 24 Jun 2021 12:40:33 -0700 (PDT) Received: by mail-wm1-x32a.google.com with SMTP id n23so4768696wms.2 for ; Thu, 24 Jun 2021 12:40: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=j3BHz3R6ao2lRXBxIoaaC6tGq4r+WR/zyqTWR5GVT18=; b=J5OeYfd+XrML5qT43nCYOo/hTyDX9xPep0MZdkSnXJcwKyZurfm6HzPMeOFCranuNC 33bBBwvfcifGaMhiXEKjG6e/j/B7vHGpuwFZFYfMUmH1ZTPA3nOkZXbR3SU4sW2/nspP a1C/328NNYmUm2wrCCWpwHRzJFbd0q/VTp0E2ThmDksedBcabi032NvjIsyy1MaITIDe lx26xVsM7z1VYQDfq+dklepC3gtRzMVR+I/t29bqPL7aML7cGfJIW/8rxLDcUbrb32fr fRolzwXakMXb2IdeSAAlhXnTKUSgZXKa+S99sDHHjosvd68i6GjVVMzLLUzhRnAe4g2e 6COw== 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=j3BHz3R6ao2lRXBxIoaaC6tGq4r+WR/zyqTWR5GVT18=; b=kTLNgkPFeddoeRSWUuRshS9Gbw+brZQl5svF3pqpZBSQ8e2RsxqjMfzvT2TxMucx9B 3ZMGxAOQM78C4XDLXuEWAcaUrSQlxg7uwF/VlYpZ//9knGzR3bIPzT4T05MnrYNYOm1y VVOQCUt8bR32N2+5bwn7PqYWSdVo/LEJTqbTLy1IHchGdztZ9Qjbs4IaFRyjZ0Yu8AOp Z9AWqxG+gC7l6quoTHVVRXkMN6IXwGW6Q9lRE8eUT+dNSVfFJfTB3LVr9t7yrHe7UzK/ iVH0dvbSf0UWCzsVKwZWwO6yl5v5s2tameD7Id3veAHsvW2IMH7eV9qntZCW/DHEXnMc l0MQ== X-Gm-Message-State: AOAM530YL3nPl/snzIiA6xdzh3nQyVJRO2C8RiWIsBGe/XXNBqc1aJ3Y 2Kiu5GCdUOXEmdTWHj/3N8j8HSnPm9XPfg== X-Google-Smtp-Source: ABdhPJx7ZcLsDLlMpTDKudrxPp4+I2U5a1Luav5LNtabja1GS515Jx9fYoffEoy3oxfAvs2pucik4g== X-Received: by 2002:a1c:35c2:: with SMTP id c185mr6206173wma.126.1624563631960; Thu, 24 Jun 2021 12:40:31 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id y20sm9286057wmi.31.2021.06.24.12.40.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 24 Jun 2021 12:40: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 v3 2/3] bundle doc: split out thin v.s. not discussion from Date: Thu, 24 Jun 2021 21:40:27 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.610.gd639e370050 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 "thin 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 | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 1b02f8b7468..f231f42b12f 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -42,7 +42,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. @@ -139,7 +140,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. +OPEN (THIN) 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). + +Another name for "open" bundles might be "thin bundles", as in the +`--thin` option to linkgit:git-pack-objects[1]. Under the hood that's +what `git bundle create` uses to write bundles. When thin 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. @@ -152,6 +166,11 @@ 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 ``. +See the the `--thin` option to linkgit:git-pack-objects[1] noted +above, and the discussion of "thin pack" in +link:technical/pack-format.html[the pack format documentation] for +further details. + EXAMPLES -------- From patchwork Thu Jun 24 19:40: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: 12343101 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 BB13AC49EA6 for ; Thu, 24 Jun 2021 19:40:42 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id A2A89613EC for ; Thu, 24 Jun 2021 19:40:42 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232847AbhFXTnB (ORCPT ); Thu, 24 Jun 2021 15:43:01 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59398 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232825AbhFXTmz (ORCPT ); Thu, 24 Jun 2021 15:42:55 -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 5FF0BC061760 for ; Thu, 24 Jun 2021 12:40:34 -0700 (PDT) Received: by mail-wr1-x429.google.com with SMTP id a13so7919447wrf.10 for ; Thu, 24 Jun 2021 12:40: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=1qh1rvSpNTAGWtdVlA45nwWwTA5iQ5jldTBdt6gytmE=; b=Ld4p75CRfCgwuz/VMjZh8URaX+JF67O/7aebh7ge+Q5rxxgPrFUtpdeP4ml12SXTOM SD89/Fq/A+/q3VeX+Z/7sXahedbSUaDsLfn3d23kdVcfWPqNk8ViDyPGwx9t0HsHysv7 rJzPJ4ffa60MnpFNR4kAHI0iFOeECC9o45XkE/CVRpCLqkulktW64J1qKJBhQ3Ve8sBL BafFNNo5koHiD2nEdnIsRmMdHnpx+3lo65gT46GgZa6tI600sqbkhgfbFcsZKSCq5Xyz yJG0VRkkDvGK4Qrm2zKZ3NhfJbuJzwZId7DeAJ0dThJGvVvbLYEHvcUTgPbgFDkqUvWS SbuA== 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=1qh1rvSpNTAGWtdVlA45nwWwTA5iQ5jldTBdt6gytmE=; b=LfxCZBiSlFlN9sWIipWpqsJIRI/nYLawY6lOM4ujT9ImPDvg+Q+aqjCFPMGbU80pIL IQiBmkM02phxXFJ8EHwKaO0bGc1dP+1a6bH84VH7ujAn+1KJSU/zUqmBFOV97Jg2OBHZ q6l5lsoB9ereZZ9nM5FV+Lu6xL/rvLpEvwfpigj4VEdB74HBjOn11E9ZlvLXOoSRA+65 IYBeO+c89iTIiPIRY/d6gKs5fufBQFlHjvscNN4GH9Oq/IYWuIxRWwBjmVITTrowznDE 0xnAaoBfy0OexEl+JyAUHbd6lYOR9jTPikh2hM8VZcFKdCnMwSVB7u3+IyWst7uAwf7d QzxA== X-Gm-Message-State: AOAM533BzjICnVokbNyUGp6ERWA4RBS1d/B6J51persHoU6uFKciiaE1 PDbcVTWDb4tmr8Wk/KzjDzWGMym/VIvipA== X-Google-Smtp-Source: ABdhPJy4cFv5eUm3s4WgKXOMrW+LLfon6FaHUSvMi3+Snwp7QaK1dNNh1EKU7Y7H0haf+9Un/K60ug== X-Received: by 2002:a5d:508d:: with SMTP id a13mr6401607wrt.267.1624563632764; Thu, 24 Jun 2021 12:40:32 -0700 (PDT) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id y20sm9286057wmi.31.2021.06.24.12.40.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 24 Jun 2021 12:40: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 v3 3/3] bundle doc: elaborate on rev<->ref restriction Date: Thu, 24 Jun 2021 21:40:28 +0200 Message-Id: X-Mailer: git-send-email 2.32.0.610.gd639e370050 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 f231f42b12f..5674e18155a 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -131,14 +131,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 (THIN) AND CLOSED BUNDLES ------------------------------