Re: [PATCHv2] Documentation/git-submodule.txt: Add Description section

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 16, 2008, 19:29 UTC
Message-ID: <7vej5tr5kv.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <20080716184248.6524.38463.stgit@localhost>

Petr Baudis <pasky@suse.cz> writes:

Show 12 quoted lines

> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index 76702a0..87c4ece 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -16,6 +16,28 @@ SYNOPSIS
>  'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
>  
>  
> +DESCRIPTION
> +-----------
> +Submodules are a special kind of tree entries which refer to a particular tree
> +in another repository (living at a given URL).  ...

In the documentation, "tree" has a specific meaning. Perhaps "a particular tree state" is a better wording than another alternative "a particular commit", because you mention "the exact revision" in the following sentence.

I'd suggest dropping " (living at a given URL)" from here, though.

> ...  The tree entry describes
> +the existence of a submodule with the given name and the exact revision that
> +should be used, while the location of the repository is described in the
> +`/.gitmodules` file.

Strictly speaking, ".gitmodules" merely gives a hint to be used by "submodule init", the canonical location from which the repository is expected to be cloned. I do not think this overview needs to go into such a detail. The description of "init" subcommand might need clarification, though.

Show 12 quoted lines

> +When checked out, submodules will maintain their own independent repositories
> +within their directories; the only link between the submodule and the "parent
> +project" is the tree entry within the parent project mentioned above.
> +
> +This command will manage the tree entries and contents of the gitmodules file
> +for you, as well as inspecting the status of your submodules and updating them.
> +When adding a new submodule to the tree, the 'add' subcommand is to be used.
> +However, when pulling a tree containing submodules, these will not be checked
> +out by default; the 'init' and 'update' subcommands will maintain submodules
> +checked out and at appropriate revision in your working tree. You can inspect
> +the current status of your submodules using the 'submodule' subcommand and get
> +an overview of changes 'update' would perform using the 'summary' subcommand.

Otherwise this is a nice write-up. Will queue; further comments from other submodule users are appreciated if there are any. Thanks.