From patchwork Fri Apr 22 02:32:18 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Elijah Newren X-Patchwork-Id: 12822674 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 3338CC433EF for ; Fri, 22 Apr 2022 02:32:34 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1443378AbiDVCfY (ORCPT ); Thu, 21 Apr 2022 22:35:24 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:36244 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1443375AbiDVCfX (ORCPT ); Thu, 21 Apr 2022 22:35:23 -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 3799B4B421 for ; Thu, 21 Apr 2022 19:32:31 -0700 (PDT) Received: by mail-wr1-x434.google.com with SMTP id c10so9081058wrb.1 for ; Thu, 21 Apr 2022 19:32:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:fcc :content-transfer-encoding:mime-version:to:cc; bh=ddKKUtypkHQnlEezFWPhcKPgt68JnCsvp2du9u1RLkI=; b=NPkwqKBkeLqhATuavayCJ/gZb9u7H/7XTohBS1OBl2AtQJWnhN9ftSm9orX9xz12dq 4sodibLNtpP28KRb5TWciMypApzjNhytf61vj5cN2QFpFE/YLjXWiN5TZKnIULZQECQg REDzkmpc3EEdRQPfRDUwenY0DAOYeWU/tZc2QDPv3smSjTA+BQBQJDD6eG/1psY5QQ3b YXzaeF7WCD0omfq0H7+Et3fGd30xMWWFAVDBfTyWJH2MJb5sOm9WHblwuKsPnTDljUrV JQcXWMzLSEfAc63RMfGoJXw+xfMKj3Z4bUO7jDPBnVAkNclzpzgFFJEKiZ9koexB3Mcu tqcA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:fcc:content-transfer-encoding:mime-version:to:cc; bh=ddKKUtypkHQnlEezFWPhcKPgt68JnCsvp2du9u1RLkI=; b=1FTnFuNX7s2ugPDk+vLcVC7KdY+kh3HVmrqCnErpyXi8yyY9q1qgTgF8OnshFYc2As DmIlngHwPIH5v1JwmhiVbRK9ltj6p0PpP5FeU2WEez0bUQ0CD+Kz0mjjQEvlvN4ONP0P 3tTNKCF4MRdJ3Mv4tu2Wwj2rFnp1U+VVzSxu0MfDydmG1Oe3tLwSnvwcvZyRpwuaRQAp ZJPGXOUePgAaRSJNz1qdEqHxqNEluHPCjMgNOeT3Y9I38nyR/xKHHrSmixRiRCMX4rO7 1yoGqPBe/opcXAoy7pd8wxsxiKiJWjYkt4ygrzzy+OcVOJ/aC6g0s6fkmX7a6XXw4xGe AzGA== X-Gm-Message-State: AOAM5326rEjxZUvstbmALfFrJVkIGu8+RPkBkjEDB4hi/ngONahsH8Oi OY1nbc9lxATziskdh7K7S/kR1fQriz0= X-Google-Smtp-Source: ABdhPJzYFTtSqk82lQwYAAcMt75lumgCjN8wJuB6cu6/bov8jMKq1B+GR7p3CXprjY75fD34nUQKOA== X-Received: by 2002:adf:f98e:0:b0:207:9eed:60d8 with SMTP id f14-20020adff98e000000b002079eed60d8mr1773431wrr.566.1650594749391; Thu, 21 Apr 2022 19:32:29 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id m2-20020a056000008200b00207a6f32833sm599442wrx.117.2022.04.21.19.32.28 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Apr 2022 19:32:28 -0700 (PDT) Message-Id: <05dba7069c5e0c1aec1a7206f9cbea593d8d68cb.1650594746.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Fri, 22 Apr 2022 02:32:18 +0000 Subject: [PATCH v3 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Victoria Dye , Lessley Dennington , Derrick Stolee , Elijah Newren , Elijah Newren , Elijah Newren Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Elijah Newren From: Elijah Newren Add an explicit --no-cone to several sparse-checkout invocations in preparation for changing the default to cone mode. Signed-off-by: Elijah Newren --- t/t1091-sparse-checkout-builtin.sh | 15 ++++++++------- t/t3602-rm-sparse-checkout.sh | 6 +++--- t/t3705-add-sparse-checkout.sh | 4 ++-- t/t6428-merge-conflicts-sparse.sh | 4 ++-- t/t7002-mv-sparse-checkout.sh | 2 +- t/t7012-skip-worktree-writing.sh | 2 +- 6 files changed, 17 insertions(+), 16 deletions(-) diff --git a/t/t1091-sparse-checkout-builtin.sh b/t/t1091-sparse-checkout-builtin.sh index 9a900310186..de1ec89007d 100755 --- a/t/t1091-sparse-checkout-builtin.sh +++ b/t/t1091-sparse-checkout-builtin.sh @@ -72,7 +72,7 @@ test_expect_success 'git sparse-checkout list (populated)' ' ' test_expect_success 'git sparse-checkout init' ' - git -C repo sparse-checkout init && + git -C repo sparse-checkout init --no-cone && cat >expect <<-\EOF && /* !/*/ @@ -111,6 +111,7 @@ test_expect_success 'init with existing sparse-checkout' ' test_expect_success 'clone --sparse' ' git clone --sparse "file://$(pwd)/repo" clone && + git -C clone sparse-checkout reapply --no-cone && git -C clone sparse-checkout list >actual && cat >expect <<-\EOF && /* @@ -124,7 +125,7 @@ test_expect_success 'switching to cone mode with non-cone mode patterns' ' git init bad-patterns && ( cd bad-patterns && - git sparse-checkout init && + git sparse-checkout init --no-cone && git sparse-checkout add dir && git config --worktree core.sparseCheckoutCone true && test_must_fail git sparse-checkout add dir 2>err && @@ -402,7 +403,7 @@ test_expect_success 'revert to old sparse-checkout on empty update' ' git sparse-checkout set nothing 2>err && test_i18ngrep ! "Sparse checkout leaves no entry on working directory" err && test_i18ngrep ! ".git/index.lock" err && - git sparse-checkout set file + git sparse-checkout set --no-cone file ) ' @@ -424,7 +425,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status' git clone repo dirty && echo dirty >dirty/folder1/a && - git -C dirty sparse-checkout init 2>err && + git -C dirty sparse-checkout init --no-cone 2>err && test_i18ngrep "warning.*The following paths are not up to date" err && git -C dirty sparse-checkout set /folder2/* /deep/deeper1/* 2>err && @@ -435,7 +436,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status' test_must_be_empty err && git -C dirty reset --hard && - git -C dirty sparse-checkout init && + git -C dirty sparse-checkout init --no-cone && git -C dirty sparse-checkout set /folder2/* /deep/deeper1/* && test_path_is_missing dirty/folder1/a && git -C dirty sparse-checkout disable && @@ -451,7 +452,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat EOF git -C unmerged update-index --index-info err && + git -C unmerged sparse-checkout init --no-cone 2>err && test_i18ngrep "warning.*The following paths are unmerged" err && git -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* 2>err && @@ -462,7 +463,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat test_i18ngrep "warning.*The following paths are unmerged" err && git -C unmerged reset --hard && - git -C unmerged sparse-checkout init && + git -C unmerged sparse-checkout init --no-cone && git -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* && git -C unmerged sparse-checkout disable ' diff --git a/t/t3602-rm-sparse-checkout.sh b/t/t3602-rm-sparse-checkout.sh index 034ec010910..08580fd3dcc 100755 --- a/t/t3602-rm-sparse-checkout.sh +++ b/t/t3602-rm-sparse-checkout.sh @@ -30,7 +30,7 @@ test_expect_success 'setup' " for opt in "" -f --dry-run do test_expect_success "rm${opt:+ $opt} does not remove sparse entries" ' - git sparse-checkout set a && + git sparse-checkout set --no-cone a && test_must_fail git rm $opt b 2>stderr && test_cmp b_error_and_hint stderr && git ls-files --error-unmatch b @@ -118,7 +118,7 @@ test_expect_success 'can remove files from non-sparse dir' ' test_commit w/f && test_commit x/y/f && - git sparse-checkout set w !/x y/ && + git sparse-checkout set --no-cone w !/x y/ && git rm w/f.t x/y/f.t 2>stderr && test_must_be_empty stderr ' @@ -128,7 +128,7 @@ test_expect_success 'refuse to remove non-skip-worktree file from sparse dir' ' git sparse-checkout disable && mkdir -p x/y/z && test_commit x/y/z/f && - git sparse-checkout set !/x y/ !x/y/z && + git sparse-checkout set --no-cone !/x y/ !x/y/z && git update-index --no-skip-worktree x/y/z/f.t && test_must_fail git rm x/y/z/f.t 2>stderr && diff --git a/t/t3705-add-sparse-checkout.sh b/t/t3705-add-sparse-checkout.sh index 95609046c61..2bade9e804f 100755 --- a/t/t3705-add-sparse-checkout.sh +++ b/t/t3705-add-sparse-checkout.sh @@ -166,7 +166,7 @@ test_expect_success 'do not warn when pathspec matches dense entries' ' test_expect_success 'git add fails outside of sparse-checkout definition' ' test_when_finished git sparse-checkout disable && test_commit a && - git sparse-checkout init && + git sparse-checkout init --no-cone && git sparse-checkout set a && echo >>sparse_entry && @@ -208,7 +208,7 @@ test_expect_success 'add obeys advice.updateSparsePath' ' ' test_expect_success 'add allows sparse entries with --sparse' ' - git sparse-checkout set a && + git sparse-checkout set --no-cone a && echo modified >sparse_entry && test_must_fail git add sparse_entry && test_sparse_entry_unchanged && diff --git a/t/t6428-merge-conflicts-sparse.sh b/t/t6428-merge-conflicts-sparse.sh index 142c9aaabc5..064be1b629e 100755 --- a/t/t6428-merge-conflicts-sparse.sh +++ b/t/t6428-merge-conflicts-sparse.sh @@ -87,7 +87,7 @@ test_expect_success 'conflicting entries written to worktree even if sparse' ' test_path_is_file numerals && git sparse-checkout init && - git sparse-checkout set README && + git sparse-checkout set --no-cone README && test_path_is_file README && test_path_is_missing numerals && @@ -123,7 +123,7 @@ test_expect_success 'present-despite-SKIP_WORKTREE handled reasonably' ' test_path_is_file numerals && git sparse-checkout init && - git sparse-checkout set README && + git sparse-checkout set --no-cone README && test_path_is_file README && test_path_is_missing numerals && diff --git a/t/t7002-mv-sparse-checkout.sh b/t/t7002-mv-sparse-checkout.sh index 1d3d2aca21c..f0f7cbfcdb7 100755 --- a/t/t7002-mv-sparse-checkout.sh +++ b/t/t7002-mv-sparse-checkout.sh @@ -27,7 +27,7 @@ test_expect_success 'setup' " test_expect_success 'mv refuses to move sparse-to-sparse' ' test_when_finished rm -f e && git reset --hard && - git sparse-checkout set a && + git sparse-checkout set --no-cone a && touch b && test_must_fail git mv b e 2>stderr && cat sparse_error_header >expect && diff --git a/t/t7012-skip-worktree-writing.sh b/t/t7012-skip-worktree-writing.sh index cb9f1a6981e..cd5c20fe51b 100755 --- a/t/t7012-skip-worktree-writing.sh +++ b/t/t7012-skip-worktree-writing.sh @@ -151,7 +151,7 @@ test_expect_success 'stash restore in sparse checkout' ' git stash push && - git sparse-checkout set subdir && + git sparse-checkout set --no-cone subdir && # Ensure after sparse-checkout we only have expected files cat >expect <<-EOF && From patchwork Fri Apr 22 02:32:19 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Elijah Newren X-Patchwork-Id: 12822675 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1CDD8C433F5 for ; Fri, 22 Apr 2022 02:32:36 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1443381AbiDVCfZ (ORCPT ); Thu, 21 Apr 2022 22:35:25 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:36264 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1443376AbiDVCfY (ORCPT ); Thu, 21 Apr 2022 22:35:24 -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 4A7054B412 for ; Thu, 21 Apr 2022 19:32:32 -0700 (PDT) Received: by mail-wr1-x429.google.com with SMTP id c10so9081102wrb.1 for ; Thu, 21 Apr 2022 19:32:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:fcc :content-transfer-encoding:mime-version:to:cc; bh=tuHXimBwYebEU6fghwiMtrYIrfgCUPrazOHafCyQMTY=; b=VysN0HdK/9shrHabMauGCtN0/Ywq/bWxmJ1gprMblsrp8KYNLX++DUwh66uwAEs7mt TU1q/99E9AxwjaGLbKYz+vjYsAyExxY9JMlOKVPeCzR3ZXQO66LE4TIEb8eOsxonVsmY Nw4tOdME7kMKsEnVhyPNcqzAmqVNhEKjAMcxKgxAgZIrXEhQg4hwu+JGb2+ol8K7/+5L Tl/IXwUDCsqYK1qRrXBNZNtidVu4kA8pJY3yZ6OO8c/sW/eeDnNUaXDlvYs1v5RMIV+n BKR8o19DFlKq7sykup1kbaWNyG9j2MoOYIOpFZBvkPuDx82igJqQ8dOF1PBitEpb2T2i SeUQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:fcc:content-transfer-encoding:mime-version:to:cc; bh=tuHXimBwYebEU6fghwiMtrYIrfgCUPrazOHafCyQMTY=; b=d6voFe7v0k3hCDzavSb9YCtDY6UigPYtmu4fVici87XKipmGBTzKeDPlUs6Tm85bvL 9KemU/5BSXdSkgFQIfQYSpaSLKNkSCZ4xeAGUFp4dGvXgTaIo+7XHd8awTx19f6hfBTs 8YfS03skcwiUoME7FHkYQq1bDBUoaqsPHRu7beFP2cUKdXZM/FIvwKosoYWnQr96kFfm iuM3G+MavsYy3MVaUNPKqj3RBLPywloHYy9/kGKcNgbOP8Xti1bmjf8wbHnx/3b8uxoa CEeJZTJ7DyPE61eftXuZAkU4HTbDWfrXqHIs9mYKoce98gwQlI2VZIDqdmiZ/784Ss5H KPaQ== X-Gm-Message-State: AOAM5321rbdETa3So/ouYv9SAnLiW3gllUSU5LNhIdEteSLZCUTuyQa4 +b1OBkVNeKgVi/iwsDOMoC1atotiZ5w= X-Google-Smtp-Source: ABdhPJxdSXw7MQYKHpiiJyvv17pMHMDXJwfcKycFWbZPTdodrw8KdIVUnCwJ3Z37jvIqarcj+O4R/A== X-Received: by 2002:a5d:6dab:0:b0:20a:8684:cbc1 with SMTP id u11-20020a5d6dab000000b0020a8684cbc1mr1746464wrs.482.1650594750440; Thu, 21 Apr 2022 19:32:30 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id a4-20020a056000188400b0020a9ec6e8e3sm585146wri.55.2022.04.21.19.32.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Apr 2022 19:32:30 -0700 (PDT) Message-Id: In-Reply-To: References: Date: Fri, 22 Apr 2022 02:32:19 +0000 Subject: [PATCH v3 2/9] sparse-checkout: make --cone the default Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Victoria Dye , Lessley Dennington , Derrick Stolee , Elijah Newren , Elijah Newren , Elijah Newren Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Elijah Newren From: Elijah Newren Make cone mode the default, and update the documentation accordingly. Signed-off-by: Elijah Newren --- Documentation/config/core.txt | 6 ++++-- Documentation/git-sparse-checkout.txt | 20 ++++++++++---------- builtin/sparse-checkout.c | 2 +- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index c04f62a54a1..03cf075821b 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -615,8 +615,10 @@ core.sparseCheckout:: core.sparseCheckoutCone:: Enables the "cone mode" of the sparse checkout feature. When the - sparse-checkout file contains a limited set of patterns, then this - mode provides significant performance advantages. See + sparse-checkout file contains a limited set of patterns, this + mode provides significant performance advantages. The "non + cone mode" can be requested to allow specifying a more flexible + patterns by setting this variable to 'false'. See linkgit:git-sparse-checkout[1] for more information. core.abbrev:: diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 88e55f432f3..7308e744c57 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -22,8 +22,8 @@ present, or undo and go back to having all tracked files present in the working copy. The subset of files is chosen by providing a list of directories in -cone mode (which is recommended), or by providing a list of patterns -in non-cone mode. +cone mode (the default), or by providing a list of patterns in +non-cone mode. When in a sparse-checkout, other Git commands behave a bit differently. For example, switching branches will not update paths outside the @@ -60,7 +60,7 @@ When the `--stdin` option is provided, the directories or patterns are read from standard in as a newline-delimited list instead of from the arguments. + -When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the +When `--cone` is passed or `core.sparseCheckoutCone` is not false, the input list is considered a list of directories. This allows for better performance with a limited set of patterns (see 'CONE PATTERN SET' below). The input format matches the output of `git ls-tree @@ -68,10 +68,9 @@ SET' below). The input format matches the output of `git ls-tree double quote (") as C-style quoted strings. Note that the set command will write patterns to the sparse-checkout file to include all files contained in those directories (recursively) as well as files that are -siblings of ancestor directories. This may become the default in the -future; --no-cone can be passed to request non-cone mode. +siblings of ancestor directories. + -When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled, +When `--no-cone` is passed or `core.sparseCheckoutCone` is set to false, the input list is considered a list of patterns. This mode is harder to use and less performant, and is thus not recommended. See the "Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern @@ -227,10 +226,11 @@ patterns. The resulting sparse-checkout file is now Here, order matters, so the negative patterns are overridden by the positive patterns that appear lower in the file. -If `core.sparseCheckoutCone=true`, then Git will parse the sparse-checkout file -expecting patterns of these types. Git will warn if the patterns do not match. -If the patterns do match the expected format, then Git will use faster hash- -based algorithms to compute inclusion in the sparse-checkout. +Unless `core.sparseCheckoutCone` is explicitly set to `false`, Git will +parse the sparse-checkout file expecting patterns of these types. Git will +warn if the patterns do not match. If the patterns do match the expected +format, then Git will use faster hash-based algorithms to compute inclusion +in the sparse-checkout. In the cone mode case, the `git sparse-checkout list` subcommand will list the directories that define the recursive patterns. For the example sparse-checkout diff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c index 5518ed47f6c..61b7a7519bb 100644 --- a/builtin/sparse-checkout.c +++ b/builtin/sparse-checkout.c @@ -397,7 +397,7 @@ static int update_modes(int *cone_mode, int *sparse_index) /* Set cone/non-cone mode appropriately */ core_apply_sparse_checkout = 1; - if (*cone_mode == 1) { + if (*cone_mode == 1 || *cone_mode == -1) { mode = MODE_CONE_PATTERNS; core_sparse_checkout_cone = 1; } else { From patchwork Fri Apr 22 02:32:20 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Elijah Newren X-Patchwork-Id: 12822677 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6819BC433F5 for ; Fri, 22 Apr 2022 02:32:48 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1443400AbiDVCfi (ORCPT ); Thu, 21 Apr 2022 22:35:38 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:36300 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1443375AbiDVCfZ (ORCPT ); Thu, 21 Apr 2022 22:35:25 -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 8E8E24B425 for ; Thu, 21 Apr 2022 19:32:33 -0700 (PDT) Received: by mail-wm1-x32b.google.com with SMTP id l62-20020a1c2541000000b0038e4570af2fso4557138wml.5 for ; Thu, 21 Apr 2022 19:32:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:fcc :content-transfer-encoding:mime-version:to:cc; bh=q6Ij5s6GRHeJKZ845PeuupKqm1meRfzSIPmF3t8zdRE=; b=KGRDhlyIyAW+B11qv+pIxDQgaJRlF3h2Ug08W2FFqeVpf1Tbo6sFAzvf7neg8tyZAE FSrzB7CLxEKPI87Ogdku9aYaO+HIBsUfJMj/9EfSGauzRlDn0bSuEHZfDjEj/KTfkL3z 3lqSIbR10wqaASUAvh3UvwJsmPT0PCKaufuyu3MhWgwSDv/y1uS0ydnIFI59xpTkMR4R G5Z2cvirjBr1jozCoH3TFu0ux6LpjPOIddyeoDq57SMd/S0+z1l9NIci4LYK7c+AcWC0 K4kc+JQ30c5dGpnGK1sUcEhi4ZtfdFzMxXOtIQLnfkmmRU1cvWygyoVE1Ie/yDBw/eXN TNVQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:fcc:content-transfer-encoding:mime-version:to:cc; bh=q6Ij5s6GRHeJKZ845PeuupKqm1meRfzSIPmF3t8zdRE=; b=7ukzF3DA4QdhDEUVxI1lPVUrBrKe9/xZhQckQRUAQQsTKz3Z0iOgGqx/pB8nb8e3IN 4mvh83Mtq5/LXw6s0j/2mMBIf5MTc4cE9Pk5CFhJDmMQxmLKvr+0vv/7BOtamVt6ZzTo WvkGl3EZtVOAFwkc18f5HY3SUgGgsv2xY7VS4nXSgcOjgGB2a2N9Uui29+znJOsgxrsV fbRbilyDBptka1xv6kJGU8VPittPGmlJ1kgNM2xd8Y9aRei1WHv3f3t0HB5wMmnggKYM IiTOKLlcTrxdOg30UdnL43eV1i4B6f9+QWz3sI/CBaSy1x55kdvEaQvlS36EcLD8fYcc 6wDQ== X-Gm-Message-State: AOAM531IBCqgiFMsiuq93NsKW/dYcPrTj1Y9GOC++OigBfXcZ77Sc4OJ e/2EJxDOR9HXbI2RtIJqM2sxgqkXJf4= X-Google-Smtp-Source: ABdhPJx0EL0ztorVPPbEDbfUpXKD9c4wT3K2lTzT87Z6QGl96jj/9QFAPXE18JSIY3/pov3Q1qUKsQ== X-Received: by 2002:a1c:43c6:0:b0:38e:bb4c:6e1a with SMTP id q189-20020a1c43c6000000b0038ebb4c6e1amr11142002wma.111.1650594751508; Thu, 21 Apr 2022 19:32:31 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id n38-20020a05600c502600b00393d946aef4sm78543wmr.10.2022.04.21.19.32.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Apr 2022 19:32:30 -0700 (PDT) Message-Id: In-Reply-To: References: Date: Fri, 22 Apr 2022 02:32:20 +0000 Subject: [PATCH v3 3/9] git-sparse-checkout.txt: wording updates for the cone mode default Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Victoria Dye , Lessley Dennington , Derrick Stolee , Elijah Newren , Elijah Newren , Elijah Newren Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Elijah Newren From: Elijah Newren Now that cone mode is the default, we'd like to focus on the arguments to set/add being directories rather than patterns, and it probably makes sense to provide an earlier heads up that files from leading directories get included as well. Signed-off-by: Elijah Newren --- Documentation/git-sparse-checkout.txt | 31 +++++++++++++-------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 7308e744c57..b5db812f09e 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -44,9 +44,9 @@ COMMANDS Enable the necessary sparse-checkout config settings (`core.sparseCheckout`, `core.sparseCheckoutCone`, and `index.sparse`) if they are not already set to the desired values, - and write a set of patterns to the sparse-checkout file from the - list of arguments following the 'set' subcommand. Update the - working directory to match the new patterns. + populate the sparse-checkout file from the list of arguments + following the 'set' subcommand, and update the working directory to + match. + To ensure that adjusting the sparse-checkout settings within a worktree does not alter the sparse-checkout settings in other worktrees, the 'set' @@ -60,15 +60,15 @@ When the `--stdin` option is provided, the directories or patterns are read from standard in as a newline-delimited list instead of from the arguments. + -When `--cone` is passed or `core.sparseCheckoutCone` is not false, the -input list is considered a list of directories. This allows for -better performance with a limited set of patterns (see 'CONE PATTERN -SET' below). The input format matches the output of `git ls-tree ---name-only`. This includes interpreting pathnames that begin with a -double quote (") as C-style quoted strings. Note that the set command -will write patterns to the sparse-checkout file to include all files -contained in those directories (recursively) as well as files that are -siblings of ancestor directories. +By default, the input list is considered a list of directories, matching +the output of `git ls-tree -d --name-only`. This includes interpreting +pathnames that begin with a double quote (") as C-style quoted strings. +Note that all files under the specified directories (at any depth) will +be included in the sparse checkout, as well as files that are siblings +of either the given directory or any of its ancestors (see 'CONE PATTERN +SET' below for more details). In the past, this was not the default, +and `--cone` needed to be specified or `core.sparseCheckoutCone` needed +to be enabled. + When `--no-cone` is passed or `core.sparseCheckoutCone` is set to false, the input list is considered a list of patterns. This mode is harder @@ -208,10 +208,9 @@ the following patterns: This says "include everything in root, but nothing two levels below root." When in cone mode, the `git sparse-checkout set` subcommand takes a list of -directories instead of a list of sparse-checkout patterns. In this mode, -the command `git sparse-checkout set A/B/C` sets the directory `A/B/C` as -a recursive pattern, the directories `A` and `A/B` are added as parent -patterns. The resulting sparse-checkout file is now +directories. In this mode, the command `git sparse-checkout set A/B/C` sets +the directory `A/B/C` as a recursive pattern, the directories `A` and `A/B` +are added as parent patterns. The resulting sparse-checkout file is now ---------------- /* From patchwork Fri Apr 22 02:32:21 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Elijah Newren X-Patchwork-Id: 12822678 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 46E2CC433EF for ; Fri, 22 Apr 2022 02:32:53 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1443388AbiDVCfj (ORCPT ); Thu, 21 Apr 2022 22:35:39 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:36324 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1443384AbiDVCf0 (ORCPT ); Thu, 21 Apr 2022 22:35:26 -0400 Received: from mail-wr1-x430.google.com (mail-wr1-x430.google.com [IPv6:2a00:1450:4864:20::430]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 5FA884B40C for ; Thu, 21 Apr 2022 19:32:34 -0700 (PDT) Received: by mail-wr1-x430.google.com with SMTP id m14so9063822wrb.6 for ; Thu, 21 Apr 2022 19:32:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:fcc :content-transfer-encoding:mime-version:to:cc; bh=uMMwrMi3Zq1sV2E4egHHhmRIH6diyDyXo7IxLvY/hWU=; b=IWoKzKqBxOt4N50V2raWRW4F8iTD/sNXRhyUmROP+xUBUQbQsCCPoUnggHhI90O0gv Z2C8i/IoD/2yBuqOXyB4TsG1l4CLTLXZiRYj/iASodlo/g8Gx4xeRwJBqCPTVZrgDX4H AASkgIR7sSn0Hp4uNoisatvK230tPFkNrviLR1Ui1KtpZWp3XmmQPfPmMH418gTPyYC+ t5LaHOz9+W9gDvpH6Ui+enfBkVr4UlrMZvdFdWPGASpbCjue1Wun8zhU9SJD+EmFEfmr /18Qa5vPNjLTiZ2ltvTgALRi5i+/MFyTgscS08ZwVetcG16DS34LFj5V78ojt+P55way pDPg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:fcc:content-transfer-encoding:mime-version:to:cc; bh=uMMwrMi3Zq1sV2E4egHHhmRIH6diyDyXo7IxLvY/hWU=; b=1saCIBJI15Kg3GHH11VrnywGzHI4onbpBQNV4YKhv355wKb07/wbaf2c6JfH4Z6fMb 0o2A4NJTThfB23sPWOH8e+y+ZAKXJtn7tql3FFzQpSKEGENRvEovJI1xBCLNXhBMdzu9 uXaEOLhCP8M0h+4+SI3uHHCNXhl9hs29NN9YQE/tQfF0PvjNvH/mtWiGga7lUIUl2feJ YwfV1t64DVw4LLTvrRYwCvSWIv7wB85W2lmB07bO2ZDn6MPU/sMtOReIs/CNVPdr/qzO jC41wszavowEYQyiaT5fb8+HM+RuM8j49WK1EMLafTIrESBWi7dBpXdwSh9+oLYtXJWh bqFQ== X-Gm-Message-State: AOAM531wYajwDr1dX9fL1ZSXyxEP6pK9Uw5yl2ZzBNH7uoyX4ez3NyGj hRaOPvnPnlSsKNfkgUAiA2WnrKnI+fo= X-Google-Smtp-Source: ABdhPJw1NJaIOLhC35xfoNdJoYZLDGKi3hyPkyHTef82yLgI4cqrDdiFcMe8HN5GhJyDAAJ59BsKMw== X-Received: by 2002:adf:e908:0:b0:207:a28e:b904 with SMTP id f8-20020adfe908000000b00207a28eb904mr1856311wrm.542.1650594752672; Thu, 21 Apr 2022 19:32:32 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id i11-20020a5d584b000000b0020a8d859e5fsm564968wrf.10.2022.04.21.19.32.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Apr 2022 19:32:32 -0700 (PDT) Message-Id: In-Reply-To: References: Date: Fri, 22 Apr 2022 02:32:21 +0000 Subject: [PATCH v3 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init' Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Victoria Dye , Lessley Dennington , Derrick Stolee , Elijah Newren , Elijah Newren , Elijah Newren Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Elijah Newren From: Elijah Newren The 'init' subcommand of sparse-checkout was deprecated in ba2f3f58ac ("git-sparse-checkout.txt: update to document init/set/reapply changes", 2021-12-14), but a couple places in the manual still assumed it was the primary way to use sparse-checkout. Correct them. Signed-off-by: Elijah Newren --- Documentation/git-sparse-checkout.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index b5db812f09e..8e80d1c7332 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -70,11 +70,11 @@ SET' below for more details). In the past, this was not the default, and `--cone` needed to be specified or `core.sparseCheckoutCone` needed to be enabled. + -When `--no-cone` is passed or `core.sparseCheckoutCone` is set to false, -the input list is considered a list of patterns. This mode is harder -to use and less performant, and is thus not recommended. See the -"Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern -Set" sections below for more details. +When `--no-cone` is passed, the input list is considered a list of +patterns. This mode is harder to use and less performant, and is thus +not recommended. See the "Sparse Checkout" section of +linkgit:git-read-tree[1] and the "Pattern Set" sections below for more +details. + Use the `--[no-]sparse-index` option to use a sparse index (the default is to not use it). A sparse index reduces the size of the @@ -196,9 +196,9 @@ In addition to the above two patterns, we also expect that all files in the root directory are included. If a recursive pattern is added, then all leading directories are added as parent patterns. -By default, when running `git sparse-checkout init`, the root directory is -added as a parent pattern. At this point, the sparse-checkout file contains -the following patterns: +By default, when running `git sparse-checkout set` with no directories +specified, the root directory is added as a parent pattern. At this +point, the sparse-checkout file contains the following patterns: ---------------- /* From patchwork Fri Apr 22 02:32:22 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Elijah Newren X-Patchwork-Id: 12822679 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 96354C433EF for ; Fri, 22 Apr 2022 02:32:55 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1443402AbiDVCfp (ORCPT ); Thu, 21 Apr 2022 22:35:45 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:36464 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1443387AbiDVCfg (ORCPT ); Thu, 21 Apr 2022 22:35:36 -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 5E8F54B423 for ; Thu, 21 Apr 2022 19:32:35 -0700 (PDT) Received: by mail-wm1-x32d.google.com with SMTP id m15-20020a7bca4f000000b0038fdc1394b1so7047483wml.2 for ; Thu, 21 Apr 2022 19:32:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:fcc :content-transfer-encoding:mime-version:to:cc; bh=Z/qpVU+nW5fs8WHL+S8XH0F0zKjx68eiiAimoVfSsfg=; b=UvNHs/fmRNgyqZ2EOW7Kq839z8ZcL5w8jx32Pu30yhY8qJTVsxcHa73E4pW6+2+1jM wa1VukNZAk5N9llSBZsIoDlkpXI8vAwib5wGOQgvmt2DcGO6rHyxWXSHs9YBTdNyvU6Y n3QclyEe/IZjRW3km5DSb0hWm7q4++ZvR8UXoGzEhnvwjHOoGu14Bo34mD4mPyEpJOYB wLgZN4BMtMFaTahO2CWlwpnr041u/0xziIHSyFpROHKZZrI7WapyGZNw7p8mBTHZyQft H9A145tV66fQnmMeGrgCEgWvM0uYn3E1EzA6+VEeC3a1Q6osg5at3pyk0eBwvecMJ3zy 3p2A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:fcc:content-transfer-encoding:mime-version:to:cc; bh=Z/qpVU+nW5fs8WHL+S8XH0F0zKjx68eiiAimoVfSsfg=; b=2czktufJqA0gjAC8XAcqeF8goGIDNKcXojEulTdsRx44HfvqBPHL49vuNkC7dgBA3d WT4yPc5/Ft74nPHGyNw4t7wPYsX3uMALxCt2ToZHQlr6cvWtBs2EK+48ucOpGBdFdLlM 7BWVrFYBAQ+5A+651yoA9kJAahauGdURZD8ptaJuaqO7AUwYrTcxmqzs72Sbyr3Lw9aL kcMwVSKyHplsWRue4swul6l8+WFWLRk0Gw/HaNYeFvuw/z37kiXEnFqSpC7Y2aSARbp3 Jh7jQFtRQTFMeYDPvyu1+/YZK1XO5L9O+SYsdgv/dX8ucXz9Sr5SHs3Fg/33BSAmPUmg Ewrw== X-Gm-Message-State: AOAM532MIwqWiW9KtMqi3f99y03euGvDcTJdPe7WXX5atDuCPRADWZbY fxvtAlHaOqDMnfmJFfCXTii/XToPUCk= X-Google-Smtp-Source: ABdhPJwnHp9qbkKLQBCQb2wuuu7GydFjIrs5k/cCn7wJ6CriBSjBIsIM2ZcMoYU7XhZpvv/Q01RFUQ== X-Received: by 2002:a1c:3846:0:b0:392:a3e7:3798 with SMTP id f67-20020a1c3846000000b00392a3e73798mr1918762wma.80.1650594753593; Thu, 21 Apr 2022 19:32:33 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id n68-20020a1c2747000000b0038e6b4d5395sm550317wmn.16.2022.04.21.19.32.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Apr 2022 19:32:33 -0700 (PDT) Message-Id: In-Reply-To: References: Date: Fri, 22 Apr 2022 02:32:22 +0000 Subject: [PATCH v3 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Victoria Dye , Lessley Dennington , Derrick Stolee , Elijah Newren , Elijah Newren , Elijah Newren Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Elijah Newren From: Elijah Newren With cone mode as the default, it makes sense to discuss it before non-cone mode. Also, the new default means we can just use directories in most cases and users do not need to understand patterns or their meanings. Let's take advantage of this to mark several sections as "INTERNALS", notifying the user that they do not need to know all those details in order to make use of the sparse-checkout command. Signed-off-by: Elijah Newren --- Documentation/git-sparse-checkout.txt | 48 +++++++++++++-------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 8e80d1c7332..2083e6df356 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -73,8 +73,8 @@ to be enabled. When `--no-cone` is passed, the input list is considered a list of patterns. This mode is harder to use and less performant, and is thus not recommended. See the "Sparse Checkout" section of -linkgit:git-read-tree[1] and the "Pattern Set" sections below for more -details. +linkgit:git-read-tree[1] and the "Internals...Pattern Set" sections +below for more details. + Use the `--[no-]sparse-index` option to use a sparse index (the default is to not use it). A sparse index reduces the size of the @@ -136,8 +136,8 @@ paths to pass to a subsequent 'set' or 'add' command. However, the disable command, so the easy restore of calling a plain `init` decreased in utility. -SPARSE CHECKOUT ---------------- +INTERNALS -- SPARSE CHECKOUT +---------------------------- "Sparse checkout" allows populating the working directory sparsely. It uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell Git @@ -161,24 +161,8 @@ To repopulate the working directory with all files, use the `git sparse-checkout disable` command. -FULL PATTERN SET ----------------- - -By default, the sparse-checkout file uses the same syntax as `.gitignore` -files. - -While `$GIT_DIR/info/sparse-checkout` is usually used to specify what -files are included, you can also specify what files are _not_ included, -using negative patterns. For example, to remove the file `unwanted`: - ----------------- -/* -!unwanted ----------------- - - -CONE PATTERN SET ----------------- +INTERNALS -- CONE PATTERN SET +----------------------------- The full pattern set allows for arbitrary pattern matches and complicated inclusion/exclusion rules. These can result in O(N*M) pattern matches when @@ -256,8 +240,24 @@ use `git add` and `git commit` to store them, then remove any remaining files manually to ensure Git can behave optimally. -SUBMODULES ----------- +INTERNALS -- FULL PATTERN SET +----------------------------- + +By default, the sparse-checkout file uses the same syntax as `.gitignore` +files. + +While `$GIT_DIR/info/sparse-checkout` is usually used to specify what +files are included, you can also specify what files are _not_ included, +using negative patterns. For example, to remove the file `unwanted`: + +---------------- +/* +!unwanted +---------------- + + +INTERNALS -- SUBMODULES +----------------------- If your repository contains one or more submodules, then submodules are populated based on interactions with the `git submodule` command. From patchwork Fri Apr 22 02:32:23 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Elijah Newren X-Patchwork-Id: 12822683 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id A65E5C433EF for ; Fri, 22 Apr 2022 02:33:01 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1443398AbiDVCfv (ORCPT ); Thu, 21 Apr 2022 22:35:51 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:36476 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1443389AbiDVCfg (ORCPT ); Thu, 21 Apr 2022 22:35:36 -0400 Received: from mail-wm1-x32f.google.com (mail-wm1-x32f.google.com [IPv6:2a00:1450:4864:20::32f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7B8804B434 for ; Thu, 21 Apr 2022 19:32:36 -0700 (PDT) Received: by mail-wm1-x32f.google.com with SMTP id n40-20020a05600c3ba800b0038ff1939b16so4567758wms.2 for ; Thu, 21 Apr 2022 19:32:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:fcc :content-transfer-encoding:mime-version:to:cc; bh=KTAYz2IoJo8jRWqSzJj6zyy/6mxRcObxkuZ5nQQCYcQ=; b=G4OFLwrDBcOGiSLnYFSpBR4AgP1egGlcZaJlElTDN1Agew5++dPBfKbaMTBCeaRaSV j1SjRb+a0XzZ1zM5MF+BvFRP3El6FawY/Eb2yiNKG2QtR7cPoagA82NdyqyQ8FdD6c57 n1ckhBJS+3Wm0k3CuqFtMHyt3HHVuDG0HP8c3y1+wWrPEV+Kn01SJAQlWnqd+sRVve1D HCWHvqCDZ9VLxAplr2yxAua0pfuLhF3ZbnvfWPoStbB4KSQdXdWOz1K10Cgd/uu7fzqy KnXezMvLjWNQh9U2IczBAvDKew5wPxdCPAAWK1mkNpSc5qnHC/oBo6dHuzgXHBpr4YI0 yyeQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:fcc:content-transfer-encoding:mime-version:to:cc; bh=KTAYz2IoJo8jRWqSzJj6zyy/6mxRcObxkuZ5nQQCYcQ=; b=4tGqtfh/iDEA+0QusTNWqSkCwxkBa7mBm8hpTaGMPlwIt31BHjg6Ew1gDtiA1XLuey d1zopLoFwgm8Dzxv9HWE2yT5zBc45RGAV16XJq9aaJjBBcMCNuaoSUQa4YLUKbufuIEu /9ntF5lbpyRYa35QpQBShqYYnOv+wslZd4LBQyC95szLS9wiy0JGc+vhGaBehIb8bLL3 nav6rzzsZYG0oz8GzHKyVIWM2NcyOfi0kw31SkkCUh62g5Fhk9Dqh11VvTKx1XAGzjZo BEIdOcVFZLiMkGpDtmuagIgkfzqlSPPzWTxdCHVZeqkUK2KpyzeAsJ9uKnsF8/ZWk/X6 MLlw== X-Gm-Message-State: AOAM530j0Eltbr8K6JIwvucUAzk85NNpxJumNtiN6XUpf5o3+B3ASz20 pxybq3D1Jex8YQzC2/vzfyJhmw8iUms= X-Google-Smtp-Source: ABdhPJynqHNgMhcRPto/6nY4Wd+76hN+rqwc1y+av7/bxKMLbS1t4REiB7PQbCu0nI5YRjZj69JNAA== X-Received: by 2002:a05:600c:2744:b0:38e:b6f7:d548 with SMTP id 4-20020a05600c274400b0038eb6f7d548mr11232927wmw.49.1650594754676; Thu, 21 Apr 2022 19:32:34 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id g8-20020a5d4888000000b00207a49fa6a1sm610891wrq.81.2022.04.21.19.32.33 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Apr 2022 19:32:34 -0700 (PDT) Message-Id: <7908c8f83d85c5e0bfea8476f0d9577d41ccd82b.1650594746.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Fri, 22 Apr 2022 02:32:23 +0000 Subject: [PATCH v3 6/9] git-sparse-checkout.txt: add a new EXAMPLES section Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Victoria Dye , Lessley Dennington , Derrick Stolee , Elijah Newren , Elijah Newren , Elijah Newren Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Elijah Newren From: Elijah Newren Since many users like to learn from examples, provide a section in the manual with example commands that would be used and a brief explanation of what each does. Signed-off-by: Elijah Newren --- Documentation/git-sparse-checkout.txt | 43 +++++++++++++++++++++++---- 1 file changed, 37 insertions(+), 6 deletions(-) diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 2083e6df356..c54437428bb 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -136,6 +136,43 @@ paths to pass to a subsequent 'set' or 'add' command. However, the disable command, so the easy restore of calling a plain `init` decreased in utility. +EXAMPLES +-------- +`git sparse-checkout set MY/DIR1 SUB/DIR2`:: + + Change to a sparse checkout with all files (at any depth) under + MY/DIR1/ and SUB/DIR2/ present in the working copy (plus all + files immediately under MY/ and SUB/ and the toplevel + directory). If already in a sparse checkout, change which files + are present in the working copy to this new selection. Note + that this command will also delete all ignored files in any + directory that no longer has either tracked or + non-ignored-untracked files present. + +`git sparse-checkout disable`:: + + Repopulate the working directory with all files, disabling sparse + checkouts. + +`git sparse-checkout add SOME/DIR/ECTORY`:: + + Add all files under SOME/DIR/ECTORY/ (at any depth) to the + sparse checkout, as well as all files immediately under + SOME/DIR/ and immediately under SOME/. Must already be in a + sparse checkout before using this command. + +`git sparse-checkout reapply`:: + + It is possible for commands to update the working tree in a + way that does not respect the selected sparsity directories. + This can come from tools external to Git writing files, or + even affect Git commands because of either special cases (such + as hitting conflicts when merging/rebasing), or because some + commands didn't fully support sparse checkouts (e.g. the old + `recursive` merge backend had only limited support). This + command reapplies the existing sparse directory specifications + to make the working directory match. + INTERNALS -- SPARSE CHECKOUT ---------------------------- @@ -154,12 +191,6 @@ directory, it updates the skip-worktree bits in the index based on this file. The files matching the patterns in the file will appear in the working directory, and the rest will not. -To enable the sparse-checkout feature, run `git sparse-checkout set` to -set the patterns you want to use. - -To repopulate the working directory with all files, use the -`git sparse-checkout disable` command. - INTERNALS -- CONE PATTERN SET ----------------------------- From patchwork Fri Apr 22 02:32:24 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Elijah Newren X-Patchwork-Id: 12822682 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id DAAC1C433F5 for ; Fri, 22 Apr 2022 02:33:00 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1443393AbiDVCfu (ORCPT ); Thu, 21 Apr 2022 22:35:50 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:36480 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1443390AbiDVCfg (ORCPT ); Thu, 21 Apr 2022 22:35:36 -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 8877B4B435 for ; Thu, 21 Apr 2022 19:32:37 -0700 (PDT) Received: by mail-wr1-x42d.google.com with SMTP id b19so9022289wrh.11 for ; Thu, 21 Apr 2022 19:32:37 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:fcc :content-transfer-encoding:mime-version:to:cc; bh=jwYa8NoODylvOmfYEQNNeU9meZTz6udqgzlQ9UufeOk=; b=DlBjbtPPrQ7ZFjYztw4bZl6ac8x019/8Sr9u9ps5Ypsggdgc8SQfVR0LwD/oLyiZNw Sjh+P1BLZHn4OP7dByJcQ85uWPXnOVOLXI+9WQMegwlVurHRdf/4J2mHqQS+TS1W2DZq v82cxaZf259jdyNCSxoStdJQKsJoF1uDhlzyYVkqU5HbV2RagMRr6ao70wf8Zzs1Y048 cAPmv4fCpb0RbuwWxcjyfDgdqjF7zuW6C3QY/hzcv7Jr9pS4/P8CUlUTnGkmjSwEoZ63 /ioDBIo0Oy27KywMeFhOk4ZCRNBOelq+RSHenfrW5oO5VT8HkmpNg/d0Kwmm+Sw4hdbE 5Qvw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:fcc:content-transfer-encoding:mime-version:to:cc; bh=jwYa8NoODylvOmfYEQNNeU9meZTz6udqgzlQ9UufeOk=; b=MqulgBoFetkg7hKDQWHp0Zs5Tz67B9bS9iyROZ1PbVrgMZXT5wmcLPvx+TdAwYeRx5 a+figf81FRvMMbIrxAvM9ziTSTyRy2kCuWEO7bl9O1cBNA5mo1lKn09WtG3p4m4fJGnL g+lNpfxWqD5pZg/qf0TuA2IfqtQgmm869pwWGXXufUneFEGluTb39fbKA9G2RqZxvlWj pxzdvnlLSTaX8ABrkY8obdcIezbd3S2jWJPVDDIKiNZj8QEQ32XU4sa/6PAGVJ6CREgo ZxU/8EdT6qbcOFZoo/jQOiiNV5R2Bd5gX7/KPmdemlyWbC3vlVTRjYzg4tP1b2rjfZZ3 enug== X-Gm-Message-State: AOAM530n5l9BvWBhZPV/KcGAYj22u7ygauw/qlw8iO1qurHqCrowNsnH ASiqWeMb/CEpljJH3+8JqT2D2p3yGj4= X-Google-Smtp-Source: ABdhPJymQlK2n1vNfW6ZTb2ALvSQ3bypEnoJNCcuFeOGYMkEFySoqYD1oILjjcsQkwJAWp65gutaFA== X-Received: by 2002:a05:6000:188b:b0:20a:a7f4:2f8 with SMTP id a11-20020a056000188b00b0020aa7f402f8mr1717891wri.424.1650594755658; Thu, 21 Apr 2022 19:32:35 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id n12-20020a5d588c000000b0020a9e80d2b1sm566173wrf.107.2022.04.21.19.32.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Apr 2022 19:32:35 -0700 (PDT) Message-Id: <546ae3d67326435c2b4a689f9217639bce660d88.1650594746.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Fri, 22 Apr 2022 02:32:24 +0000 Subject: [PATCH v3 7/9] git-sparse-checkout.txt: flesh out pattern set sections a bit Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Victoria Dye , Lessley Dennington , Derrick Stolee , Elijah Newren , Elijah Newren , Elijah Newren Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Elijah Newren From: Elijah Newren The "Internals -- Cone Pattern Set" section starts off discussing patterns, despite the fact that cone mode is about avoiding the patterns. This made sense back when non-cone mode was the default and we started by discussing the full pattern set, but now that we are changing the default, it makes more sense to discuss cone-mode first and avoid the full discussion of patterns. Split this section into two, the first with details about how cone mode operates, and the second following the full pattern set section and discussing how the cone mode patterns used under the hood relate to the full pattern set. While at it, flesh out the "Internals -- Full Pattern Set" section a bit to include more examples as well. Signed-off-by: Elijah Newren --- Documentation/git-sparse-checkout.txt | 129 +++++++++++++++++--------- 1 file changed, 85 insertions(+), 44 deletions(-) diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index c54437428bb..6e32034511d 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -192,7 +192,40 @@ on this file. The files matching the patterns in the file will appear in the working directory, and the rest will not. -INTERNALS -- CONE PATTERN SET +INTERNALS -- CONE MODE HANDLING +------------------------------- + +The "cone mode", which is the default, lets you specify only what +directories to include. For any directory specified, all paths below +that directory will be included, and any paths immediately under +leading directories (including the toplevel directory) will also be +included. Thus, if you specified the directory + Documentation/technical/ +then your sparse checkout would contain: + + * all files in the toplevel-directory + * all files immediately under Documentation/ + * all files at any depth under Documentation/technical/ + +Also, in cone mode, even if no directories are specified, then the +files in the toplevel directory will be included. + +When changing the sparse-checkout patterns in cone mode, Git will inspect each +tracked directory that is not within the sparse-checkout cone to see if it +contains any untracked files. If all of those files are ignored due to the +`.gitignore` patterns, then the directory will be deleted. If any of the +untracked files within that directory is not ignored, then no deletions will +occur within that directory and a warning message will appear. If these files +are important, then reset your sparse-checkout definition so they are included, +use `git add` and `git commit` to store them, then remove any remaining files +manually to ensure Git can behave optimally. + +See also the "Internals -- Cone Pattern Set" section to learn how the +directories are transformed under the hood into a subset of the +Full Pattern Set of sparse-checkout. + + +INTERNALS -- FULL PATTERN SET ----------------------------- The full pattern set allows for arbitrary pattern matches and complicated @@ -201,31 +234,62 @@ updating the index, where N is the number of patterns and M is the number of paths in the index. To combat this performance issue, a more restricted pattern set is allowed when `core.sparseCheckoutCone` is enabled. -The accepted patterns in the cone pattern set are: +The sparse-checkout file uses the same syntax as `.gitignore` files; +see linkgit:gitignore[5] for details. Here, though, the patterns are +usually being used to select which files to include rather than which +files to exclude. (However, it can get a bit confusing since +gitignore-style patterns have negations defined by patterns which +begin with a '!', so you can also select files to _not_ include.) + +For example, to select everything, and then to remove the file +`unwanted` (so that every file will appear in your working tree except +the file named `unwanted`): + + git sparse-checkout set --no-cone '/*' '!unwanted' + +These patterns are just placed into the +`$GIT_DIR/info/sparse-checkout` as-is, so the contents of that file +at this point would be + +---------------- +/* +!unwanted +---------------- + +See also the "Sparse Checkout" section of linkgit:git-read-tree[1] to +learn more about the gitignore-style patterns used in sparse +checkouts. + + +INTERNALS -- CONE PATTERN SET +----------------------------- + +In cone mode, only directories are accepted, but they are translated into +the same gitignore-style patterns used in the full pattern set. We refer +to the particular patterns used in those mode as being of one of two types: 1. *Recursive:* All paths inside a directory are included. 2. *Parent:* All files immediately inside a directory are included. -In addition to the above two patterns, we also expect that all files in the -root directory are included. If a recursive pattern is added, then all -leading directories are added as parent patterns. - -By default, when running `git sparse-checkout set` with no directories -specified, the root directory is added as a parent pattern. At this -point, the sparse-checkout file contains the following patterns: +Since cone mode always includes files at the toplevel, when running +`git sparse-checkout set` with no directories specified, the toplevel +directory is added as a parent pattern. At this point, the +sparse-checkout file contains the following patterns: ---------------- /* !/*/ ---------------- -This says "include everything in root, but nothing two levels below root." +This says "include everything immediately under the toplevel +directory, but nothing at any level below that." -When in cone mode, the `git sparse-checkout set` subcommand takes a list of -directories. In this mode, the command `git sparse-checkout set A/B/C` sets -the directory `A/B/C` as a recursive pattern, the directories `A` and `A/B` -are added as parent patterns. The resulting sparse-checkout file is now +When in cone mode, the `git sparse-checkout set` subcommand takes a +list of directories. The command `git sparse-checkout set A/B/C` sets +the directory `A/B/C` as a recursive pattern, the directories `A` and +`A/B` are added as parent patterns. The resulting sparse-checkout file +is now ---------------- /* @@ -244,11 +308,14 @@ Unless `core.sparseCheckoutCone` is explicitly set to `false`, Git will parse the sparse-checkout file expecting patterns of these types. Git will warn if the patterns do not match. If the patterns do match the expected format, then Git will use faster hash-based algorithms to compute inclusion -in the sparse-checkout. +in the sparse-checkout. If they do not match, git will behave as though +`core.sparseCheckoutCone` was false, regardless of its setting. -In the cone mode case, the `git sparse-checkout list` subcommand will list the -directories that define the recursive patterns. For the example sparse-checkout -file above, the output is as follows: +In the cone mode case, despite the fact that full patterns are written +to the $GIT_DIR/info/sparse-checkout file, the `git sparse-checkout +list` subcommand will list the directories that define the recursive +patterns. For the example sparse-checkout file above, the output is as +follows: -------------------------- $ git sparse-checkout list @@ -260,32 +327,6 @@ case-insensitive check. This corrects for case mismatched filenames in the 'git sparse-checkout set' command to reflect the expected cone in the working directory. -When changing the sparse-checkout patterns in cone mode, Git will inspect each -tracked directory that is not within the sparse-checkout cone to see if it -contains any untracked files. If all of those files are ignored due to the -`.gitignore` patterns, then the directory will be deleted. If any of the -untracked files within that directory is not ignored, then no deletions will -occur within that directory and a warning message will appear. If these files -are important, then reset your sparse-checkout definition so they are included, -use `git add` and `git commit` to store them, then remove any remaining files -manually to ensure Git can behave optimally. - - -INTERNALS -- FULL PATTERN SET ------------------------------ - -By default, the sparse-checkout file uses the same syntax as `.gitignore` -files. - -While `$GIT_DIR/info/sparse-checkout` is usually used to specify what -files are included, you can also specify what files are _not_ included, -using negative patterns. For example, to remove the file `unwanted`: - ----------------- -/* -!unwanted ----------------- - INTERNALS -- SUBMODULES ----------------------- From patchwork Fri Apr 22 02:32:25 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Elijah Newren X-Patchwork-Id: 12822681 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id E4F44C433EF for ; Fri, 22 Apr 2022 02:32:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1443406AbiDVCfs (ORCPT ); Thu, 21 Apr 2022 22:35:48 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:36482 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1443392AbiDVCfh (ORCPT ); Thu, 21 Apr 2022 22:35:37 -0400 Received: from mail-wr1-x42e.google.com (mail-wr1-x42e.google.com [IPv6:2a00:1450:4864:20::42e]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 871544B43A for ; Thu, 21 Apr 2022 19:32:38 -0700 (PDT) Received: by mail-wr1-x42e.google.com with SMTP id u3so9078288wrg.3 for ; Thu, 21 Apr 2022 19:32:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:fcc :content-transfer-encoding:mime-version:to:cc; bh=mniuo+xVSZDEQAPlzXASCWjhGUSvKje1AXNU3Lzz9ko=; b=RkRHbmu86keaZGrI9R2tvx4CT03oecOfkhNsz9bvTJb4BTon6BtS+EEeMyz7u3zpw1 WtWUSvesSTV7wr4fulKI1gqmXdy4jh+eLHDwQixEAPgdJkMU9V+jhbVZYyc6WIMJDnhZ cpmwT7veKH8r4Agtf3zDBbMyWXm2fLUAM6msOOvyT0xnNQfihlidIQ2z4lnsZ5npkwkT udewxavZH/Xr/4aWvucosCGUiSaOYPsrqhzFihiKXqz0kvNIUDiDBbIKJ+xZb8gqCR9/ bnTzPS8Zp1IyYKwar8UXLn7N5hb7fJtnm6uqCxKnuxLZFRNFfr+0UHeKmglddHcwm50C 7ibQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:fcc:content-transfer-encoding:mime-version:to:cc; bh=mniuo+xVSZDEQAPlzXASCWjhGUSvKje1AXNU3Lzz9ko=; b=HjdGklqzGF6BqJQ4muW6/+dzIzg0IiB6SYLaD0EpX3HrVzphmovHY2c/Uh/Iu3jLG9 6nWBngSyrwrQKRH0n6BV4WwbD0PfJcA/4aiDFCkukw6BymybeSUHdWR7lNlModhwlSPx YLhtYfq7Bch5oUy55oGXy/pA8Md25+WKgSCnkTFcoPefWLOHyWtedBXbvSz2zGTNYXXz qkkc2Vk5B0T7fEbjO01vDqTNeNDZAexfoFCTiDcz81OHda3+8GQtCuXT/8oExQDQFvC8 dvFLw7L+elgN1DbaLESObEOOpff7Ppxg+zjUgScyNR5k0fdY+YMypXDZEcyuzu8bCfUm yo1g== X-Gm-Message-State: AOAM530dpexl9lVkbW4zTSserpxO/fNVriBafd52RUyqyD9eR5mg3I17 vFSHaUu/J7Dp7/yf4vjI7EBkOtMNW24= X-Google-Smtp-Source: ABdhPJytgfJOkBiDQCODtOhHMfLLIK3H6jPdGQDEG7gGTzobii0MoBgTPvcuNf4dElVoDSKc/xGZSQ== X-Received: by 2002:adf:ed81:0:b0:207:a82a:bcf1 with SMTP id c1-20020adfed81000000b00207a82abcf1mr1766772wro.194.1650594756723; Thu, 21 Apr 2022 19:32:36 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id 3-20020a056000154300b0020a9dcac3c2sm611599wry.20.2022.04.21.19.32.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Apr 2022 19:32:36 -0700 (PDT) Message-Id: In-Reply-To: References: Date: Fri, 22 Apr 2022 02:32:25 +0000 Subject: [PATCH v3 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Victoria Dye , Lessley Dennington , Derrick Stolee , Elijah Newren , Elijah Newren , Elijah Newren Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Elijah Newren From: Elijah Newren While we have no current plans to actually remove --no-cone mode, we think users would be better off not using it. Update the documentation accordingly, including explaining why we think non-cone mode is problematic for users. Signed-off-by: Elijah Newren --- Documentation/git-sparse-checkout.txt | 98 +++++++++++++++++++++++++-- 1 file changed, 94 insertions(+), 4 deletions(-) diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 6e32034511d..c65d0ce96bb 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -71,10 +71,9 @@ and `--cone` needed to be specified or `core.sparseCheckoutCone` needed to be enabled. + When `--no-cone` is passed, the input list is considered a list of -patterns. This mode is harder to use and less performant, and is thus -not recommended. See the "Sparse Checkout" section of -linkgit:git-read-tree[1] and the "Internals...Pattern Set" sections -below for more details. +patterns. This mode has a number of drawbacks, including not working +with some options like `--sparse-index`. As explained in the +"Non-cone Problems" section below, we do not recommend using it. + Use the `--[no-]sparse-index` option to use a sparse index (the default is to not use it). A sparse index reduces the size of the @@ -191,6 +190,97 @@ directory, it updates the skip-worktree bits in the index based on this file. The files matching the patterns in the file will appear in the working directory, and the rest will not. +INTERNALS -- NON-CONE PROBLEMS +------------------------------ + +The `$GIT_DIR/info/sparse-checkout` file populated by the `set` and +`add` subcommands is defined to be a bunch of patterns (one per line) +using the same syntax as `.gitignore` files. In cone mode, these +patterns are restricted to matching directories (and users only ever +need supply or see directory names), while in non-cone mode any +gitignore-style pattern is permitted. Using the full gitignore-style +patterns in non-cone mode has a number of shortcomings: + + * Fundamentally, it makes various worktree-updating processes (pull, + merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern + matches, where N is the number of patterns and M is the number of + paths in the index. This scales poorly. + + * Avoiding the scaling issue has to be done via limiting the number + of patterns via specifying leading directory name or glob. + + * Passing globs on the command line is error-prone as users may + forget to quote the glob, causing the shell to expand it into all + matching files and pass them all individually along to + sparse-checkout set/add. While this could also be a problem with + e.g. "git grep -- *.c", mistakes with grep/log/status appear in + the immediate output. With sparse-checkout, the mistake gets + recorded at the time the sparse-checkout command is run and might + not be problematic until the user later switches branches or rebases + or merges, thus putting a delay between the user's error and when + they have a chance to catch/notice it. + + * Related to the previous item, sparse-checkout has an 'add' + subcommand but no 'remove' subcommand. Even if a 'remove' + subcommand were added, undoing an accidental unquoted glob runs + the risk of "removing too much", as it may remove entries that had + been included before the accidental add. + + * Non-cone mode uses gitignore-style patterns to select what to + *include* (with the exception of negated patterns), while + .gitignore files use gitignore-style patterns to select what to + *exclude* (with the exception of negated patterns). The + documentation on gitignore-style patterns usually does not talk in + terms of matching or non-matching, but on what the user wants to + "exclude". This can cause confusion for users trying to learn how + to specify sparse-checkout patterns to get their desired behavior. + + * Every other git subcommand that wants to provide "special path + pattern matching" of some sort uses pathspecs, but non-cone mode + for sparse-checkout uses gitignore patterns, which feels + inconsistent. + + * It has edge cases where the "right" behavior is unclear. Two examples: + + First, two users are in a subdirectory, and the first runs + git sparse-checkout set '/toplevel-dir/*.c' + while the second runs + git sparse-checkout set relative-dir + Should those arguments be transliterated into + current/subdirectory/toplevel-dir/*.c + and + current/subdirectory/relative-dir + before inserting into the sparse-checkout file? The user who typed + the first command is probably aware that arguments to set/add are + supposed to be patterns in non-cone mode, and probably would not be + happy with such a transliteration. However, many gitignore-style + patterns are just paths, which might be what the user who typed the + second command was thinking, and they'd be upset if their argument + wasn't transliterated. + + Second, what should bash-completion complete on for set/add commands + for non-cone users? If it suggests paths, is it exacerbating the + problem above? Also, if it suggests paths, what if the user has a + file or directory that begins with either a '!' or '#' or has a '*', + '\', '?', '[', or ']' in its name? And if it suggests paths, will + it complete "/pro" to "/proc" (in the root filesytem) rather than to + "/progress.txt" in the current directory? (Note that users are + likely to want to start paths with a leading '/' in non-cone mode, + for the same reason that .gitignore files often have one.) + Completing on files or directories might give nasty surprises in + all these cases. + + * The excessive flexibility made other extensions essentially + impractical. `--sparse-index` is likely impossible in non-cone + mode; even if it is somehow feasible, it would have been far more + work to implement and may have been too slow in practice. Some + ideas for adding coupling between partial clones and sparse + checkouts are only practical with a more restricted set of paths + as well. + +For all these reasons, non-cone mode is deprecated. Please switch to +using cone mode. + INTERNALS -- CONE MODE HANDLING ------------------------------- From patchwork Fri Apr 22 02:32:26 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Elijah Newren X-Patchwork-Id: 12822680 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id D66ABC433F5 for ; Fri, 22 Apr 2022 02:32:57 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1443404AbiDVCfq (ORCPT ); Thu, 21 Apr 2022 22:35:46 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:36488 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1443394AbiDVCfh (ORCPT ); Thu, 21 Apr 2022 22:35:37 -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 81D354B843 for ; Thu, 21 Apr 2022 19:32:39 -0700 (PDT) Received: by mail-wr1-x432.google.com with SMTP id t6so5624807wra.4 for ; Thu, 21 Apr 2022 19:32:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=message-id:in-reply-to:references:from:date:subject:mime-version :content-transfer-encoding:fcc:to:cc; bh=cQ7VO46HxU83KepgllzaoRvWa6YiqCIJUR2hs7SH9Ec=; b=lfT98ftimT20EkXoLE0GZmSwV9Zj8TyioIBa2WWfwpSEv49xmM+Z+8TZM1pEQgofKb ZIHYcc9dTrRFwVeq+IZ9RF7kMOoULwo5O0edFBVr/8FH30W98UO/aegtElJgKZXvMiA+ IrJ5MLIC8ZOaYExq6vMjXTkRMuh5SP9/Lia1HvxPzzRMB7VwFq99arqWlNRR41jETb+j 19WPptGINi+l+U36w85zHgN2uRBPBrcLdt6nT0uIdpOdqAKCQpg//bA2gu3lnNlrFRQC pDJHG5n/N+Q+A5rJZB3F0veI3e95JmiZZ3/7IGI25PYK0O4dmuNfFautjqKCssDQX+qf OrkQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:message-id:in-reply-to:references:from:date :subject:mime-version:content-transfer-encoding:fcc:to:cc; bh=cQ7VO46HxU83KepgllzaoRvWa6YiqCIJUR2hs7SH9Ec=; b=fWKGhTI7r8Ve8QqI5HS3PiflzZK/PWW21lmQO9o+VRCdMCbJTOkU+j9gC5T95R+LEf f9BXx1zJ62fBvR04Zx2azRSJId7R554FSfuGI50wrp4AUt7yLmPBHc70Q0yMiStTj7s5 v9nsPfVhWJEwrNCNGob/H2NVh3KBkRS4VddipEdtivpemJMSSaXr13EFqXNk0v3pZhSu 19+hst65iXcwyeisH3LWXTT42aIu8Q6JoCAIedOWHqQwYaBGbyyuRDNfL7vL724BBzEH AdUzD/wMQ7CCRHpH0gk1rWgEwYaFpqiDZdVhd4dAMj3JPZfo4dsugS5PlzCnkG9po8RX bOfQ== X-Gm-Message-State: AOAM531+PK2R592gZ7d5EgoDN23ahUspYETae7qwFYgpy2AtdZr3Eo9n aPHYNK8XSysfK8E5EOV6gp5VXbvNzoQ= X-Google-Smtp-Source: ABdhPJx6H5vS9A1a0DMLJlOZJi/kDyspD+BTFgx01rOwYGgfR5b+XveH7U4ADss9qq4D+8EUvQxnDA== X-Received: by 2002:a5d:56c9:0:b0:20a:c54c:70e2 with SMTP id m9-20020a5d56c9000000b0020ac54c70e2mr1738195wrw.415.1650594757815; Thu, 21 Apr 2022 19:32:37 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id n2-20020a05600c4f8200b003928e8e85eesm530100wmq.10.2022.04.21.19.32.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Apr 2022 19:32:37 -0700 (PDT) Message-Id: <5f0e80777de6d4dcb245f3f0281cd31cac497cbc.1650594746.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Fri, 22 Apr 2022 02:32:26 +0000 Subject: [PATCH v3 9/9] Documentation: some sparsity wording clarifications MIME-Version: 1.0 Fcc: Sent To: git@vger.kernel.org Cc: Victoria Dye , Lessley Dennington , Derrick Stolee , Elijah Newren , Elijah Newren , Elijah Newren Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Elijah Newren From: Elijah Newren Improve the wording for a couple paragraphs in two different manuals relating to sparse behavior. Reported-by: Ævar Arnfjörð Bjarmason Signed-off-by: Elijah Newren --- Documentation/git-read-tree.txt | 11 +++++++---- Documentation/git-sparse-checkout.txt | 10 +++++----- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 99bb387134d..d255807798c 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -375,10 +375,13 @@ have finished your work-in-progress), attempt the merge again. SPARSE CHECKOUT --------------- -Note: The `update-index` and `read-tree` primitives for supporting the -skip-worktree bit predated the introduction of -linkgit:git-sparse-checkout[1]. Users are encouraged to use -`sparse-checkout` in preference to these low-level primitives. +Note: The skip-worktree capabilities in linkgit:git-update-index[1] +and `read-tree` predated the introduction of +linkgit:git-sparse-checkout[1]. Users are encouraged to use the +`sparse-checkout` command in preference to these plumbing commands for +sparse-checkout/skip-worktree related needs. However, the information +below might be useful to users trying to understand the pattern style +used in non-cone mode of the `sparse-checkout` command. "Sparse checkout" allows populating the working directory sparsely. It uses the skip-worktree bit (see linkgit:git-update-index[1]) to diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index c65d0ce96bb..3776705bf53 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -15,11 +15,11 @@ SYNOPSIS DESCRIPTION ----------- -This command is used to create sparse checkouts, which means that it -changes the working tree from having all tracked files present, to only -have a subset of them. It can also switch which subset of files are -present, or undo and go back to having all tracked files present in the -working copy. +This command is used to create sparse checkouts, which change the +working tree from having all tracked files present to only having a +subset of those files. It can also switch which subset of files are +present, or undo and go back to having all tracked files present in +the working copy. The subset of files is chosen by providing a list of directories in cone mode (the default), or by providing a list of patterns in