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
Hello, I get Best regards Uwe -- Uwe Kleine-König http://www.google.com/search?q=half+a+cup+in+teaspoons -
On Mon, Sep 24, 2007 at 09:11:35AM +0200, Uwe Kleine-K=F6nig <ukleinek@info= yes, thanks for the correction - VMiklos
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. -
On Tue, Sep 18, 2007 at 09:29:40AM -0400, "J. Bruce Fields" <bfields@fields= 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
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. -
[ adding Michael to CC. ] On Tue, Sep 18, 2007 at 11:55:29AM -0400, "J. Bruce Fields" <bfields@fields= 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
Maybe signed-off-by is appropriate? Otherwise, don't worry about it. Mike -
Signed-off-by: Michael Smith <msmith@cbnco.com> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> --- 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: ...
You may want to warn the reader not to use local URLs here if they This is only true if they didn't follow your advise of checking out a branch first. skimo -
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:
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
Before doing this "git add", it would be educational to have the
user do
$ git diff
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
The list is good, but are they Problems or pitfalls to watch out
The same caution applies not to rewind branches in submodule
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
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 thi...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: + +------------------------------------------------- +$ l...
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
Hi, So maybe we should do the same as with the tutorial: stick the examples into a test script? Ciao, Dscho -
Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> --- 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 -
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. -
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...
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. -
Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> --- 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...
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
-Hi, 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 -
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 -
On Thu, Sep 20, 2007 at 07:47:32PM +0100, Johannes Schindelin <Johannes.Sch= 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
Signed-off-by: Michael Smith <msmith@cbnco.com> Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> --- [ 2nd version ] right, changed it to two examples, one about "git checkout master", and yes, it was illogical to use a 'note' here as it's not related. i've right, i forgot the 'cd ~/git/super/a'. provided the repos are symmetric, i think it would just make the situation unnecessary 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 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 comm...
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. -
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 -
Hi, AFAICT there is one, on the git Wiki, since yesterday. Ciao, Dscho -
| Linus Torvalds | Linux 2.6.27-rc8 |
| Bron Gondwana | BUG: mmapfile/writev spurious zero bytes (x86_64/not i386, bisected, reproducable) |
| Jeff Garzik | Virt RNG? |
| Crispin Cowan | AppArmor Security Goal |
git: | |
| walt | [VOTE] git versus mercurial |
| Pavel Roskin | Implementing branch attributes in git config |
| Peter Karlsson | RCS keyword expansion |
| Johannes Schindelin | Re: Empty directories... |
| Christian Weisgerber | Re: libiconv problem |
| Steve Shockley | Re: Real men don't attack straw men |
| Theo de Raadt | Re: Oddly high load average |
| Steve B | Intel Atom and D945GCLF2 |
| Karlin Dodd | VL-bus questions |
| Jim Winstead Jr. | Re: Root Disk/Book Disk Compatibility |
| Joern Rennecke | Use shadow ram? |
| Framstag | ftp-error: bind: Address already in use? |
