From patchwork Sat Mar 19 06:19:07 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Shaoxuan Yuan X-Patchwork-Id: 12786077 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 EDAD0C433F5 for ; Sat, 19 Mar 2022 06:19:34 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S242190AbiCSGUx (ORCPT ); Sat, 19 Mar 2022 02:20:53 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:33876 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233945AbiCSGUs (ORCPT ); Sat, 19 Mar 2022 02:20:48 -0400 Received: from mail-pf1-x429.google.com (mail-pf1-x429.google.com [IPv6:2607:f8b0:4864:20::429]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 2307697290 for ; Fri, 18 Mar 2022 23:19:28 -0700 (PDT) Received: by mail-pf1-x429.google.com with SMTP id u17so11254285pfk.11 for ; Fri, 18 Mar 2022 23:19:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=DxSXk5STCiKpYdqfI7Rzk35WBxeGplQYeTa7X1Lfpk4=; b=FwJ5/D262ZosXkrZYExdgtudMRDQ3pAR3sAInSnF36VdzCR4TUTz7hV6ivwfbS6YTZ 1T0oeHNE+PJ1B757cWblL5MWX2JwimP/mjXykqm3O0JaqFsF1KcGvXkPQ+5WHmoM/Hfi lymK4TwyGtFmqtTW/W4bkid8nwYQ8eSzSQt/HTZX6oEv9T5ywNt4Fm1CPJQ771obbhL8 Q8X2ZBY6AcV9+rwVLrl0CszCZkIqiQqaD7Njyc3kDmmFfvBZRYkAN19z0rzAkH1ttLBW 6hapVeTEEo6NAoKPtPlHuefjqhSuovL3SYIJsRbmXJx3TqYVsw46n3QCfslV0tX83MGn qwww== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=DxSXk5STCiKpYdqfI7Rzk35WBxeGplQYeTa7X1Lfpk4=; b=MXH+ghwlpHR8Nnz1CW3OyGYMcMinmMN9D792BPkJpfkX6FxQ/bz2FfEaFHnOshgyDY BTbL7M8GUKivHpuEpne8w2CHSOuBM9aEc0pcRBEx6h652oUZOjQBkPO3PT+AqmCfcPGi mDbymar+7Yqrk+XGWnZRevbTk2I0F5nbkPt+jGnD4j35t6QLuGy4EMvAtGd/lE4+TG2x hSaPk9jHiqUrjvcsDB2yFntFtpA3umLXx/vs7sm5ZU6f/QhvkMlJYZn9Tw13xjQY3rV1 vVbw/pAZJubH2guC0ReiFCDzspmxgcg55NwfUY+0FDy3Ib5peXRLiP7IX0vpcm54O+2p gX7A== X-Gm-Message-State: AOAM533yZPDNNz6PvLpgyLpi1IX8iSaKZPiL3iAhx4SfVhMOhhF/wS4b J1TJRTAsdHM2Lhh3g1+fPrA66Y6U3nc= X-Google-Smtp-Source: ABdhPJx75z+cRm7Q6ltZwVsK02tzHzbix2TULAgPitXU0qKvw0HsbUGzYt/iY8Db2dC3MIKvISZg2w== X-Received: by 2002:a63:5145:0:b0:381:4051:1f5a with SMTP id r5-20020a635145000000b0038140511f5amr10713997pgl.300.1647670767604; Fri, 18 Mar 2022 23:19:27 -0700 (PDT) Received: from ffyuanda.localdomain ([119.131.152.89]) by smtp.gmail.com with ESMTPSA id b2-20020a639302000000b003808dc4e133sm9235950pge.81.2022.03.18.23.19.25 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Mar 2022 23:19:27 -0700 (PDT) From: Shaoxuan Yuan To: gitster@pobox.com Cc: derrickstolee@github.com, git@vger.kernel.org, vdye@github.com, Shaoxuan Yuan Subject: [PATCH v5 1/4] Documentation/git-sparse-checkout.txt: add an OPTIONS section Date: Sat, 19 Mar 2022 14:19:07 +0800 Message-Id: <20220319061910.786850-2-shaoxuan.yuan02@gmail.com> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220319061910.786850-1-shaoxuan.yuan02@gmail.com> References: <20220311132141.1817-1-shaoxuan.yuan02@gmail.com> <20220319061910.786850-1-shaoxuan.yuan02@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Add an OPTIONS section to the manual and move the descriptions about these options from COMMANDS to the section. Signed-off-by: Shaoxuan Yuan --- Documentation/git-sparse-checkout.txt | 63 +++++++++++++++++---------- 1 file changed, 39 insertions(+), 24 deletions(-) diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index e4a29a2baa..5db5c0ab47 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -35,30 +35,11 @@ COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE FUTURE. -COMMANDS --------- -'list':: - Describe the directories or patterns in the sparse-checkout file. - -'set':: - Enable the necessary sparse-checkout config settings - (`core.sparseCheckout`, `core.sparseCheckoutCone`, and - `index.sparse`) if they are not already set to the desired values, - 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' -subcommand will upgrade your repository config to use worktree-specific -config if not already present. The sparsity defined by the arguments to -the 'set' subcommand are stored in the worktree-specific sparse-checkout -file. See linkgit:git-worktree[1] and the documentation of -`extensions.worktreeConfig` in linkgit:git-config[1] for more details. -+ -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. +OPTIONS +------- +'--[no-]cone':: + Use with ['set'|'reapply']. + Specify using cone mode or not. The default is to use cone mode. + By default, the input list is considered a list of directories, matching the output of `git ls-tree -d --name-only`. This includes interpreting @@ -78,6 +59,11 @@ with the `--sparse-index` option, and will likely be incompatible with other new features as they are added. See the "Non-cone Problems" section below and the "Sparse Checkout" section of linkgit:git-read-tree[1] for more details. + +'--[no-]sparse-index':: + Use with ['set'|'reapply']. + Specify using a sparse index or not. The default is to not use a + sparse index. + 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 @@ -94,6 +80,35 @@ to rewrite your index to not be sparse. Older versions of Git will not understand the sparse directory entries index extension and may fail to interact with your repository until it is disabled. +'--stdin':: + Use with ['set'|'add']. ++ +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. + + +COMMANDS +-------- +'list':: + Describe the directories or patterns in the sparse-checkout file. + +'set':: + Enable the necessary sparse-checkout config settings + (`core.sparseCheckout`, `core.sparseCheckoutCone`, and + `index.sparse`) if they are not already set to the desired values, + 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' +subcommand will upgrade your repository config to use worktree-specific +config if not already present. The sparsity defined by the arguments to +the 'set' subcommand are stored in the worktree-specific sparse-checkout +file. See linkgit:git-worktree[1] and the documentation of +`extensions.worktreeConfig` in linkgit:git-config[1] for more details. + 'add':: Update the sparse-checkout file to include additional directories (in cone mode) or patterns (in non-cone mode). By default, these From patchwork Sat Mar 19 06:19:08 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Shaoxuan Yuan X-Patchwork-Id: 12786080 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 98324C433EF for ; Sat, 19 Mar 2022 06:19:49 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S242249AbiCSGUx (ORCPT ); Sat, 19 Mar 2022 02:20:53 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:34116 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S242220AbiCSGUw (ORCPT ); Sat, 19 Mar 2022 02:20:52 -0400 Received: from mail-pj1-x1036.google.com (mail-pj1-x1036.google.com [IPv6:2607:f8b0:4864:20::1036]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 2CD5997299 for ; Fri, 18 Mar 2022 23:19:30 -0700 (PDT) Received: by mail-pj1-x1036.google.com with SMTP id mj15-20020a17090b368f00b001c637aa358eso12112413pjb.0 for ; Fri, 18 Mar 2022 23:19:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=gcg7esqTL8wuikvmNXGao5leDMsOjuIwZrmfcHapdrw=; b=UOrnLpPsQ0hlV6XHa6jb+2MN6HsbhvDBgH5i8i+d9ExNtTer9OaToaGsCUH+YMRIWW M3htcMsZmVCMLKSoaKYXuhYxq/A7+SM4yxlW8feJVqaSVeWXzyyvaaz06T33WRoTszZG tQtiWhF/ZKJY96BmA/j+ErPH7y8yxbGbGRA0dh5CSVKwpFlk2t8ZUSRgY/gWPFDPxzYG SeggWZebJsSj6QpoTcosXoNuASBVfaJN+K/WYI6wqxrQKn1B8NfEA250qeFRgw4DXmm7 iYae1K87PLdDFyoG7shDcnFMj28BU2EZ/98ccr94iyqVAabv6fcOG46o16xWHSG2EH6c tzbw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=gcg7esqTL8wuikvmNXGao5leDMsOjuIwZrmfcHapdrw=; b=EoLN6JU7KSGAJtr8JUzERa8EW1DUPgpM94s3U9DxtFjeRFVap3k+sj3p0U+2isgiAi 7VNcLrM+e5d9NOJMi0pu+24BiAS1P1mykwTrupG999MRKkf25cwifYBu1GLQFckaql76 wYwWESumQDM3S6IF/7UEAR02aO06lyxiDpkzj/JB+JJKuDEoFw5S1BEaVuLIRwW1zTvu MESXNGpXSANm8UE+XLAzbnmBeObRr1VInmWNNeDgn/HuLtF63RcK+bEhSDQv8PbxxnSa WUdL7N1HJ8uzb2nwzJaAasP0MGmT8/R7QjPrVp/ZTHzzW4mSRT6fFs0AOS11zxa1nSZJ kn8g== X-Gm-Message-State: AOAM5323MTWEMFXexh0RgwIF5OO/lswwf9yhxzv3DPNfRA8IRjDZgFCU Z6deA1NEyYht603so9rgLXs= X-Google-Smtp-Source: ABdhPJw+Vn1RU1ef9/qFCJWBjnwOGfIlLSiD5mFPXzDze3auxrbRssSGpPUimedL1qe4kdfE2QycrQ== X-Received: by 2002:a17:90a:4306:b0:1b9:80b3:7a3d with SMTP id q6-20020a17090a430600b001b980b37a3dmr25509013pjg.66.1647670769560; Fri, 18 Mar 2022 23:19:29 -0700 (PDT) Received: from ffyuanda.localdomain ([119.131.152.89]) by smtp.gmail.com with ESMTPSA id b2-20020a639302000000b003808dc4e133sm9235950pge.81.2022.03.18.23.19.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Mar 2022 23:19:29 -0700 (PDT) From: Shaoxuan Yuan To: gitster@pobox.com Cc: derrickstolee@github.com, git@vger.kernel.org, vdye@github.com, Shaoxuan Yuan Subject: [PATCH v5 2/4] Documentation/git-sparse-checkout.txt: move OPTIONS after COMMANDS Date: Sat, 19 Mar 2022 14:19:08 +0800 Message-Id: <20220319061910.786850-3-shaoxuan.yuan02@gmail.com> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220319061910.786850-1-shaoxuan.yuan02@gmail.com> References: <20220311132141.1817-1-shaoxuan.yuan02@gmail.com> <20220319061910.786850-1-shaoxuan.yuan02@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org * move OPTIONS after COMMANDS * add two sub-sections under option '--[no-]cone', one for command 'set' and one for command 'reapply' * change the command indicators from this style: Use with ['set'|'reapply']. to this style: Use with the `set` and `reapply` commands. Helped-by: Derrick Stolee Signed-off-by: Shaoxuan Yuan --- Documentation/git-sparse-checkout.txt | 121 ++++++++++++++------------ 1 file changed, 63 insertions(+), 58 deletions(-) diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 5db5c0ab47..b8f3b89b74 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -35,59 +35,6 @@ COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE FUTURE. -OPTIONS -------- -'--[no-]cone':: - Use with ['set'|'reapply']. - Specify using cone mode or not. The default is to use cone mode. -+ -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, the input list is considered a list of -patterns. This mode is harder to use, and unless you can keep the -number of patterns small, its design also scales poorly. It used to be -the default mode, but we do not recommend using it. It does not work -with the `--sparse-index` option, and will likely be incompatible with -other new features as they are added. See the "Non-cone Problems" -section below and the "Sparse Checkout" section of -linkgit:git-read-tree[1] for more details. - -'--[no-]sparse-index':: - Use with ['set'|'reapply']. - Specify using a sparse index or not. The default is to not use a - sparse index. -+ -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 -index to be more closely aligned with your sparse-checkout -definition. This can have significant performance advantages for -commands such as `git status` or `git add`. This feature is still -experimental. Some commands might be slower with a sparse index until -they are properly integrated with the feature. -+ -**WARNING:** Using a sparse index requires modifying the index in a way -that is not completely understood by external tools. If you have trouble -with this compatibility, then run `git sparse-checkout init --no-sparse-index` -to rewrite your index to not be sparse. Older versions of Git will not -understand the sparse directory entries index extension and may fail to -interact with your repository until it is disabled. - -'--stdin':: - Use with ['set'|'add']. -+ -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. - - COMMANDS -------- 'list':: @@ -124,11 +71,6 @@ file. See linkgit:git-worktree[1] and the documentation of cases, it can make sense to run `git sparse-checkout reapply` later after cleaning up affected paths (e.g. resolving conflicts, undoing or committing changes, etc.). -+ -The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index` -flags, with the same meaning as the flags from the `set` command, in order -to change which sparsity mode you are using without needing to also respecify -all sparsity paths. 'disable':: Disable the `core.sparseCheckout` config setting, and restore the @@ -154,6 +96,69 @@ 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. + +OPTIONS +------- +'--[no-]cone':: + Use with the `set` and `reapply` commands. + Specify using cone mode or not. The default is to use cone mode. ++ +For `set` command: ++ +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, the input list is considered a list of +patterns. This mode is harder to use, and unless you can keep the +number of patterns small, its design also scales poorly. It used to be +the default mode, but we do not recommend using it. It does not work +with the `--sparse-index` option, and will likely be incompatible with +other new features as they are added. See the "Non-cone Problems" +section below and the "Sparse Checkout" section of +linkgit:git-read-tree[1] for more details. ++ +For `reapply` command: ++ +The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index` +flags, with the same meaning as the flags from the `set` command, in order +to change which sparsity mode you are using without needing to also respecify +all sparsity paths. + +'--[no-]sparse-index':: + Use with the `set` and `reapply` commands. + Specify using a sparse index or not. The default is to not use a + sparse index. ++ +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 +index to be more closely aligned with your sparse-checkout +definition. This can have significant performance advantages for +commands such as `git status` or `git add`. This feature is still +experimental. Some commands might be slower with a sparse index until +they are properly integrated with the feature. ++ +**WARNING:** Using a sparse index requires modifying the index in a way +that is not completely understood by external tools. If you have trouble +with this compatibility, then run `git sparse-checkout init --no-sparse-index` +to rewrite your index to not be sparse. Older versions of Git will not +understand the sparse directory entries index extension and may fail to +interact with your repository until it is disabled. + +'--stdin':: + Use with the `set` and `add` commands. ++ +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. + + EXAMPLES -------- `git sparse-checkout set MY/DIR1 SUB/DIR2`:: From patchwork Sat Mar 19 06:19:09 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Shaoxuan Yuan X-Patchwork-Id: 12786078 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 752B3C433F5 for ; Sat, 19 Mar 2022 06:19:49 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S242255AbiCSGU4 (ORCPT ); Sat, 19 Mar 2022 02:20:56 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:34122 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S242226AbiCSGUw (ORCPT ); Sat, 19 Mar 2022 02:20:52 -0400 Received: from mail-pl1-x62c.google.com (mail-pl1-x62c.google.com [IPv6:2607:f8b0:4864:20::62c]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A8B5E972A9 for ; Fri, 18 Mar 2022 23:19:32 -0700 (PDT) Received: by mail-pl1-x62c.google.com with SMTP id e13so8725478plh.3 for ; Fri, 18 Mar 2022 23:19:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=G+tkS3K/smcilCZUyYeDGdgmqmSXF/kDuOiacbcWSw0=; b=XZ372FulBhchREHfFrKj6q7oxqUENfYLLDar/eIpNUvcLdPwJI5R9kV5+rWXE8eKqX P15u4MElf8uYhchSkyH6H2ua6FZKwXVdZ8Z4Q70BdQ/nSwFfW7skD0tLC8TDtwWSAMNo wCwIAMcPQVkqtdE8n7z8+/pEAtUY6EKxlRwVlI8VWTIxlSeU/kv83prarBjg55+fMZbk Z9YVCo1JYEH8g/GIhCW6gpvnOs7d5aIVtvDwwb5HrV/UzfibsmwPTjF28kBj5EfyeXSW /NiArojQiXgnQCTL/XQOdJWNrYGFi65d0JnxMWP5Zwy++tqD4shkmUr7iTEqtSez1kRI a/BQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=G+tkS3K/smcilCZUyYeDGdgmqmSXF/kDuOiacbcWSw0=; b=Cm0rueP8QbfAhAtYAHu2HJ+EHaxURZF5gY2zqJdVo14vtSBXhovQjjTmF2koXayPED MxDb6OL1l66utsTCuObSYPSgjgvv+n/wXlA3v+g/zKB/Y7RjpPlXPDrqFpRGVe547pDh fYLpHLtVkpqZNQbaWSm6K4XFSN1APli2hA5/qDd2usSwq+7zbsU293gAuKki1j2KiXQd oF85IJVQUbHEbPntUhgs9OJGZy691D8t0m/JMpjnfPEXryXHu9MhYDVnUwkqp9Fp8uC/ FWNPWqtbhIg0pCFRdftKydF0Bx8UqYgSQLVZeekQ8rLlGpvq7wMCPoIuhGpO1hsBs14M 9NYQ== X-Gm-Message-State: AOAM532SDaKh+/6uq3pcpx7FKFeOooemrFM4Ar/f/9U9q+z/JWQkEuRD bLUans0iqQKYkmm3lDUW1g4= X-Google-Smtp-Source: ABdhPJzFfKOcU3hgtcz6YGVQVyWuG4mTkFaZCgZfbrSXg+lDMf9a+lGXt/aFPqwrp9uoOc0CZgwPNg== X-Received: by 2002:a17:90b:2496:b0:1b9:a6dd:ae7 with SMTP id nt22-20020a17090b249600b001b9a6dd0ae7mr25529569pjb.35.1647670772112; Fri, 18 Mar 2022 23:19:32 -0700 (PDT) Received: from ffyuanda.localdomain ([119.131.152.89]) by smtp.gmail.com with ESMTPSA id b2-20020a639302000000b003808dc4e133sm9235950pge.81.2022.03.18.23.19.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Mar 2022 23:19:31 -0700 (PDT) From: Shaoxuan Yuan To: gitster@pobox.com Cc: derrickstolee@github.com, git@vger.kernel.org, vdye@github.com, Shaoxuan Yuan Subject: [PATCH v5 3/4] Documentation/git-sparse-checkout.txt: some reword and modifications Date: Sat, 19 Mar 2022 14:19:09 +0800 Message-Id: <20220319061910.786850-4-shaoxuan.yuan02@gmail.com> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220319061910.786850-1-shaoxuan.yuan02@gmail.com> References: <20220311132141.1817-1-shaoxuan.yuan02@gmail.com> <20220319061910.786850-1-shaoxuan.yuan02@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Some changes according to Derrick [1] * added a paragraph that breifly touches on the input of 'set' command * refer to the 'set' command when talking about 'add' command * condense the '--[no-]cone' section * remove 'For `reapply` command' section under '--[no-]cone' section [1] https://lore.kernel.org/git/307ac60d-b0a1-ea90-8118-a4e02b809102@github.com/ Helped-by: Derrick Stolee Signed-off-by: Shaoxuan Yuan --- Documentation/git-sparse-checkout.txt | 44 +++++++++------------------ 1 file changed, 15 insertions(+), 29 deletions(-) diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index b8f3b89b74..0178d63f56 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -48,6 +48,14 @@ COMMANDS following the 'set' subcommand, and update the working directory to match. + +By default, the arguments to the `set` command are interpreted as a +list of directories. The sparse-checkout patterns are set to match +all files within those directories, recursively, as well as any file +directly contained in a parent of those directories. See INTERNALS +-- CONE PATTERN SET below for full details. If --no-cone is specified, +then the arguments are interpreted as sparse-checkout patterns. See +INTERNALS -- FULL PATTERN SET below for more information. ++ To ensure that adjusting the sparse-checkout settings within a worktree does not alter the sparse-checkout settings in other worktrees, the 'set' subcommand will upgrade your repository config to use worktree-specific @@ -59,8 +67,10 @@ file. See linkgit:git-worktree[1] and the documentation of 'add':: Update the sparse-checkout file to include additional directories (in cone mode) or patterns (in non-cone mode). By default, these - directories or patterns are read from the command-line arguments, - but they can be read from stdin using the `--stdin` option. + directories or patterns are read from the command-line arguments. + These directories or patterns are interpreted the same way as stated + above in `set` command, and they can be read from stdin using the + `--stdin` option. 'reapply':: Reapply the sparsity pattern rules to paths in the working tree. @@ -103,33 +113,9 @@ OPTIONS Use with the `set` and `reapply` commands. Specify using cone mode or not. The default is to use cone mode. + -For `set` command: -+ -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, the input list is considered a list of -patterns. This mode is harder to use, and unless you can keep the -number of patterns small, its design also scales poorly. It used to be -the default mode, but we do not recommend using it. It does not work -with the `--sparse-index` option, and will likely be incompatible with -other new features as they are added. See the "Non-cone Problems" -section below and the "Sparse Checkout" section of -linkgit:git-read-tree[1] for more details. -+ -For `reapply` command: -+ -The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index` -flags, with the same meaning as the flags from the `set` command, in order -to change which sparsity mode you are using without needing to also respecify -all sparsity paths. +For the `set` command, the option to use cone mode or not changes +the interpretation of the remaining arguments to either be a list +of directories or a list of patterns. '--[no-]sparse-index':: Use with the `set` and `reapply` commands. From patchwork Sat Mar 19 06:19:10 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Shaoxuan Yuan X-Patchwork-Id: 12786079 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 86B2AC433FE for ; Sat, 19 Mar 2022 06:19:49 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S242257AbiCSGVA (ORCPT ); Sat, 19 Mar 2022 02:21:00 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:34266 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S242252AbiCSGUz (ORCPT ); Sat, 19 Mar 2022 02:20:55 -0400 Received: from mail-pj1-x1031.google.com (mail-pj1-x1031.google.com [IPv6:2607:f8b0:4864:20::1031]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9C83B9729A for ; Fri, 18 Mar 2022 23:19:34 -0700 (PDT) Received: by mail-pj1-x1031.google.com with SMTP id mz9-20020a17090b378900b001c657559290so9719042pjb.2 for ; Fri, 18 Mar 2022 23:19:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=PdAV1jxgRUDhKFWAFHc9zRhVZngoKKmdhXK71QcIHC0=; b=eapLqWCKxvqzMCHhqQYA+5sytwHcDRvPnesygpjI2Jy04pCiK3ozLJh67r1Ro+FCEK RowRQgIzmIlzKcPJM/aKFUIKVcmPs3iquHuyWB1fXh1OF7QOQuAeOOmySvvy4Bul4oak jmow4+5W+FozHc4Z4WW9kkRbqC9TQAEahPVKKgykM5TBodINqRFRiIOlKLYVlB94OaeV 6gDuh8X2CmIVGBr1ST0tpNwohSVuH6Y8XjHdDcg0GQfGlOuVmLyNHBliEtZrbp3KWQZW sgLCwxxjo+SKRItakPIZPz5rY47cdT6AuZggpj1G+YqVXSZZt+QyezjhzA0fProYjls0 RS9A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=PdAV1jxgRUDhKFWAFHc9zRhVZngoKKmdhXK71QcIHC0=; b=JJtNRf9DzHrqnsNWkgTfKItmpRKW/I1yTE8GR2yT4B/k1yMj4v6RjW1tCsX8nICru9 Gk+Lpx40eVQ2e/GLDp6Oh+Qgf2FnLQZRrOeAJxeQ9GGrml6rQkwyhg4VMqOju+fO8cvb bmNNxnbrHOnyLHxqZ2UjO10jehMnnacKItx4bcQg3dozs3awrmwQMFsYa/BC0SixWrUt TLnt4R+YbjF8XrvshNOXloiNOzWRW9xHmZFPQC1PPL8PB6bAxyZgSfSkAQAtLWQkwemq HSVWEhVHbigJheyPK1sON2QMeaoTIixqVtWBAGwCNYotNFaveB7RXCAOIKog5zJHrQMh pq0w== X-Gm-Message-State: AOAM5330q4GiQRpUMQ/QSqtxqFxpuESwBaI+mOodKK/YNOqiOUgRmMIh wetPtvQr3AKSarQEqFnXsKY= X-Google-Smtp-Source: ABdhPJxKfjimbhh83FJP3NjVxjOnueMIxgvyzUiJsleKSGKQvTcJUg83XoDtIuRAYNiwX3wCH5s0RQ== X-Received: by 2002:a17:90b:4c8e:b0:1c6:8dfb:3cb6 with SMTP id my14-20020a17090b4c8e00b001c68dfb3cb6mr12045726pjb.72.1647670774357; Fri, 18 Mar 2022 23:19:34 -0700 (PDT) Received: from ffyuanda.localdomain ([119.131.152.89]) by smtp.gmail.com with ESMTPSA id b2-20020a639302000000b003808dc4e133sm9235950pge.81.2022.03.18.23.19.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 18 Mar 2022 23:19:34 -0700 (PDT) From: Shaoxuan Yuan To: gitster@pobox.com Cc: derrickstolee@github.com, git@vger.kernel.org, vdye@github.com, Shaoxuan Yuan Subject: [PATCH v5 4/4] Documentation/git-sparse-checkout.txt: some reword and modifications Date: Sat, 19 Mar 2022 14:19:10 +0800 Message-Id: <20220319061910.786850-5-shaoxuan.yuan02@gmail.com> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220319061910.786850-1-shaoxuan.yuan02@gmail.com> References: <20220311132141.1817-1-shaoxuan.yuan02@gmail.com> <20220319061910.786850-1-shaoxuan.yuan02@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Modifications suggested by Junio [1] * remove redundant part under 'add' command * fix broken indentation * remove redundant part under '--[no-]cone' option [1] https://lore.kernel.org/git/xmqqfsnfb42c.fsf@gitster.g/ Helped-by: Junio C Hamano Signed-off-by: Shaoxuan Yuan --- Documentation/git-sparse-checkout.txt | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 0178d63f56..482ecfe28c 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -66,11 +66,9 @@ file. See linkgit:git-worktree[1] and the documentation of 'add':: Update the sparse-checkout file to include additional directories - (in cone mode) or patterns (in non-cone mode). By default, these - directories or patterns are read from the command-line arguments. - These directories or patterns are interpreted the same way as stated - above in `set` command, and they can be read from stdin using the - `--stdin` option. + (in cone mode) or patterns (in non-cone mode). By default, these + directories or patterns are read from the command-line arguments, + but they can be read from stdin using the `--stdin` option. 'reapply':: Reapply the sparsity pattern rules to paths in the working tree. @@ -112,10 +110,6 @@ OPTIONS '--[no-]cone':: Use with the `set` and `reapply` commands. Specify using cone mode or not. The default is to use cone mode. -+ -For the `set` command, the option to use cone mode or not changes -the interpretation of the remaining arguments to either be a list -of directories or a list of patterns. '--[no-]sparse-index':: Use with the `set` and `reapply` commands.