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

[Jonathan Nieder <jrnieder@gmail.com>]

Junio C Hamano wrote:

> 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(-)

Looks correct and very readable.  Thanks.

Jonathan
(patch left unsnipped for reference)

> 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
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html