Re: [PATCH] doc: make the gitfile syntax easier to discover

From: Marcel Krause <mk+copyleft@pimpmybyte.de>
Date: Nov 28, 2023, 01:51 UTC
Message-ID: <70125a8e-57ed-2ac6-1260-2aaa10cbc851@pimpmybyte.de>
In-Reply-To: <xmqqr0kd5i66.fsf@gitster.g>

Thanks for your advice! I'll prepare a new patch.

> The title itself is sufficient, i.e. it had poor visibility, and you
> fix it by giving it better visibility.

Yeah I see now, I should have sent the explanation as cover letter, not as commit message.

> more relevant is why you needed to find out what the former should
> be in the first place.

My gitfile links worktrees on limited-capability filesystems to a git repo on a nicer filesystem.

^-- Should I write this in the commit message?

(For the more curious: That way I sync GRUB configs accross lots of FAT FS thumb drives while having the main repo and main worktree on an ext3 FS with symlinks and proper owner/group/mode for non-config files of the project.)

> Do not unnecessary rewrap existing text, only to insert a few
> words, to force reviewers read a lot more than needed.

The shortest diff I can come up with would be:

--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -25,3 +25,4 @@ A Git repository comes in two different flavours:
  your working tree, containing `gitdir: <path>` to point at the real
-directory that has the repository.  This mechanism is often used for
+directory that has the repository.
+This mechanism is called a 'gitfile' and is often used for
  a working tree of a submodule checkout, to allow you in the

It loses the double space and thus the sentence boundary information,
but a similar case exists in line 156 (old) so I guess it'll be ok.


> Running "git grep linkgit:gitrepository-layout" would help you find
> the right way to spell this one, I think.

Found and fixed the missing "[5]".
Maybe I'll try and teach our tests to catch that.