{"thread":{"id":"60557","subject":"[PATCH] doc: make the gitfile syntax easier to discover","startedAt":"2023-11-24T21:29:03Z","lastAt":"2023-12-03T13:15:22Z","messageCount":7,"participants":["Marcel Krause","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"485138","messageId":"20231124194711.563720-1-mk+copyleft@pimpmybyte.de","threadId":"60557","inReplyTo":null,"subject":"[PATCH] doc: make the gitfile syntax easier to discover","fromName":"Marcel Krause","fromEmail":"mk+copyleft@pimpmybyte.de","sentAt":"2023-11-24T19:47:12Z","receivedAt":"2023-11-24T21:29:03Z","isPatch":true,"sender":{"key":"mk+copyleft@pimpmybyte.de","avatar":null},"body":"It took way too long for me to find the syntax expected for a gitfile.\nMy search engine found the gitglossary manpage which defined the term\nbut had no hints about syntax.\nThus here I add a mention of gitrepository-layout.\n\nOnce I somehow found gitrepository-layout, I searched for \"gitfile\" in\nthere, but had no matches. It took a moment of discouragement and a\nminute or so of actually reading to find the info I was looking for.\nThus here I add the part \"[This mechanism is] called a 'gitfile'\" in\nhopes that future readers will find it in mere seconds and without\ndiscouragement. Maybe it even helps search engines find it.\n\nIdeally, someone else may add a mention of gitrepository-layout in the\n\"fatal: invalid gitfile format:\" error message, which is what sent me\non my journey initially, or even add a stub man page named \"gitfile\".\n\nBased on the maint branch for maximum compatibility.\n\nSigned-off-by: Marcel Krause \n---\n Documentation/gitrepository-layout.txt | 8 ++++----\n Documentation/glossary-content.txt | 1 +\n 2 files changed, 5 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\nindex 1a2ef4c150..c52b8564e3 100644\n--- a/Documentation/gitrepository-layout.txt\n+++ b/Documentation/gitrepository-layout.txt\n@@ -23,10 +23,10 @@ A Git repository comes in two different flavours:\n \n *Note*: Also you can have a plain text file `.git` at the root of\n your working tree, containing `gitdir: ` to point at the real\n-directory that has the repository. This mechanism is often used for\n-a working tree of a submodule checkout, to allow you in the\n-containing superproject to `git checkout` a branch that does not\n-have the submodule. The `checkout` has to remove the entire\n+directory that has the repository. This mechanism is called a 'gitfile'\n+and is often used for a working tree of a submodule checkout, to allow\n+you in the containing superproject to `git checkout` a branch that\n+does not have the submodule. The `checkout` has to remove the entire\n submodule working tree, without losing the submodule repository.\n \n These things may exist in a Git repository.\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 5a537268e2..e5f55bf670 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -184,6 +184,7 @@ current branch integrates with) obviously do not work, as there is no\n [[def_gitfile]]gitfile::\n \tA plain file `.git` at the root of a working tree that\n \tpoints at the directory that is the real repository.\n+\tSee linkgit:gitrepository-layout for the syntax.\n \n [[def_grafts]]grafts::\n \tGrafts enables two otherwise different lines of development to be joined\n-- \n2.25.1\n\n"},{"id":"485150","messageId":"xmqqr0kd5i66.fsf@gitster.g","threadId":"60557","inReplyTo":"20231124194711.563720-1-mk+copyleft@pimpmybyte.de","subject":"Re: [PATCH] doc: make the gitfile syntax easier to discover","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-11-26T03:04:33Z","receivedAt":"2023-11-26T03:04:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marcel Krause writes:\n\n> It took way too long for me to find the syntax expected for a gitfile.\n> My search engine found the gitglossary manpage which defined the term\n> but had no hints about syntax.\n> Thus here I add a mention of gitrepository-layout.\n\nEverything you wrote is not very interesting or relevant story we\nwant to see in order to explain and justify this change. The title\nitself is sufficient, i.e. it had poor visibility, and you fix it by\ngiving it better visibility.\n\nA more relevant is why you needed to find out what the former should\nbe in the first place. \"git submodule init\" and \"git worktree add\"\nwould create them as necessary without you needing to know about the\nexact implementation.\n\n> Signed-off-by: Marcel Krause \n> ---\n> Documentation/gitrepository-layout.txt | 8 ++++----\n> Documentation/glossary-content.txt | 1 +\n> 2 files changed, 5 insertions(+), 4 deletions(-)\n>\n> diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\n> index 1a2ef4c150..c52b8564e3 100644\n> --- a/Documentation/gitrepository-layout.txt\n> +++ b/Documentation/gitrepository-layout.txt\n> @@ -23,10 +23,10 @@ A Git repository comes in two different flavours:\n> \n> *Note*: Also you can have a plain text file `.git` at the root of\n> your working tree, containing `gitdir: ` to point at the real\n> -directory that has the repository. This mechanism is often used for\n> -a working tree of a submodule checkout, to allow you in the\n> -containing superproject to `git checkout` a branch that does not\n> -have the submodule. The `checkout` has to remove the entire\n> +directory that has the repository. This mechanism is called a 'gitfile'\n> +and is often used for a working tree of a submodule checkout, to allow\n> +you in the containing superproject to `git checkout` a branch that\n> +does not have the submodule. The `checkout` has to remove the entire\n> submodule working tree, without losing the submodule repository.\n\nDo not unnecessary rewrap existing text, only to insert a few words,\nto force reviewers read a lot more than needed.\n\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index 5a537268e2..e5f55bf670 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -184,6 +184,7 @@ current branch integrates with) obviously do not work, as there is no\n> [[def_gitfile]]gitfile::\n> \tA plain file `.git` at the root of a working tree that\n> \tpoints at the directory that is the real repository.\n> +\tSee linkgit:gitrepository-layout for the syntax.\n\nRunning \"git grep linkgit:gitrepository-layout\" would help you find\nthe right way to spell this one, I think.\n\nThanks.\n"},{"id":"485184","messageId":"70125a8e-57ed-2ac6-1260-2aaa10cbc851@pimpmybyte.de","threadId":"60557","inReplyTo":"xmqqr0kd5i66.fsf@gitster.g","subject":"Re: [PATCH] doc: make the gitfile syntax easier to discover","fromName":"Marcel Krause","fromEmail":"mk+copyleft@pimpmybyte.de","sentAt":"2023-11-28T01:51:03Z","receivedAt":"2023-11-28T01:51:06Z","isPatch":true,"sender":{"key":"mk+copyleft@pimpmybyte.de","avatar":null},"body":"Thanks for your advice! I'll prepare a new patch.\n\n\n> The title itself is sufficient, i.e. it had poor visibility, and you\n> fix it by giving it better visibility.\n\nYeah I see now, I should have sent the explanation as cover letter,\nnot as commit message.\n\n\n> more relevant is why you needed to find out what the former should\n> be in the first place.\n\nMy gitfile links worktrees on limited-capability filesystems to a\ngit repo on a nicer filesystem.\n\n^-- Should I write this in the commit message?\n\n(For the more curious: That way I sync GRUB configs accross lots of\nFAT FS thumb drives while having the main repo and main worktree on\nan ext3 FS with symlinks and proper owner/group/mode for non-config\nfiles of the project.)\n\n\n> Do not unnecessary rewrap existing text, only to insert a few\n> words, to force reviewers read a lot more than needed.\n\nThe shortest diff I can come up with would be:\n\n--- a/Documentation/gitrepository-layout.txt\n+++ b/Documentation/gitrepository-layout.txt\n@@ -25,3 +25,4 @@ A Git repository comes in two different flavours:\n your working tree, containing `gitdir: ` to point at the real\n-directory that has the repository. This mechanism is often used for\n+directory that has the repository.\n+This mechanism is called a 'gitfile' and is often used for\n a working tree of a submodule checkout, to allow you in the\n\nIt loses the double space and thus the sentence boundary information,\nbut a similar case exists in line 156 (old) so I guess it'll be ok.\n\n\n> Running \"git grep linkgit:gitrepository-layout\" would help you find\n> the right way to spell this one, I think.\n\nFound and fixed the missing \"[5]\".\nMaybe I'll try and teach our tests to catch that.\n"},{"id":"485187","messageId":"182d290a-86e5-b361-87a1-6860641fc726@pimpmybyte.de","threadId":"60557","inReplyTo":"70125a8e-57ed-2ac6-1260-2aaa10cbc851@pimpmybyte.de","subject":"Re: [PATCH] doc: make the gitfile syntax easier to discover","fromName":"Marcel Krause","fromEmail":"mk+copyleft@pimpmybyte.de","sentAt":"2023-11-28T05:55:40Z","receivedAt":"2023-11-28T05:55:42Z","isPatch":true,"sender":{"key":"mk+copyleft@pimpmybyte.de","avatar":null},"body":"Sorry for being slow on understanding your \"git worktree add\" hint.\nI agree that discoverability of that command is at least as important\nas discoverability of the syntax. I'll add a line about that, too.\n"},{"id":"485188","messageId":"20231128064821.1059728-1-mk+copyleft@pimpmybyte.de","threadId":"60557","inReplyTo":"182d290a-86e5-b361-87a1-6860641fc726@pimpmybyte.de","subject":"[PATCH] doc: make the gitfile syntax easier to discover","fromName":"Marcel Krause","fromEmail":"mk+copyleft@pimpmybyte.de","sentAt":"2023-11-28T06:48:21Z","receivedAt":"2023-11-28T06:52:06Z","isPatch":true,"sender":{"key":"mk+copyleft@pimpmybyte.de","avatar":null},"body":"---\n Documentation/gitrepository-layout.txt | 4 +++-\n Documentation/glossary-content.txt | 2 ++\n 2 files changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\nindex 1a2ef4c150..949cd8a31e 100644\n--- a/Documentation/gitrepository-layout.txt\n+++ b/Documentation/gitrepository-layout.txt\n@@ -23,7 +23,9 @@ A Git repository comes in two different flavours:\n \n *Note*: Also you can have a plain text file `.git` at the root of\n your working tree, containing `gitdir: ` to point at the real\n-directory that has the repository. This mechanism is often used for\n+directory that has the repository.\n+This mechanism is called a 'gitfile' and is usually managed via the\n+`git submodule` and `git worktree` commands. It is often used for\n a working tree of a submodule checkout, to allow you in the\n containing superproject to `git checkout` a branch that does not\n have the submodule. The `checkout` has to remove the entire\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 5a537268e2..3f912e7bb2 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -184,6 +184,8 @@ current branch integrates with) obviously do not work, as there is no\n [[def_gitfile]]gitfile::\n \tA plain file `.git` at the root of a working tree that\n \tpoints at the directory that is the real repository.\n+\tFor proper use see linkgit:git-worktree[1] or linkgit:git-submodule[1].\n+\tFor syntax see linkgit:gitrepository-layout[5].\n \n [[def_grafts]]grafts::\n \tGrafts enables two otherwise different lines of development to be joined\n-- \n2.25.1\n\n"},{"id":"485189","messageId":"20231128065558.1061206-1-mk+copyleft@pimpmybyte.de","threadId":"60557","inReplyTo":"182d290a-86e5-b361-87a1-6860641fc726@pimpmybyte.de","subject":"[PATCH] doc: make the gitfile syntax easier to discover","fromName":"Marcel Krause","fromEmail":"mk+copyleft@pimpmybyte.de","sentAt":"2023-11-28T06:55:58Z","receivedAt":"2023-11-28T06:59:17Z","isPatch":true,"sender":{"key":"mk+copyleft@pimpmybyte.de","avatar":null},"body":"Signed-off-by: Marcel Krause \n---\n Documentation/gitrepository-layout.txt | 4 +++-\n Documentation/glossary-content.txt | 2 ++\n 2 files changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\nindex 1a2ef4c150..949cd8a31e 100644\n--- a/Documentation/gitrepository-layout.txt\n+++ b/Documentation/gitrepository-layout.txt\n@@ -23,7 +23,9 @@ A Git repository comes in two different flavours:\n \n *Note*: Also you can have a plain text file `.git` at the root of\n your working tree, containing `gitdir: ` to point at the real\n-directory that has the repository. This mechanism is often used for\n+directory that has the repository.\n+This mechanism is called a 'gitfile' and is usually managed via the\n+`git submodule` and `git worktree` commands. It is often used for\n a working tree of a submodule checkout, to allow you in the\n containing superproject to `git checkout` a branch that does not\n have the submodule. The `checkout` has to remove the entire\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 5a537268e2..3f912e7bb2 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -184,6 +184,8 @@ current branch integrates with) obviously do not work, as there is no\n [[def_gitfile]]gitfile::\n \tA plain file `.git` at the root of a working tree that\n \tpoints at the directory that is the real repository.\n+\tFor proper use see linkgit:git-worktree[1] or linkgit:git-submodule[1].\n+\tFor syntax see linkgit:gitrepository-layout[5].\n \n [[def_grafts]]grafts::\n \tGrafts enables two otherwise different lines of development to be joined\n-- \n2.25.1\n\n"},{"id":"485337","messageId":"xmqq8r6b4ec8.fsf@gitster.g","threadId":"60557","inReplyTo":"20231128065558.1061206-1-mk+copyleft@pimpmybyte.de","subject":"Re: [PATCH] doc: make the gitfile syntax easier to discover","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-12-03T13:15:19Z","receivedAt":"2023-12-03T13:15:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marcel Krause writes:\n\n> Signed-off-by: Marcel Krause \n> ---\n> Documentation/gitrepository-layout.txt | 4 +++-\n> Documentation/glossary-content.txt | 2 ++\n> 2 files changed, 5 insertions(+), 1 deletion(-)\n\nLooking good. Will queue. Thanks.\n"}]}