{"thread":{"id":"50098","subject":"[PATCH] doc/config: do a better job of introducing 'worktree.guessRemote'","startedAt":"2018-12-23T19:25:21Z","lastAt":"2019-01-06T18:19:53Z","messageCount":3,"participants":["Eric Sunshine","Thomas Gummerer"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"365761","messageId":"20181223192435.24803-1-sunshine@sunshineco.com","threadId":"50098","inReplyTo":null,"subject":"[PATCH] doc/config: do a better job of introducing 'worktree.guessRemote'","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2018-12-23T19:24:35Z","receivedAt":"2018-12-23T19:25:21Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"The documentation for this option jumps right in with \"With `add`\",\nwithout explaining that `add` is a sub-command of \"git worktree\".\nTogether with rather odd grammatical structure of the remainder of the\nsentence, the description can be difficult for newcomers to understand.\nClarify by improving the grammar and mentioning \"git worktree add\"\nexplicitly.\n\nReported-by: Олег Самойлов \nSigned-off-by: Eric Sunshine \n---\n\nReference: https://public-inbox.org/git/0E640233-B2CB-465D-9713-BBECE331CA80@ya.ru/\n\nDocumentation/config/worktree.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/config/worktree.txt b/Documentation/config/worktree.txt\nindex b853798fc2..048e349482 100644\n--- a/Documentation/config/worktree.txt\n+++ b/Documentation/config/worktree.txt\n@@ -1,6 +1,6 @@\n worktree.guessRemote::\n-\tWith `add`, if no branch argument, and neither of `-b` nor\n-\t`-B` nor `--detach` are given, the command defaults to\n+\tIf no branch is specified and neither `-b` nor `-B` nor\n+\t`--detach` is used, then `git worktree add` defaults to\n \tcreating a new branch from HEAD. If `worktree.guessRemote` is\n \tset to true, `worktree add` tries to find a remote-tracking\n \tbranch whose name uniquely matches the new branch name. If\n-- \n2.20.1.415.g653613c723\n\n"},{"id":"366219","messageId":"20190106180914.GE25639@hank.intra.tgummerer.com","threadId":"50098","inReplyTo":"20181223192435.24803-1-sunshine@sunshineco.com","subject":"Re: [PATCH] doc/config: do a better job of introducing 'worktree.guessRemote'","fromName":"Thomas Gummerer","fromEmail":"t.gummerer@gmail.com","sentAt":"2019-01-06T18:09:14Z","receivedAt":"2019-01-06T18:09:20Z","isPatch":true,"sender":{"key":"t.gummerer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/191004?v=4"},"body":"On 12/23, Eric Sunshine wrote:\n> The documentation for this option jumps right in with \"With `add`\",\n> without explaining that `add` is a sub-command of \"git worktree\".\n> Together with rather odd grammatical structure of the remainder of the\n> sentence, the description can be difficult for newcomers to understand.\n> Clarify by improving the grammar and mentioning \"git worktree add\"\n> explicitly.\n> \n> Reported-by: Олег Самойлов \n> Signed-off-by: Eric Sunshine \n> ---\n\nThanks, this reads much better indeed. I was briefly wondering if a\nsimilar change is needed in the documentation for the 'git worktree'\ncommand itself. It currently reads:\n\n\tWith `worktree add `, without ``, instead\n\tof creating a new branch from HEAD, if there exists a tracking\n\tbranch in exactly one remote matching the basename of ``,\n\tbase the new branch on the remote-tracking branch, and mark\n\tthe remote-tracking branch as \"upstream\" from the new branch.\n\nI do think the documentation for the config option is slightly easier\nto read, especially with your improvements below. Dunno if it's worth\nadjusting the test in the 'git worktree' documentation as well?\n\n> Reference: https://public-inbox.org/git/0E640233-B2CB-465D-9713-BBECE331CA80@ya.ru/\n> \n> Documentation/config/worktree.txt | 4 ++--\n> 1 file changed, 2 insertions(+), 2 deletions(-)\n> \n> diff --git a/Documentation/config/worktree.txt b/Documentation/config/worktree.txt\n> index b853798fc2..048e349482 100644\n> --- a/Documentation/config/worktree.txt\n> +++ b/Documentation/config/worktree.txt\n> @@ -1,6 +1,6 @@\n> worktree.guessRemote::\n> -\tWith `add`, if no branch argument, and neither of `-b` nor\n> -\t`-B` nor `--detach` are given, the command defaults to\n> +\tIf no branch is specified and neither `-b` nor `-B` nor\n> +\t`--detach` is used, then `git worktree add` defaults to\n> \tcreating a new branch from HEAD. If `worktree.guessRemote` is\n> \tset to true, `worktree add` tries to find a remote-tracking\n> \tbranch whose name uniquely matches the new branch name. If\n> -- \n> 2.20.1.415.g653613c723\n> \n"},{"id":"366222","messageId":"CAPig+cT3k4HVNY8B9bFL0Ty2stGVgzDdTuANDE829Fdj-u6S3Q@mail.gmail.com","threadId":"50098","inReplyTo":"20190106180914.GE25639@hank.intra.tgummerer.com","subject":"Re: [PATCH] doc/config: do a better job of introducing 'worktree.guessRemote'","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2019-01-06T18:19:39Z","receivedAt":"2019-01-06T18:19:53Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, Jan 6, 2019 at 1:09 PM Thomas Gummerer wrote:\n> On 12/23, Eric Sunshine wrote:\n> > The documentation for this option jumps right in with \"With `add`\",\n> > without explaining that `add` is a sub-command of \"git worktree\".\n> > Together with rather odd grammatical structure of the remainder of the\n> > sentence, the description can be difficult for newcomers to understand.\n> > Clarify by improving the grammar and mentioning \"git worktree add\"\n> > explicitly.\n>\n> Thanks, this reads much better indeed. I was briefly wondering if a\n> similar change is needed in the documentation for the 'git worktree'\n> command itself. It currently reads:\n>\n> With `worktree add `, without ``, instead\n> of creating a new branch from HEAD, if there exists a tracking\n> branch in exactly one remote matching the basename of ``,\n> base the new branch on the remote-tracking branch, and mark\n> the remote-tracking branch as \"upstream\" from the new branch.\n>\n> I do think the documentation for the config option is slightly easier\n> to read, especially with your improvements below. Dunno if it's worth\n> adjusting the test in the 'git worktree' documentation as well?\n\nSuch a change to git-worktree.txt could be done, though I think it's\noutside the scope of this patch since \"With ...,\" is not nearly so\nconfusing in the context of git-worktree.txt given that the reader\n_knows_ that he/she is reading (exclusively) about \"git worktree\".\nAlso, almost all of the options in git-worktree.txt are phrased \"With\n...,\", so such a change would be more all-encompassing.\n"}]}