Re: [PATCH] doc/config: do a better job of introducing 'worktree.guessRemote'

From: Thomas Gummerer <t.gummerer@gmail.com>
Date: Jan 6, 2019, 18:09 UTC
Message-ID: <20190106180914.GE25639@hank.intra.tgummerer.com>
In-Reply-To: <20181223192435.24803-1-sunshine@sunshineco.com>

On 12/23, Eric Sunshine wrote:

Show 10 quoted lines

> The documentation for this option jumps right in with "With `add`",
> without explaining that `add` is a sub-command of "git worktree".
> Together with rather odd grammatical structure of the remainder of the
> sentence, the description can be difficult for newcomers to understand.
> Clarify by improving the grammar and mentioning "git worktree add"
> explicitly.
> 
> Reported-by: Олег Самойлов <splarv@ya.ru>
> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
> ---

Thanks, this reads much better indeed. I was briefly wondering if a similar change is needed in the documentation for the 'git worktree' command itself. It currently reads:

	With `worktree add <path>`, without `<commit-ish>`, instead
	of creating a new branch from HEAD, if there exists a tracking
	branch in exactly one remote matching the basename of `<path>`,
	base the new branch on the remote-tracking branch, and mark
	the remote-tracking branch as "upstream" from the new branch.

I do think the documentation for the config option is slightly easier to read, especially with your improvements below. Dunno if it's worth adjusting the test in the 'git worktree' documentation as well?

Show 21 quoted lines

> Reference: https://public-inbox.org/git/0E640233-B2CB-465D-9713-BBECE331CA80@ya.ru/
> 
> Documentation/config/worktree.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/config/worktree.txt b/Documentation/config/worktree.txt
> index b853798fc2..048e349482 100644
> --- a/Documentation/config/worktree.txt
> +++ b/Documentation/config/worktree.txt
> @@ -1,6 +1,6 @@
>  worktree.guessRemote::
> -	With `add`, if no branch argument, and neither of `-b` nor
> -	`-B` nor `--detach` are given, the command defaults to
> +	If no branch is specified and neither `-b` nor `-B` nor
> +	`--detach` is used, then `git worktree add` defaults to
>  	creating a new branch from HEAD.  If `worktree.guessRemote` is
>  	set to true, `worktree add` tries to find a remote-tracking
>  	branch whose name uniquely matches the new branch name.  If
> -- 
> 2.20.1.415.g653613c723
>