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

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Jan 6, 2019, 18:19 UTC
Message-ID: <CAPig+cT3k4HVNY8B9bFL0Ty2stGVgzDdTuANDE829Fdj-u6S3Q@mail.gmail.com>
In-Reply-To: <20190106180914.GE25639@hank.intra.tgummerer.com>

On Sun, Jan 6, 2019 at 1:09 PM Thomas Gummerer <t.gummerer@gmail.com> wrote:

Show 21 quoted lines

> On 12/23, Eric Sunshine wrote:
> > 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.
>
> 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?

Such a change to git-worktree.txt could be done, though I think it's outside the scope of this patch since "With ...," is not nearly so confusing in the context of git-worktree.txt given that the reader _knows_ that he/she is reading (exclusively) about "git worktree". Also, almost all of the options in git-worktree.txt are phrased "With ...,", so such a change would be more all-encompassing.