On Sun, Jan 8, 2023 at 9:54 PM Preston Tunnell Wilson <prestontunnellwilson@xxxxxxxxx> wrote: > > So, no, I don't think this qualifies for the BUGS section of > > git-wortkree, and mentioning this potential gotcha only in > > git-worktree but not in any other hook-running command doesn't seem > > ideal either. At present, the best place to discuss it seems to be > > Documentation/githooks.txt, as this patch does. > > I agree the best place to put it is in Documentation/githooks.txt. I > also agree the BUGS section doesn't make sense, but I'm still > wondering if we should call it out in git-worktree.txt in addition to > githooks.txt. When I ran into this issue, I tried to compare my setup > to that of my coworkers. The difference was that I was using > git-worktree, they were not. git-worktree's documentation lists: > > Within a linked worktree, $GIT_DIR is set to point to this private > directory (e.g. /path/main/.git/worktrees/test-next in the example) > and $GIT_COMMON_DIR is set to point back to the main worktree’s > $GIT_DIR (e.g. /path/main/.git). These settings are made in a .git > file located at the top directory of the linked worktree. > > To me, this is the "other side of the coin" of your patch. (Or maybe > one of the many other sides of the coin for commands that can run > git-hooks.) Mentioning a potential collision between git-hooks and > these variables being set could maybe go in the above snippet, maybe > in parentheses. It took a lot of working backwards to narrow the issue > to the interaction between git-worktree and git-hooks rather than the > package manager I was using or the tool the hook was calling. Putting > a note in the git-worktree documentation (in addition to the note in > git-hooks) might help out someone in the future, but I defer to your > judgement. If it doesn't make sense, doesn't fit, or adding it here > would detract and make the documentation more confusing, I am happy to > leave it out. I understand your concern, and can relate to the amount of effort it took to narrow down the problem. Nevertheless, even though you encountered this problem in relation to git-worktree, it's a more general issue which can manifest in other situations. As such, I can't think of a good way to discuss the issue in the git-worktree documentation that wouldn't feel out of place and make the documentation more confusing. I'm not necessarily opposed to someone else giving it a shot if it can be done in a way which doesn't feel out of place and doesn't confuse git-worktree documentation further (especially for those new to the documentation). I just don't know how to do so myself.
