[rfc] git submodules howto

[rfc] git submodules howto

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 1794 bytes --]

hi,

i saw several "is there any step by step howto on how to use git
submodules?" question on irc, and as far as i think there is none
available at the moment

here is how i use it at the moment:

$ mkdir lib
$ cd lib
$ git init
Initialized empty Git repository in .git/
$ echo "libmakefile" > Makefile
$ dg add Makefile
$ git commit -m "libmakefile"
Created initial commit 57c1dce: libmakefile
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 Makefile
$ cd ..
$ mkdir main
$ cd main
$ git init
Initialized empty Git repository in .git/
$ echo "main makefile" > Makefile
$ git add Makefile
$ git commit -m "main makefile"
Created initial commit 8935291: main makefile
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 Makefile
$ git submodule add ../lib lib
Initialized empty Git repository in /home/vmiklos/scm/git/sub/main/lib/.git/
0 blocks
$ git commit -m "added lib submodule"
Created commit 9dbfedf: added lib submodule
 2 files changed, 4 insertions(+), 0 deletions(-)
 create mode 100644 .gitmodules
 create mode 160000 lib
$ cd ..
$ git clone main cloned
Initialized empty Git repository in /home/vmiklos/scm/git/sub/cloned/.git/
0 blocks
$ cd cloned
$ git submodule init
Submodule 'lib' (/home/vmiklos/scm/git/sub/lib/.git) registered for path 'lib'
$ git submodule update
Initialized empty Git repository in /home/vmiklos/scm/git/sub/cloned/lib/.git/
0 blocks
Submodule path 'lib': checked out '57c1dce0e083e9ee50d06111d6aa1523116c2e15'
$ cat Makefile
main makefile
$ cat lib/Makefile
libmakefile

my questions:

1) is this correct? :) i use it and it seem to do what i except, but
maybe it's not correct

2) does this worth adding to the documentation? maybe to a .txt under
Documentation/howto? or to git-submodule.txt?

thanks,
- VMiklos

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [rfc] git submodules howto

[Johannes Schindelin]

Hi,

On Tue, 18 Sep 2007, Miklos Vajna wrote:

> i saw several "is there any step by step howto on how to use git 
> submodules?" question on irc, and as far as i think there is none 
> available at the moment

AFAICT there is one, on the git Wiki, since yesterday.

Ciao,
Dscho

Re: [rfc] git submodules howto

[Michael Smith]

On Tue, 18 Sep 2007, Miklos Vajna wrote:

> 1) is this correct? :) i use it and it seem to do what i except, but
> maybe it's not correct

Hi Miklos,

I had the same question, but you and I are both using it in a similar way 
so that's encouraging.

I put something in the Wiki the other day.

http://git.or.cz/gitwiki/GitSubmoduleTutorial

Mike

Re: [rfc] git submodules howto

[J. Bruce Fields]

On Tue, Sep 18, 2007 at 12:55:38PM +0200, Miklos Vajna wrote:
> 1) is this correct? :) i use it and it seem to do what i except, but
> maybe it's not correct

I'm not able to answer that question.

> 2) does this worth adding to the documentation? maybe to a .txt under
> Documentation/howto? or to git-submodule.txt?

Could you add it as a new chapter to user-manual.txt (probably just
after the "git concepts" chapter), and then add links to that chapter
from git-submodule(1) and gitmodules(5)?

--b.

Re: [rfc] git submodules howto

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 632 bytes --]

On Tue, Sep 18, 2007 at 09:29:40AM -0400, "J. Bruce Fields" <bfields@fieldses.org> wrote:
> > 2) does this worth adding to the documentation? maybe to a .txt under
> > Documentation/howto? or to git-submodule.txt?
> 
> Could you add it as a new chapter to user-manual.txt (probably just
> after the "git concepts" chapter), and then add links to that chapter
> from git-submodule(1) and gitmodules(5)?

hm, i did not know about the wiki page Michael created yesterday. so i
don't know what's the rule in case: if something is already in the wiki
then should or should not it be added to the 'official docs'?

- VMiklos

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [rfc] git submodules howto

[J. Bruce Fields]

On Tue, Sep 18, 2007 at 05:47:34PM +0200, Miklos Vajna wrote:
> On Tue, Sep 18, 2007 at 09:29:40AM -0400, "J. Bruce Fields" <bfields@fieldses.org> wrote:
> > > 2) does this worth adding to the documentation? maybe to a .txt under
> > > Documentation/howto? or to git-submodule.txt?
> > 
> > Could you add it as a new chapter to user-manual.txt (probably just
> > after the "git concepts" chapter), and then add links to that chapter
> > from git-submodule(1) and gitmodules(5)?
> 
> hm, i did not know about the wiki page Michael created yesterday. so i
> don't know what's the rule in case: if something is already in the wiki
> then should or should not it be added to the 'official docs'?

It should.  We also need submodules documentation for the "official"
documentation.

If you want to base that work off of that wiki page instead of your
original email, that's fine.  Just make sure you get Michael's
permission first.

--b.

Re: [rfc] git submodules howto

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 874 bytes --]

[ adding Michael to CC. ]

On Tue, Sep 18, 2007 at 11:55:29AM -0400, "J. Bruce Fields" <bfields@fieldses.org> wrote:
> > hm, i did not know about the wiki page Michael created yesterday. so i
> > don't know what's the rule in case: if something is already in the wiki
> > then should or should not it be added to the 'official docs'?
> 
> It should.  We also need submodules documentation for the "official"
> documentation.

okay.

> If you want to base that work off of that wiki page instead of your
> original email, that's fine.  Just make sure you get Michael's
> permission first.

Michael, i think the wiki version is better as my example does not
contain any extra to the wiki version. is it ok if i would send a patch
to include your work in the official docs?

i'm not sure how should i mention you, maybe in the commit message?

- VMiklos

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [rfc] git submodules howto

[Michael Smith]

On Tue, 18 Sep 2007, Miklos Vajna wrote:

> Michael, i think the wiki version is better as my example does not
> contain any extra to the wiki version. is it ok if i would send a patch
> to include your work in the official docs?

Thanks, that would be great.

> i'm not sure how should i mention you, maybe in the commit message?

Maybe signed-off-by is appropriate? Otherwise, don't worry about it.

Mike

[PATCH] User Manual: add a chapter for submodules

[Miklos Vajna]

Signed-off-by: Michael Smith <msmith@cbnco.com>
Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
---

On Tue, Sep 18, 2007 at 02:12:17PM -0400, Michael Smith <msmith@cbnco.com> wrote:
> On Tue, 18 Sep 2007, Miklos Vajna wrote:
>
> > Michael, i think the wiki version is better as my example does not
> > contain any extra to the wiki version. is it ok if i would send a patch
> > to include your work in the official docs?
>
> Thanks, that would be great.

here it is. this version is a bit shorter than the wiki one, but i think it
does not contain less useful info

 Documentation/user-manual.txt |  175 +++++++++++++++++++++++++++++++++++++++++
 1 files changed, 175 insertions(+), 0 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index ecb2bf9..ce0cf38 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3155,6 +3155,181 @@ a tree which you are in the process of working on.
 If you blow the index away entirely, you generally haven't lost any
 information as long as you have the name of the tree that it described.
 
+[[submodules]]
+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.
+
+To see how submodule support works, create (for example) four example
+repository that can be used later as a submodule:
+
+-------------------------------------------------
+$ mkdir ~/git
+$ cd ~/git
+$ for i in a b c d
+do
+	mkdir $i
+	cd $i
+	git init
+	echo "module $i" > $i.txt
+	git add $i.txt
+	git commit -m "Initial commit, submodule $mod"
+	cd ..
+done
+-------------------------------------------------
+
+Now create the superproject and add all the submodules:
+
+-------------------------------------------------
+$ mkdir super
+$ cd super
+$ git init
+$ echo hi > super.txt
+$ git add super.txt
+$ git commit -m "Initial commit of empty superproject"
+$ for i in a b c d
+do
+	git submodule add ~/git/$i
+done
+-------------------------------------------------
+
+See what files `git submodule` created:
+
+-------------------------------------------------
+$ ls -a
+.  ..  .git  .gitmodules  a  b  c  d  super.txt
+-------------------------------------------------
+
+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 current commit ID to the index, ready to be
+  committed.
+
+Commit the superproject:
+
+-------------------------------------------------
+$ git commit -m "Add submodules a, b, c, d."
+-------------------------------------------------
+
+Now clone the superproject:
+
+-------------------------------------------------
+$ cd ..
+$ git clone super cloned
+$ cd cloned
+-------------------------------------------------
+
+The submodule directories are there, but they're empty:
+
+-------------------------------------------------
+$ ls -a a
+.  ..
+$ git submodule status
+-d266b9873ad50488163457f025db7cdd9683d88b a
+-e81d457da15309b4fef4249aba9b50187999670d b
+-c1536a972b9affea0f16e0680ba87332dc059146 c
+-d96249ff5d57de5de093e6baff9e0aafa5276a74 d
+-------------------------------------------------
+
+Pulling down the submodules is a two-step process. First run `git submodule
+init` to add the submodule repository URLs to `.git/config`:
+
+-------------------------------------------------
+$ git submodule init
+-------------------------------------------------
+
+Now use `git submodule update` to clone the repositories and check out the
+commits specified in the superproject:
+
+-------------------------------------------------
+$ git submodule update
+$ cd a
+$ ls -a
+.  ..  .git  a.txt
+-------------------------------------------------
+
+One major difference between `git submodule update` and `git submodule add` is
+that `git submodule update` checks out a specific commit, rather than the tip
+of a branch. It's like checking out a tag: the head is detached, so you're not
+working on a branch.
+
+-------------------------------------------------
+$ git branch
+* (no branch)
+  master
+-------------------------------------------------
+
+If you want to make a change within a submodule, you should first check out a
+branch, make your changes, publish the change within the submodule, and then
+update the superproject to reference the new commit:
+
+-------------------------------------------------
+$ git branch
+* (no branch)
+  master
+$ git checkout master
+$ echo "adding a line again" >> a.txt
+$ git commit -a -m "Updated the submodule from within the superproject."
+$ git push
+$ cd ..
+$ git add a
+$ git commit -m "Updated submodule a."
+$ git push
+-------------------------------------------------
+
+NOTE: This means that you have to run `git submodule update` after `git pull`
+if you want to update the subprojects, too.
+
+Problems with submodules
+------------------------
+
+Always publish the submodule change before publishing the change to the
+superproject that references it. If you forget to publish the submodule change,
+others won't be able to clone the repository:
+
+-------------------------------------------------
+$ echo i added another line to this file >> a.txt
+$ git commit -a -m "doing it wrong this time"
+$ cd ..
+$ git add a
+$ git commit -m "Updated submodule a again."
+$ git push
+$ cd ~/git/cloned
+$ git pull
+$ git submodule update
+error: pathspec '261dfac35cb99d380eb966e102c1197139f7fa24' did not match any file(s) known to git.
+Did you forget to 'git add'?
+Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a'
+-------------------------------------------------
+
+It's not safe to run `git submodule update` if you've made changes within a
+submodule. They will be silently overwritten:
+
+-------------------------------------------------
+$ cat a.txt
+module a
+$ echo line added from private2 >> a.txt
+$ git commit -a -m "line added inside private2"
+$ cd ..
+$ git submodule update
+Submodule path 'a': checked out 'd266b9873ad50488163457f025db7cdd9683d88b'
+$ cd a
+$ cat a.txt
+module a
+-------------------------------------------------
+
+NOTE: The changes are still visible in the submodule's reflog.
+
 [[low-level-operations]]
 Low-level git operations
 ========================
-- 
1.5.3.1.1.g1e61-dirty

Re: [PATCH] User Manual: add a chapter for submodules

[Junio C Hamano]

Miklos Vajna <vmiklos@frugalware.org> writes:

> Signed-off-by: Michael Smith <msmith@cbnco.com>
> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>

Thanks.

> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index ecb2bf9..ce0cf38 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -3155,6 +3155,181 @@ a tree which you are in the process of working on.
>  If you blow the index away entirely, you generally haven't lost any
>  information as long as you have the name of the tree that it described.
>  
> +[[submodules]]
> +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.
> +
> +To see how submodule support works, create (for example) four example
> +repository that can be used later as a submodule:

s/repository/repositories/;

> +-------------------------------------------------
> +$ mkdir ~/git
> +$ cd ~/git
> +$ for i in a b c d
> +do
> +	mkdir $i
> +	cd $i
> +	git init
> +	echo "module $i" > $i.txt
> +	git add $i.txt
> +	git commit -m "Initial commit, submodule $mod"

s/\$mod/$i/;

> +	cd ..
> +done
> +-------------------------------------------------
> +
> +Now create the superproject and add all the submodules:
> +
> +-------------------------------------------------
> +$ mkdir super
> +$ cd super
> +$ git init
> +$ echo hi > super.txt
> +$ git add super.txt
> +$ git commit -m "Initial commit of empty superproject"

This is not *empty*; do you even need this step?

> +$ for i in a b c d
> +do
> +	git submodule add ~/git/$i
> +done
> +-------------------------------------------------
> +
> +See what files `git submodule` created:
> +
> +-------------------------------------------------
> +$ ls -a
> +.  ..  .git  .gitmodules  a  b  c  d  super.txt
> +-------------------------------------------------
> +
> +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 current commit ID to the index, ready to be
> +  committed.
> +
> +Commit the superproject:
> +
> +-------------------------------------------------
> +$ git commit -m "Add submodules a, b, c, d."
> +-------------------------------------------------

s/c, d./c and d./;

> +
> +Now clone the superproject:
> +
> +-------------------------------------------------
> +$ cd ..
> +$ git clone super cloned
> +$ cd cloned
> +-------------------------------------------------
> +
> +The submodule directories are there, but they're empty:
> +
> +-------------------------------------------------
> +$ ls -a a
> +.  ..
> +$ git submodule status
> +-d266b9873ad50488163457f025db7cdd9683d88b a
> +-e81d457da15309b4fef4249aba9b50187999670d b
> +-c1536a972b9affea0f16e0680ba87332dc059146 c
> +-d96249ff5d57de5de093e6baff9e0aafa5276a74 d
> +-------------------------------------------------

You might want to mention...

    Note: the commit object names shown above would be different for
    you, but they should match the HEAD commit object names of your
    repositories.  You can check it by doing:

    $ git ls-remote ../a

> +Pulling down the submodules is a two-step process. First run `git submodule
> +init` to add the submodule repository URLs to `.git/config`:
> +
> +-------------------------------------------------
> +$ git submodule init
> +-------------------------------------------------
> +
> +Now use `git submodule update` to clone the repositories and check out the
> +commits specified in the superproject:
> +
> +-------------------------------------------------
> +$ git submodule update
> +$ cd a
> +$ ls -a
> +.  ..  .git  a.txt
> +-------------------------------------------------
> +
> +One major difference between `git submodule update` and `git submodule add` is
> +that `git submodule update` checks out a specific commit, rather than the tip
> +of a branch. It's like checking out a tag: the head is detached, so you're not
> +working on a branch.
> +
> +-------------------------------------------------
> +$ git branch
> +* (no branch)
> +  master
> +-------------------------------------------------
> +
> +If you want to make a change within a submodule, you should first check out a
> +branch, make your changes, publish the change within the submodule, and then
> +update the superproject to reference the new commit:
> +
> +-------------------------------------------------
> +$ git branch
> +* (no branch)
> +  master
> +$ git checkout master

I am not so sure about this advice.  Don't you want to see how
the detached HEAD and 'master' (or any other branches) are
related before doing this?  You might even want to create a
"fix-up" branch that is rooted at the detached HEAD if the
change you are making is to fix minor details of the submodule
to suit what superproject wants (i.e. "little feature that is
applicable to the submodule as a standalone project, meant to
be pushed back to the submodule upstream").

> +$ echo "adding a line again" >> a.txt
> +$ git commit -a -m "Updated the submodule from within the superproject."
> +$ git push
> +$ cd ..
> +$ git add a

Before doing this "git add", it would be educational to have the
user do

    $ git diff

which would say that now the submodule is being updated.


> +$ git commit -m "Updated submodule a."
> +$ git push
> +-------------------------------------------------
> +
> +NOTE: This means that you have to run `git submodule update` after `git pull`
> +if you want to update the subprojects, too.

I do not quite understand this note.  I do understand the part
after "that you have to", but I do not know how the above
example relates to that --- iow, the above example does not
seem to "mean" such thing to me.

Also "submodule" is used consistently in the rest of the
document but this sentence talks about "subproject".

> +Problems with submodules
> +------------------------

The list is good, but are they Problems or pitfalls to watch out
for?

> +Always publish the submodule change before publishing the change to the
> +superproject that references it. If you forget to publish the submodule change,
> +others won't be able to clone the repository:

The same caution applies not to rewind branches in submodule
beyond commits that were ever recorded in any superproject.

> +-------------------------------------------------
> +$ echo i added another line to this file >> a.txt
> +$ git commit -a -m "doing it wrong this time"

It is not clear in which repository you are supposed to try this
command in the example sequence, as we crossed the section
boundary.  I am _guessing_ that the above two commands are to be
run inside ~/git/cloned-2/a after redoing ~/git/cloned-2 the
same way as you did ~/git/cloned, but you may want to make it
clear.

> +$ cd ..
> +$ git add a
> +$ git commit -m "Updated submodule a again."
> +$ git push
> +$ cd ~/git/cloned
> +$ git pull
> +$ git submodule update
> +error: pathspec '261dfac35cb99d380eb966e102c1197139f7fa24' did not match any file(s) known to git.
> +Did you forget to 'git add'?

I sense there is a bug in "git submodule update" here.  I do not
have time to look at what it's doing right now, but this is a
symptom of running:

    $ git checkout 261dfac35...

without checking if that is a valid commit object name, and git
checkout cannot decide if the request is about detaching the
head at commit 261dfac35 or checking the path 261dfac35 out of
the current index.  Porcelains should check with "cat-file -t"
first.

In addition we probably would want to teach "git checkout" about
the "--" separator, so that this can be disambiguated like this:

    $ git checkout 261dfac35 --

> +Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a'
> +-------------------------------------------------
> +
> +It's not safe to run `git submodule update` if you've made changes within a
> +submodule. They will be silently overwritten:

You want to distinguish two cases here.  Local uncommitted
changes, and committed changes.  The latter case is switched
away without too much noise, which is what you are demonstrating
here.  I _think_ local uncommitted changes will not be
overwritten at all, unless "submodule update" does "reset
--hard", which I suspect it doesn't.

> +-------------------------------------------------
> +$ cat a.txt
> +module a
> +$ echo line added from private2 >> a.txt
> +$ git commit -a -m "line added inside private2"
> +$ cd ..
> +$ git submodule update
> +Submodule path 'a': checked out 'd266b9873ad50488163457f025db7cdd9683d88b'
> +$ cd a
> +$ cat a.txt
> +module a
> +-------------------------------------------------
> +
> +NOTE: The changes are still visible in the submodule's reflog.
> +
>  [[low-level-operations]]
>  Low-level git operations
>  ========================
> -- 
> 1.5.3.1.1.g1e61-dirty

Re: [PATCH] User Manual: add a chapter for submodules

[J. Bruce Fields]

On Wed, Sep 19, 2007 at 12:44:18PM -0700, Junio C Hamano wrote:
> Also "submodule" is used consistently in the rest of the
> document but this sentence talks about "subproject".

I never liked the terms "submodule" or "subproject" much--it seems to
focus attention in the wrong place.  it's the "superproject" that's the
new and interesting thing here, while the submodules themselves are all
just standard git projects, right?

But I guess that's kind of a silly complaint, and late besides.

--b.

[PATCH] User Manual: add a chapter for submodules

[Miklos Vajna]

Signed-off-by: Michael Smith <msmith@cbnco.com>
Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
---

[ 2nd version ]

On Wed, Sep 19, 2007 at 12:44:18PM -0700, Junio C Hamano <gitster@pobox.com> wrote:
> > +To see how submodule support works, create (for example) four example
> > +repository that can be used later as a submodule:
> 
> s/repository/repositories/;

fixed.

> > +$ for i in a b c d
> > +do
> > +	mkdir $i
> > +	cd $i
> > +	git init
> > +	echo "module $i" > $i.txt
> > +	git add $i.txt
> > +	git commit -m "Initial commit, submodule $mod"
> 
> s/\$mod/$i/;

fixed

> > +$ echo hi > super.txt
> > +$ git add super.txt
> > +$ git commit -m "Initial commit of empty superproject"
> 
> This is not *empty*; do you even need this step?

in fact, no :) removed.

> > +-------------------------------------------------
> > +$ git commit -m "Add submodules a, b, c, d."
> > +-------------------------------------------------
> 
> s/c, d./c and d./;

fixed.

> > +$ ls -a a
> > +.  ..
> > +$ git submodule status
> > +-d266b9873ad50488163457f025db7cdd9683d88b a
> > +-e81d457da15309b4fef4249aba9b50187999670d b
> > +-c1536a972b9affea0f16e0680ba87332dc059146 c
> > +-d96249ff5d57de5de093e6baff9e0aafa5276a74 d
> > +-------------------------------------------------
> 
> You might want to mention...
> 
>     Note: the commit object names shown above would be different for
>     you, but they should match the HEAD commit object names of your
>     repositories.  You can check it by doing:
> 
>     $ git ls-remote ../a

i've added such a note.

> > +If you want to make a change within a submodule, you should first check out a
> > +branch, make your changes, publish the change within the submodule, and then
> > +update the superproject to reference the new commit:
> > +
> > +-------------------------------------------------
> > +$ git branch
> > +* (no branch)
> > +  master
> > +$ git checkout master
> 
> I am not so sure about this advice.  Don't you want to see how
> the detached HEAD and 'master' (or any other branches) are
> related before doing this?  You might even want to create a
> "fix-up" branch that is rooted at the detached HEAD if the
> change you are making is to fix minor details of the submodule
> to suit what superproject wants (i.e. "little feature that is
> applicable to the submodule as a standalone project, meant to
> be pushed back to the submodule upstream").

right, changed it to two examples, one about "git checkout master", and
the other about "git checkout -b fix-up"

> > +$ git push
> > +$ cd ..
> > +$ git add a
> 
> Before doing this "git add", it would be educational to have the
> user do
> 
>     $ git diff
> 
> which would say that now the submodule is being updated.

added.

> > +$ git commit -m "Updated submodule a."
> > +$ git push
> > +-------------------------------------------------
> > +
> > +NOTE: This means that you have to run `git submodule update` after `git pull`
> > +if you want to update the subprojects, too.
> 
> I do not quite understand this note.  I do understand the part
> after "that you have to", but I do not know how the above
> example relates to that --- iow, the above example does not
> seem to "mean" such thing to me.
> 
> Also "submodule" is used consistently in the rest of the
> document but this sentence talks about "subproject".

yes, it was illogical to use a 'note' here as it's not related. i've
just added a separte sentence about this without the 'this means'.

> > +Problems with submodules
> > +------------------------
> 
> The list is good, but are they Problems or pitfalls to watch out
> for?

the later :) title changed.

> > +Always publish the submodule change before publishing the change to the
> > +superproject that references it. If you forget to publish the submodule change,
> > +others won't be able to clone the repository:
> 
> The same caution applies not to rewind branches in submodule
> beyond commits that were ever recorded in any superproject.

i've added a paragraph about this issue.

> > +-------------------------------------------------
> > +$ echo i added another line to this file >> a.txt
> > +$ git commit -a -m "doing it wrong this time"
> 
> It is not clear in which repository you are supposed to try this
> command in the example sequence, as we crossed the section
> boundary.  I am _guessing_ that the above two commands are to be
> run inside ~/git/cloned-2/a after redoing ~/git/cloned-2 the
> same way as you did ~/git/cloned, but you may want to make it
> clear.

right, i forgot the 'cd ~/git/super/a'. provided the repos are
symmetric, i think it would just make the situation unnecessary
complicated to clone a third repo.

> > +$ git submodule update
> > +error: pathspec '261dfac35cb99d380eb966e102c1197139f7fa24' did not match any file(s) known to git.
> > +Did you forget to 'git add'?
> 
> I sense there is a bug in "git submodule update" here.  I do not
> have time to look at what it's doing right now, but this is a
> symptom of running:
> 
>     $ git checkout 261dfac35...
> 
> without checking if that is a valid commit object name, and git
> checkout cannot decide if the request is about detaching the
> head at commit 261dfac35 or checking the path 261dfac35 out of
> the current index.  Porcelains should check with "cat-file -t"
> first.

hm yes. i think as long as this behaviour is not changed, it would not
be good to remove the "Did you forget to 'git add'?" part from the
example

> > +Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a'
> > +-------------------------------------------------
> > +
> > +It's not safe to run `git submodule update` if you've made changes within a
> > +submodule. They will be silently overwritten:
> 
> You want to distinguish two cases here.  Local uncommitted
> changes, and committed changes.  The latter case is switched
> away without too much noise, which is what you are demonstrating
> here.  I _think_ local uncommitted changes will not be
> overwritten at all, unless "submodule update" does "reset
> --hard", which I suspect it doesn't.

i've just checked that it does a git checkout, so uncommitted changes
are preserved. i've updated this part to mention this fact.

i've also added the suggestions by skimo.

VMiklos

 Documentation/user-manual.txt |  175 +++++++++++++++++++++++++++++++++++++++++
 1 files changed, 175 insertions(+), 0 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index ecb2bf9..ce0cf38 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3155,6 +3155,181 @@ a tree which you are in the process of working on.
 If you blow the index away entirely, you generally haven't lost any
 information as long as you have the name of the tree that it described.
 
+[[submodules]]
+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.
+
+To see how submodule support works, create (for example) four example
+repository that can be used later as a submodule:
+
+-------------------------------------------------
+$ mkdir ~/git
+$ cd ~/git
+$ for i in a b c d
+do
+	mkdir $i
+	cd $i
+	git init
+	echo "module $i" > $i.txt
+	git add $i.txt
+	git commit -m "Initial commit, submodule $mod"
+	cd ..
+done
+-------------------------------------------------
+
+Now create the superproject and add all the submodules:
+
+-------------------------------------------------
+$ mkdir super
+$ cd super
+$ git init
+$ echo hi > super.txt
+$ git add super.txt
+$ git commit -m "Initial commit of empty superproject"
+$ for i in a b c d
+do
+	git submodule add ~/git/$i
+done
+-------------------------------------------------
+
+See what files `git submodule` created:
+
+-------------------------------------------------
+$ ls -a
+.  ..  .git  .gitmodules  a  b  c  d  super.txt
+-------------------------------------------------
+
+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 current commit ID to the index, ready to be
+  committed.
+
+Commit the superproject:
+
+-------------------------------------------------
+$ git commit -m "Add submodules a, b, c, d."
+-------------------------------------------------
+
+Now clone the superproject:
+
+-------------------------------------------------
+$ cd ..
+$ git clone super cloned
+$ cd cloned
+-------------------------------------------------
+
+The submodule directories are there, but they're empty:
+
+-------------------------------------------------
+$ ls -a a
+.  ..
+$ git submodule status
+-d266b9873ad50488163457f025db7cdd9683d88b a
+-e81d457da15309b4fef4249aba9b50187999670d b
+-c1536a972b9affea0f16e0680ba87332dc059146 c
+-d96249ff5d57de5de093e6baff9e0aafa5276a74 d
+-------------------------------------------------
+
+Pulling down the submodules is a two-step process. First run `git submodule
+init` to add the submodule repository URLs to `.git/config`:
+
+-------------------------------------------------
+$ git submodule init
+-------------------------------------------------
+
+Now use `git submodule update` to clone the repositories and check out the
+commits specified in the superproject:
+
+-------------------------------------------------
+$ git submodule update
+$ cd a
+$ ls -a
+.  ..  .git  a.txt
+-------------------------------------------------
+
+One major difference between `git submodule update` and `git submodule add` is
+that `git submodule update` checks out a specific commit, rather than the tip
+of a branch. It's like checking out a tag: the head is detached, so you're not
+working on a branch.
+
+-------------------------------------------------
+$ git branch
+* (no branch)
+  master
+-------------------------------------------------
+
+If you want to make a change within a submodule, you should first check out a
+branch, make your changes, publish the change within the submodule, and then
+update the superproject to reference the new commit:
+
+-------------------------------------------------
+$ git branch
+* (no branch)
+  master
+$ git checkout master
+$ echo "adding a line again" >> a.txt
+$ git commit -a -m "Updated the submodule from within the superproject."
+$ git push
+$ cd ..
+$ git add a
+$ git commit -m "Updated submodule a."
+$ git push
+-------------------------------------------------
+
+NOTE: This means that you have to run `git submodule update` after `git pull`
+if you want to update the subprojects, too.
+
+Problems with submodules
+------------------------
+
+Always publish the submodule change before publishing the change to the
+superproject that references it. If you forget to publish the submodule change,
+others won't be able to clone the repository:
+
+-------------------------------------------------
+$ echo i added another line to this file >> a.txt
+$ git commit -a -m "doing it wrong this time"
+$ cd ..
+$ git add a
+$ git commit -m "Updated submodule a again."
+$ git push
+$ cd ~/git/cloned
+$ git pull
+$ git submodule update
+error: pathspec '261dfac35cb99d380eb966e102c1197139f7fa24' did not match any file(s) known to git.
+Did you forget to 'git add'?
+Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a'
+-------------------------------------------------
+
+It's not safe to run `git submodule update` if you've made changes within a
+submodule. They will be silently overwritten:
+
+-------------------------------------------------
+$ cat a.txt
+module a
+$ echo line added from private2 >> a.txt
+$ git commit -a -m "line added inside private2"
+$ cd ..
+$ git submodule update
+Submodule path 'a': checked out 'd266b9873ad50488163457f025db7cdd9683d88b'
+$ cd a
+$ cat a.txt
+module a
+-------------------------------------------------
+
+NOTE: The changes are still visible in the submodule's reflog.
+
 [[low-level-operations]]
 Low-level git operations
 ========================
-- 
1.5.3.1.1.g1e61-dirty

[PATCH] User Manual: add a chapter for submodules

[Miklos Vajna]

Signed-off-by: Michael Smith <msmith@cbnco.com>
Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
---

Sorry, I sent the original patch again. So here is the updated second version.

 Documentation/user-manual.txt |  202 +++++++++++++++++++++++++++++++++++++++++
 1 files changed, 202 insertions(+), 0 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index ecb2bf9..aee654c 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3155,6 +3155,208 @@ a tree which you are in the process of working on.
 If you blow the index away entirely, you generally haven't lost any
 information as long as you have the name of the tree that it described.
 
+[[submodules]]
+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.
+
+To see how submodule support works, create (for example) four example
+repositories that can be used later as a submodule:
+
+-------------------------------------------------
+$ mkdir ~/git
+$ cd ~/git
+$ for i in a b c d
+do
+	mkdir $i
+	cd $i
+	git init
+	echo "module $i" > $i.txt
+	git add $i.txt
+	git commit -m "Initial commit, submodule $i"
+	cd ..
+done
+-------------------------------------------------
+
+Now create the superproject and add all the submodules:
+
+-------------------------------------------------
+$ mkdir super
+$ cd super
+$ git init
+$ for i in a b c d
+do
+	git submodule add ~/git/$i
+done
+-------------------------------------------------
+
+NOTE: Do not use local URLs here if you plan to publish your superproject!
+
+See what files `git submodule` created:
+
+-------------------------------------------------
+$ ls -a
+.  ..  .git  .gitmodules  a  b  c  d
+-------------------------------------------------
+
+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 current commit ID to the index, ready to be
+  committed.
+
+Commit the superproject:
+
+-------------------------------------------------
+$ git commit -m "Add submodules a, b, c and d."
+-------------------------------------------------
+
+Now clone the superproject:
+
+-------------------------------------------------
+$ cd ..
+$ git clone super cloned
+$ cd cloned
+-------------------------------------------------
+
+The submodule directories are there, but they're empty:
+
+-------------------------------------------------
+$ ls -a a
+.  ..
+$ git submodule status
+-d266b9873ad50488163457f025db7cdd9683d88b a
+-e81d457da15309b4fef4249aba9b50187999670d b
+-c1536a972b9affea0f16e0680ba87332dc059146 c
+-d96249ff5d57de5de093e6baff9e0aafa5276a74 d
+-------------------------------------------------
+
+NOTE: The commit object names shown above would be different for you, but they
+should match the HEAD commit object names of your repositories.  You can check
+it by running `git ls-remote ../a`.
+
+Pulling down the submodules is a two-step process. First run `git submodule
+init` to add the submodule repository URLs to `.git/config`:
+
+-------------------------------------------------
+$ git submodule init
+-------------------------------------------------
+
+Now use `git submodule update` to clone the repositories and check out the
+commits specified in the superproject:
+
+-------------------------------------------------
+$ git submodule update
+$ cd a
+$ ls -a
+.  ..  .git  a.txt
+-------------------------------------------------
+
+One major difference between `git submodule update` and `git submodule add` is
+that `git submodule update` checks out a specific commit, rather than the tip
+of a branch. It's like checking out a tag: the head is detached, so you're not
+working on a branch.
+
+-------------------------------------------------
+$ git branch
+* (no branch)
+  master
+-------------------------------------------------
+
+If you want to make a change within a submodule and you have a detached head,
+then you should create or checkout a branch, make your changes, publish the
+change within the submodule, and then update the superproject to reference the
+new commit:
+
+-------------------------------------------------
+$ git checkout master
+-------------------------------------------------
+
+or
+
+-------------------------------------------------
+$ git checkout -b fix-up
+-------------------------------------------------
+
+then
+
+-------------------------------------------------
+$ echo "adding a line again" >> a.txt
+$ git commit -a -m "Updated the submodule from within the superproject."
+$ git push
+$ cd ..
+$ git diff
+diff --git a/a b/a
+index d266b98..261dfac 160000
+--- a/a
++++ b/a
+@@ -1 +1 @@
+-Subproject commit d266b9873ad50488163457f025db7cdd9683d88b
++Subproject commit 261dfac35cb99d380eb966e102c1197139f7fa24
+$ git add a
+$ git commit -m "Updated submodule a."
+$ git push
+-------------------------------------------------
+
+You have to run `git submodule update` after `git pull` if you want to update
+submodules, too.
+
+Pitfalls with submodules
+------------------------
+
+Always publish the submodule change before publishing the change to the
+superproject that references it. If you forget to publish the submodule change,
+others won't be able to clone the repository:
+
+-------------------------------------------------
+$ cd ~/git/super/a
+$ echo i added another line to this file >> a.txt
+$ git commit -a -m "doing it wrong this time"
+$ cd ..
+$ git add a
+$ git commit -m "Updated submodule a again."
+$ git push
+$ cd ~/git/cloned
+$ git pull
+$ git submodule update
+error: pathspec '261dfac35cb99d380eb966e102c1197139f7fa24' did not match any file(s) known to git.
+Did you forget to 'git add'?
+Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a'
+-------------------------------------------------
+
+You also should not rewind branches in a submodule beyond commits that were
+ever recorded in any superproject.
+
+It's not safe to run `git submodule update` if you've made and committed
+changes within a submodule without checking out a branch first. They will be
+silently overwritten:
+
+-------------------------------------------------
+$ cat a.txt
+module a
+$ echo line added from private2 >> a.txt
+$ git commit -a -m "line added inside private2"
+$ cd ..
+$ git submodule update
+Submodule path 'a': checked out 'd266b9873ad50488163457f025db7cdd9683d88b'
+$ cd a
+$ cat a.txt
+module a
+-------------------------------------------------
+
+NOTE: The changes are still visible in the submodule's reflog.
+
+This is not the case if you did not commit your changes.
+
 [[low-level-operations]]
 Low-level git operations
 ========================
-- 
1.5.3.1.1.g1e61-dirty

Re: [PATCH] User Manual: add a chapter for submodules

[Junio C Hamano]

Miklos Vajna <vmiklos@frugalware.org> writes:

> Signed-off-by: Michael Smith <msmith@cbnco.com>
> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
> ---
>
> Sorry, I sent the original patch again. So here is the updated second version.

Looks Ok to me, although I didn't verify the examples by
actually running them myself this time (last round I did).

Re: [PATCH] User Manual: add a chapter for submodules

[Johannes Schindelin]

Hi,

On Wed, 19 Sep 2007, Junio C Hamano wrote:

> Miklos Vajna <vmiklos@frugalware.org> writes:
> 
> > Signed-off-by: Michael Smith <msmith@cbnco.com>
> > Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
> > ---
> >
> > Sorry, I sent the original patch again. So here is the updated second version.
> 
> Looks Ok to me, although I didn't verify the examples by
> actually running them myself this time (last round I did).

So maybe we should do the same as with the tutorial: stick the examples 
into a test script?

Ciao,
Dscho

[PATCH] new test from the submodule chapter of the user manual

[Miklos Vajna]

Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
---

On Thu, Sep 20, 2007 at 11:34:25AM +0100, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
> On Wed, 19 Sep 2007, Junio C Hamano wrote:
> > Looks Ok to me, although I didn't verify the examples by
> > actually running them myself this time (last round I did).
>
> So maybe we should do the same as with the tutorial: stick the examples
> into a test script?

what about this?

 t/t3060-subprojects-tutorial.sh |   62 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 62 insertions(+), 0 deletions(-)
 create mode 100755 t/t3060-subprojects-tutorial.sh

diff --git a/t/t3060-subprojects-tutorial.sh b/t/t3060-subprojects-tutorial.sh
new file mode 100755
index 0000000..2fcf4ab
--- /dev/null
+++ b/t/t3060-subprojects-tutorial.sh
@@ -0,0 +1,62 @@
+#!/bin/sh
+#
+# Copyright (c) 2007 Miklos Vajna
+#
+
+test_description='A simple subprojects tutorial in the form of a test case'
+
+. ./test-lib.sh
+
+test_expect_success "create the submodules" '
+	for i in a b c d
+	do
+		mkdir $i &&
+		cd $i &&
+		git init &&
+		echo "module $i" > $i.txt &&
+		git add $i.txt &&
+		git commit -m "Initial commit, submodule $i" &&
+		cd ..
+	done
+'
+
+test_expect_success "create the superproject" '
+	mkdir super &&
+	cd super &&
+	git init &&
+	for i in a b c d
+	do
+		git submodule add '`pwd`'/$i
+	done
+'
+
+test_expect_success "commit in the superproject" '
+	git commit -m "Add submodules a, b, c and d." &&
+	cd ..
+'
+
+test_expect_success "clone the superproject" '
+	git clone super cloned &&
+	cd cloned
+'
+
+test_expect_success "submodule init" '
+	git submodule init
+'
+
+test_expect_success "submodule update" '
+	git submodule update
+'
+
+test_expect_success "update the submodule from within the superproject" '
+	cd a &&
+	echo "adding a line again" >> a.txt &&
+	git commit -a -m "Updated the submodule from within the superproject." &&
+	git push &&
+	cd .. &&
+	git add a &&
+	git commit -m "Updated submodule a." &&
+	git push
+'
+
+test_done
-- 
1.5.3.2.80.g077d6f-dirty

Re: [PATCH] new test from the submodule chapter of the user manual

[Joel Becker]

On Thu, Sep 20, 2007 at 07:08:31PM +0200, Miklos Vajna wrote:
> +test_expect_success "create the submodules" '
> +	for i in a b c d
> +	do
> +		mkdir $i &&
> +		cd $i &&
> +		git init &&
> +		echo "module $i" > $i.txt &&
> +		git add $i.txt &&
> +		git commit -m "Initial commit, submodule $i" &&
> +		cd ..
> +	done

	Silly question: why use the '&&' when you can 'set -e'?  As it
currently stands, a failure will still go back around the loop...

Joel

-- 

"Sometimes when reading Goethe I have the paralyzing suspicion
 that he is trying to be funny."
         - Guy Davenport

Joel Becker
Principal Software Developer
Oracle
E-mail: joel.becker@oracle.com
Phone: (650) 506-8127

Re: [PATCH] new test from the submodule chapter of the user manual

[Johannes Schindelin]

Hi,

On Thu, 20 Sep 2007, Joel Becker wrote:

> On Thu, Sep 20, 2007 at 07:08:31PM +0200, Miklos Vajna wrote:
> > +test_expect_success "create the submodules" '
> > +	for i in a b c d
> > +	do
> > +		mkdir $i &&
> > +		cd $i &&
> > +		git init &&
> > +		echo "module $i" > $i.txt &&
> > +		git add $i.txt &&
> > +		git commit -m "Initial commit, submodule $i" &&
> > +		cd ..
> > +	done
> 
> 	Silly question: why use the '&&' when you can 'set -e'?  As it
> currently stands, a failure will still go back around the loop...

A "set -e" will make the script exit AFAIR.  That's not what we want.  A 
simple "|| break" after the "cd .." will work, though.

Ciao,
Dscho

Re: [PATCH] new test from the submodule chapter of the user manual

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 1475 bytes --]

On Thu, Sep 20, 2007 at 07:47:32PM +0100, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
> > > +test_expect_success "create the submodules" '
> > > +	for i in a b c d
> > > +	do
> > > +		mkdir $i &&
> > > +		cd $i &&
> > > +		git init &&
> > > +		echo "module $i" > $i.txt &&
> > > +		git add $i.txt &&
> > > +		git commit -m "Initial commit, submodule $i" &&
> > > +		cd ..
> > > +	done
> > 
> > 	Silly question: why use the '&&' when you can 'set -e'?  As it
> > currently stands, a failure will still go back around the loop...
> 
> A "set -e" will make the script exit AFAIR.  That's not what we want.  A 
> simple "|| break" after the "cd .." will work, though.

i know i asked this on irc, but i still a bit confused. the target would
be to jump out from the loop and return 'false' if any of the items
fails

if i understand correctly then this is what Dscho proposes:

$ for i in a b; do echo $i && false || break; done
a
$ echo $?
0

this jumps out from the loop but does not return false

here is my version:

$ for i in a b; do echo $i && false; done
a
b

$ echo $?
1

this one detects the error but does not jump out from the loop. none of
them is perfect, but at least my version fails as long as the last cycle
fails (which is not problem as i think in most cases all or none of the
cycles will fail)

anyway, if you really want, i can change it, but i think it is not the
right thing to do

- VMiklos

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [PATCH] new test from the submodule chapter of the user manual

[Joel Becker]

On Thu, Sep 20, 2007 at 07:47:32PM +0100, Johannes Schindelin wrote:
> > 	Silly question: why use the '&&' when you can 'set -e'?  As it
> > currently stands, a failure will still go back around the loop...
> 
> A "set -e" will make the script exit AFAIR.  That's not what we want.  A 
> simple "|| break" after the "cd .." will work, though.

	Oh, drat.  It's run in eval, not a subshell.

Joel

-- 

Life's Little Instruction Book #94

	"Make it a habit to do nice things for people who 
	 will never find out."

Joel Becker
Principal Software Developer
Oracle
E-mail: joel.becker@oracle.com
Phone: (650) 506-8127

Re: [PATCH] new test from the submodule chapter of the user manual

[Junio C Hamano]

Miklos Vajna <vmiklos@frugalware.org> writes:

> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
> ---
>
> On Thu, Sep 20, 2007 at 11:34:25AM +0100, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
>> On Wed, 19 Sep 2007, Junio C Hamano wrote:
>> > Looks Ok to me, although I didn't verify the examples by
>> > actually running them myself this time (last round I did).
>>
>> So maybe we should do the same as with the tutorial: stick the examples
>> into a test script?
>
> what about this?

Far too inadequate.  You test if "commit" reports success, but
do not check if what is committed is what you wanted to commit,
for example.

[PATCH] new test from the submodule chapter of the user manual

[Miklos Vajna]

Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
---

second version, now checking for all output, the commit hashes shows what is
committed is what we wanted to commit.

 t/t3060-subprojects-tutorial.sh |  151 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 151 insertions(+), 0 deletions(-)
 create mode 100755 t/t3060-subprojects-tutorial.sh

diff --git a/t/t3060-subprojects-tutorial.sh b/t/t3060-subprojects-tutorial.sh
new file mode 100755
index 0000000..fc09451
--- /dev/null
+++ b/t/t3060-subprojects-tutorial.sh
@@ -0,0 +1,151 @@
+#!/bin/sh
+#
+# Copyright (c) 2007 Miklos Vajna
+#
+
+test_description='A simple subprojects tutorial in the form of a test case'
+
+. ./test-lib.sh
+
+test_tick
+
+cat > create.expect << EOF
+Initialized empty Git repository in .git/
+Created initial commit 85349d2: Initial commit, submodule a
+ 1 files changed, 1 insertions(+), 0 deletions(-)
+ create mode 100644 a.txt
+Initialized empty Git repository in .git/
+Created initial commit 47398d6: Initial commit, submodule b
+ 1 files changed, 1 insertions(+), 0 deletions(-)
+ create mode 100644 b.txt
+Initialized empty Git repository in .git/
+Created initial commit 3d88526: Initial commit, submodule c
+ 1 files changed, 1 insertions(+), 0 deletions(-)
+ create mode 100644 c.txt
+Initialized empty Git repository in .git/
+Created initial commit 73af3de: Initial commit, submodule d
+ 1 files changed, 1 insertions(+), 0 deletions(-)
+ create mode 100644 d.txt
+EOF
+
+for i in a b c d
+do
+	mkdir $i &&
+	cd $i &&
+	git init &&
+	echo "module $i" > $i.txt &&
+	git add $i.txt &&
+	git commit -m "Initial commit, submodule $i" &&
+	cd ..
+done > create.output
+test_expect_success "create the submodules" 'cmp create.expect create.output'
+
+mkdir super
+cd super
+cat > create-super.expect << EOF
+Initialized empty Git repository in .git/
+Initialized empty Git repository in `pwd`/a/.git/
+0 blocks
+Initialized empty Git repository in `pwd`/b/.git/
+0 blocks
+Initialized empty Git repository in `pwd`/c/.git/
+0 blocks
+Initialized empty Git repository in `pwd`/d/.git/
+0 blocks
+EOF
+
+(git init &&
+for i in a b c d
+do
+	git submodule add `pwd`/../$i
+done ) &> create-super.output
+test_expect_success "create the superproject" 'cmp create-super.expect create-super.output'
+
+cat > commit-superproject.expect << EOF
+Created initial commit c496be9: Add submodules a, b, c and d.
+ 5 files changed, 16 insertions(+), 0 deletions(-)
+ create mode 100644 .gitmodules
+ create mode 160000 a
+ create mode 160000 b
+ create mode 160000 c
+ create mode 160000 d
+EOF
+git commit -m "Add submodules a, b, c and d." > commit-superproject.output
+
+test_expect_success "commit in the superproject" 'cmp commit-superproject.expect commit-superproject.output'
+
+cd ..
+
+cat > clone.expect << EOF
+Initialized empty Git repository in `pwd`/cloned/.git/
+0 blocks
+EOF
+
+git clone super cloned &> clone.output
+
+test_expect_success "clone the superproject" 'cmp clone.expect clone.output'
+
+cd cloned
+
+cat > submodule-init.expect << EOF
+Submodule 'a' (${PWD%%/cloned}/a/.git) registered for path 'a'
+Submodule 'b' (${PWD%%/cloned}/b/.git) registered for path 'b'
+Submodule 'c' (${PWD%%/cloned}/c/.git) registered for path 'c'
+Submodule 'd' (${PWD%%/cloned}/d/.git) registered for path 'd'
+EOF
+
+git submodule init > submodule-init.output
+
+test_expect_success "submodule init" 'cmp submodule-init.expect submodule-init.output'
+
+cat > submodule-update.expect << EOF
+Initialized empty Git repository in `pwd`/a/.git/
+0 blocks
+Submodule path 'a': checked out '85349d24595f581f5548b321a55c8a5fbe87259f'
+Initialized empty Git repository in `pwd`/b/.git/
+0 blocks
+Submodule path 'b': checked out '47398d6286153d23bfd5780ae3bf1996eb18cf90'
+Initialized empty Git repository in `pwd`/c/.git/
+0 blocks
+Submodule path 'c': checked out '3d88526ff6973dd27a07f57a3bb2bf5fa0bada42'
+Initialized empty Git repository in `pwd`/d/.git/
+0 blocks
+Submodule path 'd': checked out '73af3de6718291404ef541f4bb152f87d35a1481'
+EOF
+
+git submodule update &> submodule-update.output
+
+test_expect_success "submodule update" 'cmp submodule-update.expect submodule-update.output'
+
+cat > submodule-push.expect << EOF
+Created commit ab78b5a: Updated the submodule from within the superproject.
+ 1 files changed, 1 insertions(+), 0 deletions(-)
+Everything up-to-date
+Created commit 8bbfffe: Updated submodule a.
+ 1 files changed, 1 insertions(+), 1 deletions(-)
+updating 'refs/heads/master'
+  from c496be9e726d5c6ee0f96668b1b5822cf6cad027
+  to   8bbfffe1651b896e371bf7a3506452d545cf81b3
+ Also local refs/remotes/origin/master
+Generating pack...
+Done counting 2 objects.
+Deltifying 2 objects...
+  50% (1/2) done
 100% (2/2) done

+Writing 2 objects...
+  50% (1/2) done
 100% (2/2) done

+Total 2 (delta 0), reused 0 (delta 0)
+refs/heads/master: c496be9e726d5c6ee0f96668b1b5822cf6cad027 -> 8bbfffe1651b896e371bf7a3506452d545cf81b3
+EOF
+
+( cd a &&
+echo "adding a line again" >> a.txt &&
+git commit -a -m "Updated the submodule from within the superproject." &&
+git push &&
+cd .. &&
+git add a &&
+git commit -m "Updated submodule a." &&
+git push) &> submodule-push.output
+
+test_expect_success "update the submodule from within the superproject" 'cmp submodule-push.expect submodule-push.output'
+
+test_done
-- 
1.5.3.2.80.g077d6f-dirty

Re: [PATCH] new test from the submodule chapter of the user manual

[Junio C Hamano]

That's horrible.  Please do not depend on object SHA1's to stay
the same.  If somebody makes a fix to the test to add a new file
in a sample subproject it would break all the rest.  Also please
do not depend on the progress output.

In short, please do not try to get away with quick-and-dirty.

[PATCH] new test from the submodule chapter of the user manual

[Miklos Vajna]

Signed-off-by: Miklos Vajna <vmiklos@frugalware.org>
---

On Fri, Sep 21, 2007 at 11:04:05AM -0700, Junio C Hamano <gitster@pobox.com> wrote:
> That's horrible.  Please do not depend on object SHA1's to stay
> the same.  If somebody makes a fix to the test to add a new file
> in a sample subproject it would break all the rest.  Also please
> do not depend on the progress output.

okay, here is the third try. now checking for the result using diff-tree and
ls-files. hopefully i did what you expected :)

 t/t3060-subprojects-tutorial.sh |   95 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 95 insertions(+), 0 deletions(-)
 create mode 100755 t/t3060-subprojects-tutorial.sh

diff --git a/t/t3060-subprojects-tutorial.sh b/t/t3060-subprojects-tutorial.sh
new file mode 100755
index 0000000..d46dded
--- /dev/null
+++ b/t/t3060-subprojects-tutorial.sh
@@ -0,0 +1,95 @@
+#!/bin/sh
+#
+# Copyright (c) 2007 Miklos Vajna
+#
+
+test_description='A simple subprojects tutorial in the form of a test case'
+
+. ./test-lib.sh
+
+test_expect_success "create the submodules" '
+	for i in a b c d
+	do
+		mkdir $i &&
+		cd $i &&
+		git init &&
+		echo "module $i" > $i.txt &&
+		git add $i.txt &&
+		git commit -m "Initial commit, submodule $i" &&
+		cd ..
+	done
+'
+
+mkdir super
+cd super
+cat >expected << EOF
+:000000 100644 00000... A	.gitmodules
+:000000 160000 00000... A	a
+:000000 160000 00000... A	b
+:000000 160000 00000... A	c
+:000000 160000 00000... A	d
+EOF
+
+test_expect_success "create the superproject" '
+	git init &&
+	echo super > super.txt &&
+	git add super.txt &&
+	git commit -m "initial" &&
+	for i in a b c d
+	do
+		git submodule add '`pwd`'/../$i
+	done &&
+	git commit -m "Add submodules a, b, c and d." &&
+	git diff-tree --abbrev=5 HEAD^ HEAD |cut -d" " -f-3,5- >current &&
+	cmp expected current
+'
+
+test_expect_success "checking if the correct commit is stored in the superproject" '
+	for i in a b c d
+	do
+		git ls-files -s $i|cut -d " " -f 2 > $i.actual &&
+		(cd $i && git-rev-parse HEAD) > $i.expected &&
+		cmp $i.actual $i.expected
+	done &&
+	cd ..
+'
+
+test_expect_success "clone the superproject" '
+	git clone super cloned &&
+	cd cloned
+'
+
+test_expect_success "submodule init" '
+	git submodule init
+'
+
+test_expect_success "submodule update" '
+	git submodule update
+'
+
+test_expect_success "checking the result of the commit in the cloned project" '
+	for i in a b c d
+	do
+		git ls-files -s $i|cut -d " " -f 2 > $i.actual &&
+		(cd $i && git-rev-parse HEAD) > $i.expected &&
+		cmp $i.actual $i.expected
+	done
+'
+
+test_expect_success "update the submodule from within the superproject" '
+	cd a &&
+	echo "adding a line again" >> a.txt &&
+	git commit -a -m "Updated the submodule from within the superproject." &&
+	git push &&
+	cd .. &&
+	git add a &&
+	git commit -m "Updated submodule a." &&
+	git push
+'
+
+test_expect_success "checking the result of the commit in the updated cloned project" '
+	git ls-files -s a|cut -d " " -f 2 > a.actual &&
+	(cd a && git-rev-parse HEAD) > a.expected &&
+	cmp a.actual a.expected
+'
+test_done
-- 
1.5.3.2.80.g077d6f-dirty

Re: [PATCH] User Manual: add a chapter for submodules

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 288 bytes --]

On Wed, Sep 19, 2007 at 09:15:58PM -0700, Junio C Hamano <gitster@pobox.com> wrote:
> Looks Ok to me, although I didn't verify the examples by
> actually running them myself this time (last round I did).

just wanted to mention that i did verify them before sending the patch.

- VMiklos

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [PATCH] User Manual: add a chapter for submodules

[Sven Verdoolaege]

On Wed, Sep 19, 2007 at 07:42:50PM +0200, Miklos Vajna wrote:
> +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.

[..]

> +-------------------------------------------------
> +$ mkdir super
> +$ cd super
> +$ git init
> +$ echo hi > super.txt
> +$ git add super.txt
> +$ git commit -m "Initial commit of empty superproject"
> +$ for i in a b c d
> +do
> +	git submodule add ~/git/$i
> +done
> +-------------------------------------------------

You may want to warn the reader not to use local URLs here if they
plan to publish their superproject.

> +It's not safe to run `git submodule update` if you've made changes within a
> +submodule. They will be silently overwritten:

This is only true if they didn't follow your advise of checking out
a branch first.

skimo

Re: [rfc] git submodules howto

[Uwe Kleine-König]

Hello,

Miklos Vajna wrote:
> $ mkdir lib
> $ cd lib
> $ git init
> Initialized empty Git repository in .git/
> $ echo "libmakefile" > Makefile
> $ dg add Makefile
>
> [...]
>
> 1) is this correct? :) i use it and it seem to do what i except, but
> maybe it's not correct

I get 

	bash: dg: command not found

:-)  Probably s/dg/git/

Best regards
Uwe

-- 
Uwe Kleine-König

http://www.google.com/search?q=half+a+cup+in+teaspoons

Re: [rfc] git submodules howto

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 229 bytes --]

On Mon, Sep 24, 2007 at 09:11:35AM +0200, Uwe Kleine-König <ukleinek@informatik.uni-freiburg.de> wrote:
> I get 
> 
> 	bash: dg: command not found
> 
> :-)  Probably s/dg/git/

yes, thanks for the correction

- VMiklos

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]