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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 26, 2023, 03:04 UTC
Message-ID: <xmqqr0kd5i66.fsf@gitster.g>
In-Reply-To: <20231124194711.563720-1-mk+copyleft@pimpmybyte.de>

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.

Show 23 quoted lines

> 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.

Show 9 quoted lines

> 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.