Re: [PATCH 5/6] Add a description for 'gitfile' to glossary

From: Junio C Hamano <gitster@pobox.com>
To: Thomas Ackermann <th.acker@arcor.de>
Cc: git@vger.kernel.org, davvid@gmail.com,
	Lars Hjemli <hjemli@gmail.com>,
	Jens Lehmann <Jens.Lehmann@web.de>
Subject: Re: [PATCH 5/6] Add a description for 'gitfile' to glossary
Date: Fri, 01 Feb 2013 11:26:35 -0800	[thread overview]
Message-ID: <7vlib7al90.fsf@alter.siamese.dyndns.org> (raw)
In-Reply-To: <7v4nhvc1vv.fsf@alter.siamese.dyndns.org> (Junio C. Hamano's message of "Fri, 01 Feb 2013 10:41:56 -0800")

Junio C Hamano <gitster@pobox.com> writes:

> Thomas Ackermann <th.acker@arcor.de> writes:
>
>> Signed-off-by: Thomas Ackermann <th.acker@arcor.de>
>> ---
>>  Documentation/glossary-content.txt | 3 +++
>>  1 file changed, 3 insertions(+)
>>
>> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
>> index 7c15bc0..ddf2f66 100644
>> --- a/Documentation/glossary-content.txt
>> +++ b/Documentation/glossary-content.txt
>> @@ -149,6 +149,9 @@ to point at the new commit.
>>  [[def_git_archive]]Git archive::
>>  	Synonym for <<def_repository,repository>> (for arch people).
>>  
>> +[[def_gitfile]]gitfile::
>> +	A `.git` file which points to a `$GIT_DIR` (used for Git submodules).
>> +
>
> It is more like 'used by' ;-)  People are free to write their
> Porcelain system that uses this mechanism.

The series merged at e2e2def (Merge branch 'lh/git-file', 2008-05-05)
added a mention of this to repository-layout and the readers can see
how it is interpreted by Git, but I doubt that anything explains why
you may want to use it in the documentation.

How about saying something like this here in the glossary:

	A plain file `.git` at the root of a working tree that
	points at the directory that is the real repository.

And then as a separate patch, in gitrepository-layout.txt (eek---see
the other thread), we can do something like this:

 Documentation/gitrepository-layout.txt | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index 9f62886..473c6a0 100644
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -12,12 +12,24 @@ $GIT_DIR/*
 DESCRIPTION
 -----------
 
-You may find these things in your git repository (`.git`
-directory for a repository associated with your working tree, or
-`<project>.git` directory for a public 'bare' repository. It is
-also possible to have a working tree where `.git` is a plain
-ASCII file containing `gitdir: <path>`, i.e. the path to the
-real git repository).
+A Git repository comes in two different flavours:
+
+ * a `.git` directory at the root of the working tree;
+
+ * a `<project>.git` directory that is a 'bare' repository
+   (i.e. without its own working tree), that is typically used for
+   exchanging histories with others by pushing into it and fetching
+   from it.
+
+*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
+submodule working tree, without losing the submodule repository.
+
+These things may exist in a Git repository.
 
 objects::
 	Object store associated with this repository.  Usually
