Re: [PATCH] config doc: add missing list separator for checkout.optimizeNewBranch

From: Jeff King <peff@peff.net>
Date: Sep 18, 2018, 17:13 UTC
Message-ID: <20180918171317.GB15470@sigill.intra.peff.net>
In-Reply-To: <20180918053449.14047-1-avarab@gmail.com>

On Tue, Sep 18, 2018 at 05:34:49AM +0000, Ævar Arnfjörð Bjarmason wrote:

Show 5 quoted lines

> The documentation added in fa655d8411 ("checkout: optimize "git
> checkout -b <new_branch>"", 2018-08-16) didn't add the double-colon
> needed for the labeled list separator, as a result the added
> documentation all got squashed into one paragraph. Fix that by adding
> the list separator.

Obviously the right thing to do, but your patch does not seem to apply on that commit. Looks like you built it on a more recent commit that also has checkout.defaultRemote (i.e., probably 'next')?

Show 13 quoted lines

> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index ac71ade256..1546833213 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -1153,7 +1153,7 @@ and by linkgit:git-worktree[1] when 'git worktree add' refers to a
>  remote branch. This setting might be used for other checkout-like
>  commands or functionality in the future.
>  
> -checkout.optimizeNewBranch
> +checkout.optimizeNewBranch::
>  	Optimizes the performance of "git checkout -b <new_branch>" when
>  	using sparse-checkout.  When set to true, git will not update the
>  	repo based on the current sparse-checkout settings.  This means it

Now the real reason I responded. :)

I just want to plug the recently-added "doc-diff" script, which diffs a rendered view and makes it easier to catch cases like this. E.g., after applying your patch:

  $ cd Documentation
  $ ./doc-diff HEAD^ HEAD
  [...]
  diff --git a/6ad88fd5d99b8dcbb69c6f3239ad41e66516d8f7/none/share/man/man1/git-config.1 b/28e258682021a09cd7842e4edbb21ad231c8bb7a/none/share/man/man1/git-config.1
  index 7298292112..fa91b5f2d1 100644
  --- a/6ad88fd5d99b8dcbb69c6f3239ad41e66516d8f7/none/share/man/man1/git-config.1
  +++ b/28e258682021a09cd7842e4edbb21ad231c8bb7a/none/share/man/man1/git-config.1
  @@ -1533,12 +1533,13 @@ CONFIGURATION FILE
              branch. This setting might be used for other checkout-like commands
              or functionality in the future.
   
  -       checkout.optimizeNewBranch Optimizes the performance of "git checkout
  -       -b <new_branch>" when using sparse-checkout. When set to true, git will
  -       not update the repo based on the current sparse-checkout settings. This
  -       means it will not update the skip-worktree bit in the index nor
  -       add/remove files in the working directory to reflect the current sparse
  -       checkout settings nor will it show the local changes.
  +       checkout.optimizeNewBranch
  +           Optimizes the performance of "git checkout -b <new_branch>" when
  +           using sparse-checkout. When set to true, git will not update the
  +           repo based on the current sparse-checkout settings. This means it
  +           will not update the skip-worktree bit in the index nor add/remove
  +           files in the working directory to reflect the current sparse
  +           checkout settings nor will it show the local changes.
   
          clean.requireForce
              A boolean to make git-clean do nothing unless given -f, -i or -n.

Obviously we knew this fix was going to help, but running it on the original fa655d8411 (versus its parent) and eyeballing the result might have caught this sooner.

(Though I would not be at all surprised to hear that the script does not run on Windows, as it relies on things like "man"; patches certainly welcome).

-Peff