Re: [PATCH] Documentation: Note about the meaning of "clone"

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 15, 2008, 20:14 UTC
Message-ID: <7vskvecv6d.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <200806151505.27686.robin.rosenberg.lists@dewire.com>

Robin Rosenberg <robin.rosenberg.lists@dewire.com> writes:

Show 22 quoted lines

> Clarify that a clone is not an exact copy.
>
> Signed-off-by: Robin Rosenberg <robin.rosenberg@dewire.com>
> ---
>  Documentation/git-clone.txt |    7 ++++++-
>  1 files changed, 6 insertions(+), 1 deletions(-)
>
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index 7973e6a..c9bc627 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -31,7 +31,12 @@ This default configuration is achieved by creating references to
>  the remote branch heads under `$GIT_DIR/refs/remotes/origin` and
>  by initializing `remote.origin.url` and `remote.origin.fetch`
>  configuration variables.
> -
> ++
> +*NOTE*: Although this command is called clone, the clone is not identical
> +in all respects. Local branches in the repository being cloned
> +becomes remote tracking branches in the clone and remote tracking
> +branches are not cloned at all. For security reasone the config sections
> +and triggers are not cloned either.

Thanks.

But the above will not lose any information content if "Although... clone," is dropped. It in fact, dropping that would make it even clearer.

Saying only "beware that neither X nor Y nor Z is done" leaves readers wondering "why not". Saying "you may assume W but that is not the case" is the same. How about expressing it a bit differently and in a more positive way? Documentation is not a place to express your frustration you felt immediately after you found out that your initial assumption did not match reality.

And there is no triggers in git. If you are improving documentation, please get your terminology straight.

I think the first three paragraphs of this manual page need major overhaul. There were not much difference between bare and non-bare clone when historical layout was used, but exactly because a clone with a working tree always use separate remotes layout, what they do is vastly different these days.

Points to stress, and the order to present them, in the rewritten first paragraphs would be:

 - There are two different kind of clones.  A bare one and non bare one.

 - A non-bare one is a way to prepare where you work in.  It is assumed
   that you will want to keep updating the resulting repository from the
   source of the cloning operation from time to time, so 'origin' is set
   up for you automatically to track its branches in remotes/origin.

 - A bare one is a way to prepare where you push into so that others can
   fetch from it.  IOW, it is a place people meet to exchange history, not
   a place where somebody actually works in to build history.  It is
   expected that people will push into the resulting repository from
   elsewhere to update it, rather than somebody will fetch into it further
   from any 'origin'.  No 'origin' is made, and branches are copied 1:1.

 - In either case, only the information from the originating repository
   that are designed to be shared are propagated.  That includes branches
   and tags, but not things that are specific for working in the
   originating repository such as config, stash, hooks and remote tracking
   branches.