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

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

[Petr Baudis]

Figuring out how submodules work conceptually is quite a bumpy
ride for a newcomer; the user manual helps (if one knows to actually
look into it), but the reference documentation should provide good
quick intro as well. This patch attempts to do that.

Signed-off-by: Petr Baudis <pasky@suse.cz>
---

 Documentation/git-submodule.txt |   18 ++++++++++++++++++
 1 files changed, 18 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 105fc2d..3413704 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -16,6 +16,24 @@ SYNOPSIS
 'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
 
 
+DESCRIPTION
+-----------
+Submodules are a special kind of tree entries which do not refer to a blob or
+a directory, but to a particular tree in another repository (living at a given
+URL).  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.  This command will manage
+the tree entries and contents of this 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.
+
+
 COMMANDS
 --------
 add::

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

[Junio C Hamano]

Petr Baudis <pasky@suse.cz> writes:

> Figuring out how submodules work conceptually is quite a bumpy
> ride for a newcomer; the user manual helps (if one knows to actually
> look into it), but the reference documentation should provide good
> quick intro as well. This patch attempts to do that.

Good discussion starter, I think.  There seem to be a few technical
inaccuracies though.

I'll wait until the people interested in submodules on the list form
consensus on the wording and contents.

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

[Heikki Orsila]

On Tue, Jul 15, 2008 at 12:22:07PM +0200, Petr Baudis wrote:
> +Submodules are a special kind of tree entries which do not refer to a blob or
> +a directory, but to a particular tree in another repository (living at a given
> +URL). 

Better to say what a submodule is, rather than what it isn't:

"Submodules are a special kind of tree entries which refer to a 
particular tree in another repository ..."

Also, I think you should make the following explicit:

"A submodule is visible as subdirectory in the working directory.
However, the submodule is not part of the main repository.
This is a differene to "remotes". In remotes only the contents of 
other repositories is tracked, but their content is not visible in the
working directory."

-- 
Heikki Orsila
heikki.orsila@iki.fi
http://www.iki.fi/shd

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

[Petr Baudis]

Figuring out how submodules work conceptually is quite a bumpy
ride for a newcomer; the user manual helps (if one knows to actually
look into it), but the reference documentation should provide good
quick intro as well. This patch attempts to do that, with suggestions
from Heikki Orsila.

Cc: Heikki Orsila <shdl@zakalwe.fi>
Signed-off-by: Petr Baudis <pasky@suse.cz>
---

I have adjusted the description a bit; however, I believe mentioning remotes in
the description would only raise the danger of confusion - I emphasized the
level of separation, though.

 Documentation/git-submodule.txt |   22 ++++++++++++++++++++++
 1 files changed, 22 insertions(+), 0 deletions(-)

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).  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.
+
+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.
+
+
 COMMANDS
 --------
 add::

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

[Kalle Olavi Niemitalo]

Petr Baudis <pasky@suse.cz> writes:

> +Submodules are a special kind of tree entries which refer to a particular tree
> +in another repository (living at a given URL).  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.

I was surprised to learn that a commit ID in a tree does not
prevent Git from pruning the corresponding commit object if
one happens to exist in the same repository.  That might be
best documented under "Tree Object" in user-manual.txt though,
rather than in git-submodule.txt.

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

[Junio C Hamano]

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.

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

[Heikki Orsila]

On Wed, Jul 16, 2008 at 08:44:12PM +0200, Petr Baudis wrote:
> I have adjusted the description a bit; however, I believe mentioning
> remotes in
> the description would only raise the danger of confusion - I emphasized the
> level of separation, though.

I think not doing a comparison actually creates confusion. My immediate 
thought about submodules was "how does this differ from remotes? why do 
submodules exist rather than just remotes?"

-- 
Heikki Orsila
heikki.orsila@iki.fi
http://www.iki.fi/shd

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

[Petr Baudis]

On Wed, Jul 16, 2008 at 12:29:03PM -0700, Junio C Hamano wrote:
> 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.

The two sentences are now highly redundant, so...

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

...actually, in the end I have completely rewritten this yet again. The
description was too low-level (and kind of in fact explained gitlinks
instead of submodules), while we should carefully explain the high-level
concept of submodules first, only then talk about tree entries.

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

I believe we should mention it. The users *will* see this file e.g.
during submodule merges, as well as in git status output when
manipulating submodules.


On Thu, Jul 17, 2008 at 01:41:24PM +0300, Heikki Orsila wrote:
> On Wed, Jul 16, 2008 at 08:44:12PM +0200, Petr Baudis wrote:
> > I have adjusted the description a bit; however, I believe mentioning
> > remotes in
> > the description would only raise the danger of confusion - I emphasized the
> > level of separation, though.
> 
> I think not doing a comparison actually creates confusion. My immediate 
> thought about submodules was "how does this differ from remotes? why do 
> submodules exist rather than just remotes?"

Ok, now I realize this is a good point, and it's a nice chance to give a
plug for the subtree merge strategy as an alternative. ;-)

-- 
				Petr "Pasky" Baudis
GNU, n. An animal of South Africa, which in its domesticated state
resembles a horse, a buffalo and a stag. In its wild condition it is
something like a thunderbolt, an earthquake and a cyclone. -- A. Pierce

[PATCH] Documentation/git-submodule.txt: Further clarify the description

[Petr Baudis]

This patch rewrites the general description yet again, first clarifying
the high-level concept, mentioning the difference to remotes and using
the subtree merge strategy, then getting to the details about tree
entries and .gitmodules file.

The patch also makes few smallar grammar fixups of the rest of the
description and clarifies how does 'init' relate to 'update --init'.

Cc: Heikki Orsila <shdl@zakalwe.fi>
Signed-off-by: Petr Baudis <pasky@suse.cz>
---

 Documentation/git-submodule.txt |   39 +++++++++++++++++++++++++++------------
 1 files changed, 27 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index bb4e6fb..01d0d91 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -18,24 +18,35 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Submodules are a special kind of tree entries which refer to a particular tree
-state in another repository.  The tree entry describes
-the existence of a submodule with the given name and the exact revision that
-should be used, while an entry in `.gitmodules` file gives the location of
-the repository.
-
-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.
+Submodules allow foreign repositories to be embedded within a dedicated
+subdirectory of the source tree, always pointed at a particular commit.
+They are not to be confused with remotes, which are meant mainly for branches
+of the same project; submodules are meant for different projects you would like
+to make part of your source tree, while the history of the two projects still
+stays completely independent and you cannot modify the contents of the
+submodule from within the main project.  In case you want to merge the project
+histories, possibly make local modifications within the tree, but also do not
+mind that your repository will bulk up with all the contents of the other
+project, consider adding a remote for the other project and using the 'subtree'
+merge strategy instead of setting up a submodule.
+
+Submodules are composed from a special kind of tree entry (so-called `gitlink`)
+in the main repository that refers to a particular commit object within
+the (completely separate) inner repository, and a record in the `.gitmodules`
+file at the root of the source tree, assigning a logical name to the submodule
+and describing the default URL the submodule shall be cloned from. The logical
+name can be used for overriding this URL within your local repository
+configuration (see 'submodule init').
 
 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.
+for you, as well as inspect the status of your submodules and update 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.
+an overview of the changes 'update' would perform using the 'summary'
+subcommand.
 
 
 COMMANDS
@@ -81,7 +92,11 @@ init::
 	Initialize the submodules, i.e. register in .git/config each submodule
 	name and url found in .gitmodules. The key used in .git/config is
 	`submodule.$name.url`. This command does not alter existing information
-	in .git/config.
+	in .git/config. You can then customize the submodule clone URLs in
+	.git/config for your local setup and proceed to 'git submodule update';
+	you can also just use 'git submodule update --init' without
+	the explicit 'init' step if you do not intend to customize any
+	submodule URLs.
 
 update::
 	Update the registered submodules, i.e. clone missing submodules and

Re: [PATCH] Documentation/git-submodule.txt: Further clarify the description

[Heikki Orsila]

On Thu, Jul 17, 2008 at 02:29:20PM +0200, Petr Baudis wrote:
> +Submodules allow foreign repositories to be embedded within a dedicated
> +subdirectory of the source tree, always pointed at a particular commit.
> +They are not to be confused with remotes, which are meant mainly for branches
> +of the same project; submodules are meant for different projects you would like
> +to make part of your source tree, while the history of the two projects still
> +stays completely independent and you cannot modify the contents of the
> +submodule from within the main project.

That is nice, thanks!

-- 
Heikki Orsila
heikki.orsila@iki.fi
http://www.iki.fi/shd

Re: [PATCH] Documentation/git-submodule.txt: Further clarify the description

[Junio C Hamano]

Petr Baudis <pasky@suse.cz> writes:

> This patch rewrites the general description yet again, first clarifying
> the high-level concept, mentioning the difference to remotes and using
> the subtree merge strategy, then getting to the details about tree
> entries and .gitmodules file.
>
> The patch also makes few smallar grammar fixups of the rest of the
> description and clarifies how does 'init' relate to 'update --init'.
>
> Cc: Heikki Orsila <shdl@zakalwe.fi>
> Signed-off-by: Petr Baudis <pasky@suse.cz>
> ---
>
>  Documentation/git-submodule.txt |   39 +++++++++++++++++++++++++++------------
>  1 files changed, 27 insertions(+), 12 deletions(-)
>
> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
> index bb4e6fb..01d0d91 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -18,24 +18,35 @@ SYNOPSIS
>  
>  DESCRIPTION
>  -----------
> +Submodules allow foreign repositories to be embedded within a dedicated
> +subdirectory of the source tree, always pointed at a particular commit.
> +They are not to be confused with remotes, which are meant mainly for branches
> +of the same project; submodules are meant for different projects you would like

Your lines are getting overlong to be easily quoted and commented...

> +....  In case you want to merge the project
> +histories, possibly make local modifications within the tree, but also do not
> +mind that your repository will bulk up with all the contents of the other
> +project, consider adding a remote for the other project and using the 'subtree'
> +merge strategy instead of setting up a submodule.

I'd suggest rephrasing "do not mind" to something a lot less nagative.
The user decides to merge because both histories *are* relevant and at
that point there is no _minding_ anymore.  If you want to have them, you
not only "do not mind to have" them but you positively "want" them.

On the other hand, a situation where you would want to use submodules is
when not necessarily all users of the superproject would want to have all
submodules cloned nor checked out.  This needs to be stressed with equal
weight as the above sentence in this "contrasting merged histories and
submodules" paragraph.  With that explained clearly upfront, it would
become easier for the readers to understand why you can choose not to even
update nor fetch submodules you are not interested in.

> +Submodules are composed from a special kind of tree entry (so-called `gitlink`)
> +in the main repository that refers to a particular commit object within

Do we have to say "special"?  Is a gitlink any more special than blob and
tree entries are?  It tends to be rarer, it came later, but I do not think
there is anything special from the end user's point of view.

>  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 the changes 'update' would perform using the 'summary'
> +subcommand.

Sorry, cannot parse the last three lines...

Re: [PATCH] Documentation/git-submodule.txt: Further clarify the description

[Petr Baudis]

On Thu, Jul 17, 2008 at 01:24:22PM -0700, Junio C Hamano wrote:
> Your lines are getting overlong to be easily quoted and commented...

I will watch for that.

> Petr Baudis <pasky@suse.cz> writes:
> > +....  In case you want to merge the project
> > +histories, possibly make local modifications within the tree, but also do not
> > +mind that your repository will bulk up with all the contents of the other
> > +project, consider adding a remote for the other project and using the 'subtree'
> > +merge strategy instead of setting up a submodule.
> 
> I'd suggest rephrasing "do not mind" to something a lot less nagative.
> The user decides to merge because both histories *are* relevant and at
> that point there is no _minding_ anymore.  If you want to have them, you
> not only "do not mind to have" them but you positively "want" them.
> 
> On the other hand, a situation where you would want to use submodules is
> when not necessarily all users of the superproject would want to have all
> submodules cloned nor checked out.  This needs to be stressed with equal
> weight as the above sentence in this "contrasting merged histories and
> submodules" paragraph.  With that explained clearly upfront, it would
> become easier for the readers to understand why you can choose not to even
> update nor fetch submodules you are not interested in.

You are right. I have tried to reword the sentence to fix these issues.

> > +Submodules are composed from a special kind of tree entry (so-called `gitlink`)
> > +in the main repository that refers to a particular commit object within
> 
> Do we have to say "special"?  Is a gitlink any more special than blob and
> tree entries are?  It tends to be rarer, it came later, but I do not think
> there is anything special from the end user's point of view.

Also the parenthesis look ugly, so I have reworded this to a simpler
formulation.

> >  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 the changes 'update' would perform using the 'summary'
> > +subcommand.
> 
> Sorry, cannot parse the last three lines...

The mention of 'update' is confusing, and it was overally imprecise.
(I think that in general, the summary/status distinction was not a wise
UI decision.)

-- 
				Petr "Pasky" Baudis
As in certain cults it is possible to kill a process if you know
its true name.  -- Ken Thompson and Dennis M. Ritchie

[PATCH] Documentation/git-submodule.txt: Further clarify the description

[Petr Baudis]

This patch rewrites the general description yet again, first clarifying
the high-level concept, mentioning the difference to remotes and using
the subtree merge strategy, then getting to the details about tree
entries and .gitmodules file.

The patch also makes few smallar grammar fixups within the rest of the
description and clarifies how does 'init' relate to 'update --init'.

Cc: Heikki Orsila <shdl@zakalwe.fi>
Signed-off-by: Petr Baudis <pasky@suse.cz>
---

 Documentation/git-submodule.txt |   68 ++++++++++++++++++++++++++-------------
 1 files changed, 46 insertions(+), 22 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index bb4e6fb..755142c 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -18,24 +18,43 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Submodules are a special kind of tree entries which refer to a particular tree
-state in another repository.  The tree entry describes
-the existence of a submodule with the given name and the exact revision that
-should be used, while an entry in `.gitmodules` file gives the location of
-the repository.
-
-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.
+Submodules allow foreign repositories to be embedded within
+a dedicated subdirectory of the source tree, always pointed
+at a particular commit.
+
+They are not to be confused with remotes, which are meant mainly
+for branches of the same project; submodules are meant for
+different projects you would like to make part of your source tree,
+while the history of the two projects still stays completely
+independent and you cannot modify the contents of the submodule
+from within the main project.
+In case you want to merge the project histories, possibly make
+local modifications within the subtree, and considered the fact
+that all users will have to download and check out the subtree,
+you may choose to add a remote for the other project and use
+the 'subtree' merge strategy instead of setting up a submodule.
+
+Submodules are composed from a so-called `gitlink` tree entry
+in the main repository that refers to a particular commit object
+within the (completely separate) inner repository,
+and a record in the `.gitmodules` file at the root of the source
+tree, assigning a logical name to the submodule and describing
+the default URL the submodule shall be cloned from.
+The logical name can be used for overriding this URL within your
+local repository configuration (see 'submodule init').
+
+This command will manage the tree entries and contents of the
+gitmodules file for you, as well as inspect the status of your
+submodules and update 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 briefly inspect the up-to-date status of your submodules
+using the 'status' subcommand and get a detailed overview of the
+difference between the index and checkouts using the 'summary'
+subcommand.
 
 
 COMMANDS
@@ -78,10 +97,15 @@ status::
 	repository. This command is the default command for 'git-submodule'.
 
 init::
-	Initialize the submodules, i.e. register in .git/config each submodule
-	name and url found in .gitmodules. The key used in .git/config is
-	`submodule.$name.url`. This command does not alter existing information
-	in .git/config.
+	Initialize the submodules, i.e. register each submodule name
+	and url found in .gitmodules into .git/config.
+	The key used in .git/config is `submodule.$name.url`.
+	This command does not alter existing information in .git/config.
+	You can then customize the submodule clone URLs in .git/config
+	for your local setup and proceed to 'git submodule update';
+	you can also just use 'git submodule update --init' without
+	the explicit 'init' step if you do not intend to customize
+	any submodule locations.
 
 update::
 	Update the registered submodules, i.e. clone missing submodules and