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

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

[Marcel Krause]

It took way too long for me to find the syntax expected for a gitfile.
My search engine found the gitglossary manpage which defined the term
but had no hints about syntax.
Thus here I add a mention of gitrepository-layout.

Once I somehow found gitrepository-layout, I searched for "gitfile" in
there, but had no matches. It took a moment of discouragement and a
minute or so of actually reading to find the info I was looking for.
Thus here I add the part "[This mechanism is] called a 'gitfile'" in
hopes that future readers will find it in mere seconds and without
discouragement. Maybe it even helps search engines find it.

Ideally, someone else may add a mention of gitrepository-layout in the
"fatal: invalid gitfile format:" error message, which is what sent me
on my journey initially, or even add a stub man page named "gitfile".

Based on the maint branch for maximum compatibility.

Signed-off-by: Marcel Krause <mk+copyleft@pimpmybyte.de>
---
 Documentation/gitrepository-layout.txt | 8 ++++----
 Documentation/glossary-content.txt     | 1 +
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index 1a2ef4c150..c52b8564e3 100644
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -23,10 +23,10 @@ A Git repository comes in two different flavours:
 
 *Note*: Also you can have a plain text file `.git` at the root of
 your working tree, containing `gitdir: <path>` to point at the real
-directory that has the repository.  This mechanism is often used for
-a working tree of a submodule checkout, to allow you in the
-containing superproject to `git checkout` a branch that does not
-have the submodule.  The `checkout` has to remove the entire
+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 containing superproject to `git checkout` a branch that
+does not have the submodule.  The `checkout` has to remove the entire
 submodule working tree, without losing the submodule repository.
 
 These things may exist in a Git repository.
diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 5a537268e2..e5f55bf670 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -184,6 +184,7 @@ current branch integrates with) obviously do not work, as there is no
 [[def_gitfile]]gitfile::
 	A plain file `.git` at the root of a working tree that
 	points at the directory that is the real repository.
+	See linkgit:gitrepository-layout for the syntax.
 
 [[def_grafts]]grafts::
 	Grafts enables two otherwise different lines of development to be joined
-- 
2.25.1

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

[Junio C Hamano]

Marcel Krause <mk+copyleft@pimpmybyte.de> writes:

> It took way too long for me to find the syntax expected for a gitfile.
> My search engine found the gitglossary manpage which defined the term
> but had no hints about syntax.
> Thus here I add a mention of gitrepository-layout.

Everything you wrote is not very interesting or relevant story we
want to see in order to explain and justify this change.  The title
itself is sufficient, i.e. it had poor visibility, and you fix it by
giving it better visibility.

A more relevant is why you needed to find out what the former should
be in the first place.  "git submodule init" and "git worktree add"
would create them as necessary without you needing to know about the
exact implementation.

> Signed-off-by: Marcel Krause <mk+copyleft@pimpmybyte.de>
> ---
>  Documentation/gitrepository-layout.txt | 8 ++++----
>  Documentation/glossary-content.txt     | 1 +
>  2 files changed, 5 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
> index 1a2ef4c150..c52b8564e3 100644
> --- a/Documentation/gitrepository-layout.txt
> +++ b/Documentation/gitrepository-layout.txt
> @@ -23,10 +23,10 @@ A Git repository comes in two different flavours:
>  
>  *Note*: Also you can have a plain text file `.git` at the root of
>  your working tree, containing `gitdir: <path>` to point at the real
> -directory that has the repository.  This mechanism is often used for
> -a working tree of a submodule checkout, to allow you in the
> -containing superproject to `git checkout` a branch that does not
> -have the submodule.  The `checkout` has to remove the entire
> +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 containing superproject to `git checkout` a branch that
> +does not have the submodule.  The `checkout` has to remove the entire
>  submodule working tree, without losing the submodule repository.

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

> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> index 5a537268e2..e5f55bf670 100644
> --- a/Documentation/glossary-content.txt
> +++ b/Documentation/glossary-content.txt
> @@ -184,6 +184,7 @@ current branch integrates with) obviously do not work, as there is no
>  [[def_gitfile]]gitfile::
>  	A plain file `.git` at the root of a working tree that
>  	points at the directory that is the real repository.
> +	See linkgit:gitrepository-layout for the syntax.

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

Thanks.

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

[Marcel Krause]

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.

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

[Marcel Krause]

Sorry for being slow on understanding your "git worktree add" hint.
I agree that discoverability of that command is at least as important
as discoverability of the syntax. I'll add a line about that, too.

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

[Marcel Krause]

---
 Documentation/gitrepository-layout.txt | 4 +++-
 Documentation/glossary-content.txt     | 2 ++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index 1a2ef4c150..949cd8a31e 100644
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -23,7 +23,9 @@ A Git repository comes in two different flavours:
 
 *Note*: Also you can have a plain text file `.git` at the root of
 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 usually managed via the
+`git submodule` and `git worktree` commands. It is often used for
 a working tree of a submodule checkout, to allow you in the
 containing superproject to `git checkout` a branch that does not
 have the submodule.  The `checkout` has to remove the entire
diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 5a537268e2..3f912e7bb2 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -184,6 +184,8 @@ current branch integrates with) obviously do not work, as there is no
 [[def_gitfile]]gitfile::
 	A plain file `.git` at the root of a working tree that
 	points at the directory that is the real repository.
+	For proper use see linkgit:git-worktree[1] or linkgit:git-submodule[1].
+	For syntax see linkgit:gitrepository-layout[5].
 
 [[def_grafts]]grafts::
 	Grafts enables two otherwise different lines of development to be joined
-- 
2.25.1

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

[Marcel Krause]

Signed-off-by: Marcel Krause <mk+copyleft@pimpmybyte.de>
---
 Documentation/gitrepository-layout.txt | 4 +++-
 Documentation/glossary-content.txt     | 2 ++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index 1a2ef4c150..949cd8a31e 100644
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -23,7 +23,9 @@ A Git repository comes in two different flavours:
 
 *Note*: Also you can have a plain text file `.git` at the root of
 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 usually managed via the
+`git submodule` and `git worktree` commands. It is often used for
 a working tree of a submodule checkout, to allow you in the
 containing superproject to `git checkout` a branch that does not
 have the submodule.  The `checkout` has to remove the entire
diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
index 5a537268e2..3f912e7bb2 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.txt
@@ -184,6 +184,8 @@ current branch integrates with) obviously do not work, as there is no
 [[def_gitfile]]gitfile::
 	A plain file `.git` at the root of a working tree that
 	points at the directory that is the real repository.
+	For proper use see linkgit:git-worktree[1] or linkgit:git-submodule[1].
+	For syntax see linkgit:gitrepository-layout[5].
 
 [[def_grafts]]grafts::
 	Grafts enables two otherwise different lines of development to be joined
-- 
2.25.1

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

[Junio C Hamano]

Marcel Krause <mk+copyleft@pimpmybyte.de> writes:

> Signed-off-by: Marcel Krause <mk+copyleft@pimpmybyte.de>
> ---
>  Documentation/gitrepository-layout.txt | 4 +++-
>  Documentation/glossary-content.txt     | 2 ++
>  2 files changed, 5 insertions(+), 1 deletion(-)

Looking good.  Will queue.  Thanks.