user-manual changes

user-manual changes

[J. Bruce Fields]

I've got the submodule chapter plus another pending fix at:

  git://linux-nfs.org/~bfields/git.git maint

The submodule documentation looks fine to me.  My only suggestion is
that it should start with a brief explanation of why we have submodules
and what somebody would use them for.

--b.

J. Bruce Fields (1):
      user-manual: don't assume refs are stored under .git/refs

Miklos Vajna (1):
      User Manual: add a chapter for submodules

 Documentation/user-manual.txt |  220 +++++++++++++++++++++++++++++++++++++++--
 1 files changed, 213 insertions(+), 7 deletions(-)

Re: user-manual changes

[Michael Smith]

J. Bruce Fields wrote:

> The submodule documentation looks fine to me.  My only suggestion is
> that it should start with a brief explanation of why we have submodules
> and what somebody would use them for.

OK, I'll bite.

[PATCH] user-manual: Explain what submodules are good for.

[Michael Smith]

Rework the introduction to the Submodules section to explain why
someone would use them, and fix up submodule references from the
tree-object and todo sections.

Signed-off-by: Michael Smith <msmith@cbnco.com>
---
 Documentation/user-manual.txt |   25 ++++++++++++++-----------
 1 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index a085ca1..bd77e62 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2856,8 +2856,7 @@ between two related tree objects, since it can ignore any entries with
 identical object names.
 
 (Note: in the presence of submodules, trees may also have commits as
-entries.   See gitlink:git-submodule[1] and gitlink:gitmodules.txt[1]
-for partial documentation.)
+entries.  See <<submodules>> for documentation.)
 
 Note that the files all have mode 644 or 755: git actually only pays
 attention to the executable bit.
@@ -3163,12 +3162,18 @@ information as long as you have the name of the tree that it described.
 Submodules
 ==========
 
-This tutorial explains how to create and publish a repository with submodules
-using the gitlink:git-submodule[1] command.
+Some large projects are composed of smaller, self-contained parts.  For
+example, an embedded Linux distribution's source tree would include every
+piece of software in the distribution; a movie player might need to build
+against a specific, known-working version of a decompression library;
+several independent programs might all share the same build scripts.
 
-Submodules maintain their own identity; the submodule support just stores the
-submodule repository location and commit ID, so other developers who clone the
-superproject can easily clone all the submodules at the same revision.
+Git's submodule support allows a repository to contain, as a subdirectory, a
+checkout of an external project.  Submodules maintain their own identity;
+the submodule support just stores the submodule repository location and
+commit ID, so other developers who clone the superproject can easily clone
+all the submodules at the same revision.  The gitlink:git-submodule[1]
+command manages submodules.
 
 To see how submodule support works, create (for example) four example
 repositories that can be used later as a submodule:
@@ -3213,8 +3218,8 @@ The `git submodule add` command does a couple of things:
 
 - It clones the submodule under the current directory and by default checks out
   the master branch.
-- It adds the submodule's clone path to the `.gitmodules` file and adds this
-  file to the index, ready to be committed.
+- It adds the submodule's clone path to the gitlink:gitmodules[5] file and
+  adds this file to the index, ready to be committed.
 - It adds the submodule's current commit ID to the index, ready to be
   committed.
 
@@ -4277,5 +4282,3 @@ Write a chapter on using plumbing and writing scripts.
 Alternates, clone -reference, etc.
 
 git unpack-objects -r for recovery
-
-submodules
-- 
1.5.3

Re: [PATCH] user-manual: Explain what submodules are good for.

[J. Bruce Fields]

On Sun, Sep 23, 2007 at 11:14:09PM -0400, Michael Smith wrote:
> Rework the introduction to the Submodules section to explain why
> someone would use them, and fix up submodule references from the
> tree-object and todo sections.

Thanks!

> +Some large projects are composed of smaller, self-contained parts.  For
> +example, an embedded Linux distribution's source tree would include every
> +piece of software in the distribution; a movie player might need to build
> +against a specific, known-working version of a decompression library;
> +several independent programs might all share the same build scripts.
...
> +Git's submodule support allows a repository to contain, as a subdirectory, a
> +checkout of an external project.  Submodules maintain their own identity;
> +the submodule support just stores the submodule repository location and
> +commit ID, so other developers who clone the superproject can easily clone
> +all the submodules at the same revision.  The gitlink:git-submodule[1]
> +command manages submodules.

That looks helpful, thanks, but a little more detail might be nice.

Imagining myself as a reader trying to decide whether to use submodules
in a given case, I'm not sure this would tell me everything I need to
know.  For example, how does this compare to just importing a snapshot
of the library into your tree?  (Or possibly using the subtree merge
strategy?)

Some issues that pop to mind are scalability (when does a monolithic
tree get too large to work with?) and backwards compatibility (what
version does everybody working on your project need to have for it to
work?  What problems will you see if a few people are stuck with an
older git?)  I haven't followed submodule development, though, so may
have missed more important issues.

--b.

Re: [PATCH] user-manual: Explain what submodules are good for.

[Michael Smith]

On Mon, 24 Sep 2007, J. Bruce Fields wrote:

> That looks helpful, thanks, but a little more detail might be nice.

OK, let's find out if I'm awake enough to git-send-email.

Mike

[PATCH] user-manual: Explain what submodules are good for.

[Michael Smith]

Rework the introduction to the Submodules section to explain why
someone would use them, and fix up submodule references from the
tree-object and todo sections.

Signed-off-by: Michael Smith <msmith@cbnco.com>
---
 Documentation/user-manual.txt |   54 +++++++++++++++++++++++++++++++---------
 1 files changed, 42 insertions(+), 12 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index a085ca1..c7fdf25 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -2856,8 +2856,7 @@ between two related tree objects, since it can ignore any entries with
 identical object names.
 
 (Note: in the presence of submodules, trees may also have commits as
-entries.   See gitlink:git-submodule[1] and gitlink:gitmodules.txt[1]
-for partial documentation.)
+entries.  See <<submodules>> for documentation.)
 
 Note that the files all have mode 644 or 755: git actually only pays
 attention to the executable bit.
@@ -3163,12 +3162,45 @@ information as long as you have the name of the tree that it described.
 Submodules
 ==========
 
-This tutorial explains how to create and publish a repository with submodules
-using the gitlink:git-submodule[1] command.
-
-Submodules maintain their own identity; the submodule support just stores the
-submodule repository location and commit ID, so other developers who clone the
-superproject can easily clone all the submodules at the same revision.
+Large projects are often composed of smaller, self-contained modules.  For
+example, an embedded Linux distribution's source tree would include every
+piece of software in the distribution with some local modifications; a movie
+player might need to build against a specific, known-working version of a
+decompression library; several independent programs might all share the same
+build scripts.
+
+With centralized revision control systems this is often accomplished by
+including every module in one single repository.  Developers can check out
+all modules or only the modules they need to work with.  They can even modify
+files across several modules in a single commit while moving things around
+or updating APIs and translations.
+
+Git does not allow partial checkouts, so duplicating this approach in Git
+would force developers to keep a local copy of modules they are not
+interested in touching.  Commits in an enormous checkout would be slower
+than you'd expect as Git would have to scan every directory for changes.
+If modules have a lot of local history, clones would take forever.
+
+On the plus side, distributed revision control systems can much better
+integrate with external sources.  In a centralized model, a single arbitrary
+snapshot of the external project is exported from its own revision control
+and then imported into the local revision control on a vendor branch.  All
+the history is hidden.  With distributed revision control you can clone the
+entire external history and much more easily follow development and re-merge
+local changes.
+
+Git's submodule support allows a repository to contain, as a subdirectory, a
+checkout of an external project.  Submodules maintain their own identity;
+the submodule support just stores the submodule repository location and
+commit ID, so other developers who clone the containing project
+("superproject") can easily clone all the submodules at the same revision.
+Partial checkouts of the superproject are possible: you can tell Git to
+clone none, some or all of the submodules.
+
+The gitlink:git-submodule[1] command is available since Git 1.5.3.  Users
+with Git 1.5.2 can look up the submodule commits in the repository and
+manually check them out; earlier versions won't recognize the submodules at
+all.
 
 To see how submodule support works, create (for example) four example
 repositories that can be used later as a submodule:
@@ -3213,8 +3245,8 @@ The `git submodule add` command does a couple of things:
 
 - It clones the submodule under the current directory and by default checks out
   the master branch.
-- It adds the submodule's clone path to the `.gitmodules` file and adds this
-  file to the index, ready to be committed.
+- It adds the submodule's clone path to the gitlink:gitmodules[5] file and
+  adds this file to the index, ready to be committed.
 - It adds the submodule's current commit ID to the index, ready to be
   committed.
 
@@ -4277,5 +4309,3 @@ Write a chapter on using plumbing and writing scripts.
 Alternates, clone -reference, etc.
 
 git unpack-objects -r for recovery
-
-submodules
-- 
1.5.3

Re: [PATCH] user-manual: Explain what submodules are good for.

[J. Bruce Fields]

On Tue, Sep 25, 2007 at 08:44:38AM -0400, Michael Smith wrote:
> Rework the introduction to the Submodules section to explain why
> someone would use them, and fix up submodule references from the
> tree-object and todo sections.

Looks good to me; thanks!

Acked-by: J. Bruce Fields <bfields@citi.umich.edu>

--b.

> Signed-off-by: Michael Smith <msmith@cbnco.com>
> ---
>  Documentation/user-manual.txt |   54 +++++++++++++++++++++++++++++++---------
>  1 files changed, 42 insertions(+), 12 deletions(-)
> 
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index a085ca1..c7fdf25 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -2856,8 +2856,7 @@ between two related tree objects, since it can ignore any entries with
>  identical object names.
>  
>  (Note: in the presence of submodules, trees may also have commits as
> -entries.   See gitlink:git-submodule[1] and gitlink:gitmodules.txt[1]
> -for partial documentation.)
> +entries.  See <<submodules>> for documentation.)
>  
>  Note that the files all have mode 644 or 755: git actually only pays
>  attention to the executable bit.
> @@ -3163,12 +3162,45 @@ information as long as you have the name of the tree that it described.
>  Submodules
>  ==========
>  
> -This tutorial explains how to create and publish a repository with submodules
> -using the gitlink:git-submodule[1] command.
> -
> -Submodules maintain their own identity; the submodule support just stores the
> -submodule repository location and commit ID, so other developers who clone the
> -superproject can easily clone all the submodules at the same revision.
> +Large projects are often composed of smaller, self-contained modules.  For
> +example, an embedded Linux distribution's source tree would include every
> +piece of software in the distribution with some local modifications; a movie
> +player might need to build against a specific, known-working version of a
> +decompression library; several independent programs might all share the same
> +build scripts.
> +
> +With centralized revision control systems this is often accomplished by
> +including every module in one single repository.  Developers can check out
> +all modules or only the modules they need to work with.  They can even modify
> +files across several modules in a single commit while moving things around
> +or updating APIs and translations.
> +
> +Git does not allow partial checkouts, so duplicating this approach in Git
> +would force developers to keep a local copy of modules they are not
> +interested in touching.  Commits in an enormous checkout would be slower
> +than you'd expect as Git would have to scan every directory for changes.
> +If modules have a lot of local history, clones would take forever.
> +
> +On the plus side, distributed revision control systems can much better
> +integrate with external sources.  In a centralized model, a single arbitrary
> +snapshot of the external project is exported from its own revision control
> +and then imported into the local revision control on a vendor branch.  All
> +the history is hidden.  With distributed revision control you can clone the
> +entire external history and much more easily follow development and re-merge
> +local changes.
> +
> +Git's submodule support allows a repository to contain, as a subdirectory, a
> +checkout of an external project.  Submodules maintain their own identity;
> +the submodule support just stores the submodule repository location and
> +commit ID, so other developers who clone the containing project
> +("superproject") can easily clone all the submodules at the same revision.
> +Partial checkouts of the superproject are possible: you can tell Git to
> +clone none, some or all of the submodules.
> +
> +The gitlink:git-submodule[1] command is available since Git 1.5.3.  Users
> +with Git 1.5.2 can look up the submodule commits in the repository and
> +manually check them out; earlier versions won't recognize the submodules at
> +all.
>  
>  To see how submodule support works, create (for example) four example
>  repositories that can be used later as a submodule:
> @@ -3213,8 +3245,8 @@ The `git submodule add` command does a couple of things:
>  
>  - It clones the submodule under the current directory and by default checks out
>    the master branch.
> -- It adds the submodule's clone path to the `.gitmodules` file and adds this
> -  file to the index, ready to be committed.
> +- It adds the submodule's clone path to the gitlink:gitmodules[5] file and
> +  adds this file to the index, ready to be committed.
>  - It adds the submodule's current commit ID to the index, ready to be
>    committed.
>  
> @@ -4277,5 +4309,3 @@ Write a chapter on using plumbing and writing scripts.
>  Alternates, clone -reference, etc.
>  
>  git unpack-objects -r for recovery
> -
> -submodules
> -- 
> 1.5.3
>