Re: [RFC PATCH 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

From: Derrick Stolee <derrickstolee@github.com>
Date: Mar 11, 2022, 20:56 UTC
Message-ID: <dd9413da-1b8c-2adf-c471-e5fd4230375c@github.com>
In-Reply-To: <20220311132141.1817-2-shaoxuan.yuan02@gmail.com>

On 3/11/2022 8:21 AM, Shaoxuan Yuan wrote:

> Add an OPTIONS section to the manual and move the descriptions about
> these options from COMMANDS to the section.

This is a good goal.

> +OPTIONS
> +-------

However, there are a few issues with the current approach. First, I believe it would be better to start with COMMANDS, then OPTIONS.

To be fair, we are not consistent here. These commands use OPTIONS and then COMMANDS:

* git-commit-graph.txt
* git-remote.txt
* git-revert.txt

These use [SUB]COMMANDS and then OPTIONS:

* git-maintenance.txt
* git-notes.txt
* git-p4.txt
* git-stash.txt
* git-submodule.txt
* git-worktree.txt

My preference would be OPTIONS second (and we can clean up the other docs as #leftoverbits). In particular, I noticed that the SYNOPSIS for git-maintenance.txt is out of date.

Show 6 quoted lines

> +'--[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

The other issue is that this context is detailing information about the 'set' command and the input it takes. You'll want to make sure the information is properly grouped.

Show 7 quoted lines

> @@ -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'].

I do like these clear indicators of which commands allow this option. I wonder if it should instead be

	Use with the `set` and `reapply` commands.

Thanks, -Stolee