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

[Junio C Hamano <gitster@pobox.com>]

Petr Baudis <pasky@suse.cz> writes:

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

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