{"thread":{"id":"47201","subject":"some apparent inaccuracies in \"man git-worktree\"","startedAt":"2017-11-14T08:44:26Z","lastAt":"2017-11-21T19:44:33Z","messageCount":4,"participants":["Robert P. J. Day","Eric Sunshine","Jonathan Nieder"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"332520","messageId":"alpine.LFD.2.21.1711140324580.12112@localhost.localdomain","threadId":"47201","inReplyTo":null,"subject":"some apparent inaccuracies in \"man git-worktree\"","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-14T08:43:48Z","receivedAt":"2017-11-14T08:44:26Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"\n more annoying pedantry (but you're used to that by now, right?) ...\nfrom \"man git-worktree\", there seem to be some inaccuracies in the\nSYNOPSIS regarding the \"add\" subcommand:\n\n git worktree add \\\n [-f] [--detach] [--checkout] [--lock] [-b ] []\n\n first, there's no mention of \"-B\" in that SYNOPSIS, even though it's\nexplained further down the man page.\n\n next, the SYNOPSIS seems misleading as it doesn't make clear that\nthe options -b, -B and --detach are mutually exclusive, which is made\nclear in the worktree.c source:\n\n if (!!opts.detach + !!opts.new_branch + !!new_branch_force > 1)\n die(_(\"-b, -B, and --detach are mutually exclusive\"));\n\nand, to some extent, further down the man page:\n\n \"If is omitted and neither -b nor -B nor --detach used,\n then, as a convenience, a new branch based at HEAD is created\n automatically, as if -b $(basename ) was specified.\"\n\n finally (and maybe i'm just not reading carefully enough), it's not\nclear what happens if you add a worktree at a given commit without\nspecifying *any* of -b, -B or --detach. the obvious result should be a\nnew worktree checked out at a detached HEAD and, interestingly, if i\ndo that, then from the main tree, i see:\n\n $ git worktree list\n /home/rpjday/k/git 516fb7f2e73d [master]\n /home/rpjday/k/temp c470abd4fde4 (detached HEAD)\n $\n\nbut from within the worktree, if i ask for the status, i see only:\n\n $ git status\n Not currently on any branch.\n nothing to commit, working tree clean\n $\n\nwhere i would normally have expected to see \"detached HEAD\", is there\na reason that's not displayed?\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day Ottawa, Ontario, CANADA\n http://crashcourse.ca\n\nTwitter: http://twitter.com/rpjday\nLinkedIn: http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"332560","messageId":"CAPig+cRc7Yqeys=oPEgPnyR4qT7qKYLbH1ifnp+6F6N+mSzNVA@mail.gmail.com","threadId":"47201","inReplyTo":"alpine.LFD.2.21.1711140324580.12112@localhost.localdomain","subject":"Re: some apparent inaccuracies in \"man git-worktree\"","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2017-11-14T18:33:14Z","receivedAt":"2017-11-14T18:33:21Z","isPatch":false,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Tue, Nov 14, 2017 at 3:43 AM, Robert P. J. Day wrote:\n> from \"man git-worktree\", there seem to be some inaccuracies in the\n> SYNOPSIS regarding the \"add\" subcommand:\n>\n> git worktree add \\\n> [-f] [--detach] [--checkout] [--lock] [-b ] []\n>\n> first, there's no mention of \"-B\" in that SYNOPSIS, even though it's\n> explained further down the man page.\n\nOmission of \"-B\" from the synopsis was intentional. From cbdf60fa18\n(worktree: add -b/-B options, 2015-07-06):\n\n worktree: add -b/-B options\n\n One of git-worktree's roles is to populate the new worktree, much like\n git-checkout, and thus, for convenience, ought to support several of the\n same shortcuts. Toward this goal, add -b/-B options to create a new\n branch and check it out in the new worktree.\n\n (For brevity, only -b is mentioned in the synopsis; -B is omitted.)\n\nWhether or not the omission was actually a good decision is\nquestionable. The thinking, at the time, may have been that users\nalready familiar with \"-b\" in 'git checkout' would likewise be\nfamiliar with (and be able to infer) \"-B\", thus it wasn't important to\nstate its existence explicitly in the synopsis, which was already\ngetting lengthy. Of course, that decision does not assist newcomers,\nso adding \"-B\" to the synopsis would help the page better stand on its\nown.\n\n> next, the SYNOPSIS seems misleading as it doesn't make clear that\n> the options -b, -B and --detach are mutually exclusive, which is made\n> clear in the worktree.c source:\n>\n> if (!!opts.detach + !!opts.new_branch + !!new_branch_force > 1)\n> die(_(\"-b, -B, and --detach are mutually exclusive\"));\n\nFailure to update the synopsis to indicate mutual exclusion appears to\nbe a simple oversight in ab0b2c53ed (worktree: make --detach mutually\nexclusive with -b/-B, 2015-07-17) in response to:\nhttps://public-inbox.org/git/55A8F4B1.9060304@drmicha.warpmail.net/\n\n> finally (and maybe i'm just not reading carefully enough), it's not\n> clear what happens if you add a worktree at a given commit without\n> specifying *any* of -b, -B or --detach. the obvious result should be a\n> new worktree checked out at a detached HEAD and, interestingly, if i\n> do that, then from the main tree, i see:\n>\n> $ git worktree list\n> /home/rpjday/k/git 516fb7f2e73d [master]\n> /home/rpjday/k/temp c470abd4fde4 (detached HEAD)\n> $\n>\n> but from within the worktree, if i ask for the status, i see only:\n>\n> $ git status\n> Not currently on any branch.\n> nothing to commit, working tree clean\n> $\n>\n> where i would normally have expected to see \"detached HEAD\", is there\n> a reason that's not displayed?\n\nSomeone more familiar with this bit can correct me if I'm wrong, but I\nbelieve that the \"HEAD detached at/from \" you normally see\nwith 'git status' is derived from the reflog, and if it can't find the\ninformation in the reflog, it instead shows the generic \"Not currently\non any branch\" (which is the equivalent of the \"(detached HEAD)\" you\nsee in \"git worktree list\").\n\nEach worktree has its own newly-created reflog, which does _not_\ncontain enough information for 'git status' to present the more\ndetailed \"detached\" message, thus it falls back to the generic one.\nPerhaps seeding the worktree's reflog with a bit more information at\ncreation time would be a good #leftoverbits task.\n"},{"id":"332568","messageId":"alpine.LFD.2.21.1711141509280.3970@localhost.localdomain","threadId":"47201","inReplyTo":"CAPig+cRc7Yqeys=oPEgPnyR4qT7qKYLbH1ifnp+6F6N+mSzNVA@mail.gmail.com","subject":"Re: some apparent inaccuracies in \"man git-worktree\"","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-14T20:10:34Z","receivedAt":"2017-11-14T20:11:34Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"On Tue, 14 Nov 2017, Eric Sunshine wrote:\n\n> On Tue, Nov 14, 2017 at 3:43 AM, Robert P. J. Day wrote:\n> > from \"man git-worktree\", there seem to be some inaccuracies in the\n> > SYNOPSIS regarding the \"add\" subcommand:\n> >\n> > git worktree add \\\n> > [-f] [--detach] [--checkout] [--lock] [-b ] []\n> >\n> > first, there's no mention of \"-B\" in that SYNOPSIS, even though it's\n> > explained further down the man page.\n>\n> Omission of \"-B\" from the synopsis was intentional. From cbdf60fa18\n> (worktree: add -b/-B options, 2015-07-06):\n>\n> worktree: add -b/-B options\n>\n> One of git-worktree's roles is to populate the new worktree, much like\n> git-checkout, and thus, for convenience, ought to support several of the\n> same shortcuts. Toward this goal, add -b/-B options to create a new\n> branch and check it out in the new worktree.\n>\n> (For brevity, only -b is mentioned in the synopsis; -B is omitted.)\n>\n> Whether or not the omission was actually a good decision is\n> questionable. The thinking, at the time, may have been that users\n> already familiar with \"-b\" in 'git checkout' would likewise be\n> familiar with (and be able to infer) \"-B\", thus it wasn't important to\n> state its existence explicitly in the synopsis, which was already\n> getting lengthy. Of course, that decision does not assist newcomers,\n> so adding \"-B\" to the synopsis would help the page better stand on its\n> own.\n>\n> > next, the SYNOPSIS seems misleading as it doesn't make clear that\n> > the options -b, -B and --detach are mutually exclusive, which is made\n> > clear in the worktree.c source:\n> >\n> > if (!!opts.detach + !!opts.new_branch + !!new_branch_force > 1)\n> > die(_(\"-b, -B, and --detach are mutually exclusive\"));\n>\n> Failure to update the synopsis to indicate mutual exclusion appears to\n> be a simple oversight in ab0b2c53ed (worktree: make --detach mutually\n> exclusive with -b/-B, 2015-07-17) in response to:\n> https://public-inbox.org/git/55A8F4B1.9060304@drmicha.warpmail.net/\n>\n> > finally (and maybe i'm just not reading carefully enough), it's not\n> > clear what happens if you add a worktree at a given commit without\n> > specifying *any* of -b, -B or --detach. the obvious result should be a\n> > new worktree checked out at a detached HEAD and, interestingly, if i\n> > do that, then from the main tree, i see:\n> >\n> > $ git worktree list\n> > /home/rpjday/k/git 516fb7f2e73d [master]\n> > /home/rpjday/k/temp c470abd4fde4 (detached HEAD)\n> > $\n> >\n> > but from within the worktree, if i ask for the status, i see only:\n> >\n> > $ git status\n> > Not currently on any branch.\n> > nothing to commit, working tree clean\n> > $\n> >\n> > where i would normally have expected to see \"detached HEAD\", is there\n> > a reason that's not displayed?\n>\n> Someone more familiar with this bit can correct me if I'm wrong, but I\n> believe that the \"HEAD detached at/from \" you normally see\n> with 'git status' is derived from the reflog, and if it can't find the\n> information in the reflog, it instead shows the generic \"Not currently\n> on any branch\" (which is the equivalent of the \"(detached HEAD)\" you\n> see in \"git worktree list\").\n>\n> Each worktree has its own newly-created reflog, which does _not_\n> contain enough information for 'git status' to present the more\n> detailed \"detached\" message, thus it falls back to the generic one.\n> Perhaps seeding the worktree's reflog with a bit more information at\n> creation time would be a good #leftoverbits task.\n\n i'm not sure what i can add to this, but i'm going to leave it to\nfolks higher up the food chain than me to resolve any of the above.\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day Ottawa, Ontario, CANADA\n http://crashcourse.ca\n\nTwitter: http://twitter.com/rpjday\nLinkedIn: http://ca.linkedin.com/in/rpjday\n========================================================================\n"},{"id":"333124","messageId":"20171121194423.GH3429@aiede.mtv.corp.google.com","threadId":"47201","inReplyTo":"alpine.LFD.2.21.1711141509280.3970@localhost.localdomain","subject":"Re: some apparent inaccuracies in \"man git-worktree\"","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2017-11-21T19:44:23Z","receivedAt":"2017-11-21T19:44:33Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nRobert P. J. Day wrote:\n> On Tue, 14 Nov 2017, Eric Sunshine wrote:\n>> On Tue, Nov 14, 2017 at 3:43 AM, Robert P. J. Day wrote:\n\n>>> from \"man git-worktree\", there seem to be some inaccuracies in the\n>>> SYNOPSIS regarding the \"add\" subcommand:\n>>>\n>>> git worktree add \\\n>>> [-f] [--detach] [--checkout] [--lock] [-b ] []\n>>>\n>>> first, there's no mention of \"-B\" in that SYNOPSIS, even though it's\n>>> explained further down the man page.\n>>\n>> Omission of \"-B\" from the synopsis was intentional. From cbdf60fa18\n>> (worktree: add -b/-B options, 2015-07-06):\n[...]\n>> Whether or not the omission was actually a good decision is\n>> questionable.\n[...]\n>>> next, the SYNOPSIS seems misleading as it doesn't make clear that\n>>> the options -b, -B and --detach are mutually exclusive, which is made\n>>> clear in the worktree.c source:\n[...]\n>> Failure to update the synopsis to indicate mutual exclusion appears to\n>> be a simple oversight in ab0b2c53ed (worktree: make --detach mutually\n>> exclusive with -b/-B, 2015-07-17)\n[...]\n>>> finally (and maybe i'm just not reading carefully enough), it's not\n>>> clear what happens if you add a worktree at a given commit without\n>>> specifying *any* of -b, -B or --detach. the obvious result should be a\n>>> new worktree checked out at a detached HEAD and, interestingly, if i\n>>> do that, then from the main tree, i see:\n>>>\n>>> $ git worktree list\n>>> /home/rpjday/k/git 516fb7f2e73d [master]\n>>> /home/rpjday/k/temp c470abd4fde4 (detached HEAD)\n>>> $\n>>>\n>>> but from within the worktree, if i ask for the status, i see only:\n>>>\n>>> $ git status\n>>> Not currently on any branch.\n>>> nothing to commit, working tree clean\n>>> $\n>>>\n>>> where i would normally have expected to see \"detached HEAD\", is there\n>>> a reason that's not displayed?\n>>\n>> Someone more familiar with this bit can correct me if I'm wrong, but I\n>> believe that the \"HEAD detached at/from \" you normally see\n>> with 'git status' is derived from the reflog,\n[...]\n> i'm not sure what i can add to this, but i'm going to leave it to\n> folks higher up the food chain than me to resolve any of the above.\n\nFor what it's worth, the folks higher up the food chain you're\nreferring to don't exist, so the most likely outcome here is that\nnothing happens. People working on patches (suggesting wording,\nformatting as a patch, reviewing, testing, etc) are as high on the\nfood chain as it gets. :)\n\nOne thing we've discussed on this list before is setting up a bug\ntracker to allow people another way to collaborate (filing a clear\nsummary of a problem for interested people to work on). More on that\nsubject later today --- feel free to poke me if I don't get such a\nmessage out.\n\nThanks,\nJonathan\n"}]}