Submodule design

Submodule design

[Ramkumar Ramachandra]

Hi,

Today I learnt that a gitlink is a commit object embedded in a tree.
However, I can't seem to be able to cat it.

    $ git ls-tree HEAD
    100644 blob 5a91f388f3648b98ae34a19ec42ba9acc7852ef4    .gitmodules
    160000 commit 8daa12004db8862b22f6c7dd244a88ac6108b194  dotfiles
    $ git cat-file 8daa12004db8862b22f6c7dd244a88ac6108b194
    fatal: git cat-file 8daa12004db8862b22f6c7dd244a88ac6108b194: bad file

Why is this?  Does the object not exist in the object store at all?
Then how was it embedded in the toplevel tree object in the first
place?  Also, why (how) does 'git diff' give me the impression that
it's a blob?

    $ git diff
    diff --git a/dotfiles b/dotfiles
    index 8daa120..ff61f40 160000
    --- a/dotfiles
    +++ b/dotfiles
    @@ -1 +1 @@
    -Subproject commit 8daa12004db8862b22f6c7dd244a88ac6108b194
    +Subproject commit ff61f40e0938024aa3b748eb733a974b17082ec2

If it is really a blob, I should be able to stage and unstage it
normally, but the following command is a no-op:

    $ git checkout -- dotfiles

What is going on?  Shouldn't we get rid of these ugly inconsistencies?

Ram

Re: Submodule design

[Sascha Cunz]

Am Dienstag, 2. Oktober 2012, 20:53:28 schrieben Sie:
> Hi,
> 
> Today I learnt that a gitlink is a commit object embedded in a tree.
> However, I can't seem to be able to cat it.
> 
>     $ git ls-tree HEAD
>     100644 blob 5a91f388f3648b98ae34a19ec42ba9acc7852ef4    .gitmodules
>     160000 commit 8daa12004db8862b22f6c7dd244a88ac6108b194  dotfiles
>     $ git cat-file 8daa12004db8862b22f6c7dd244a88ac6108b194
>     fatal: git cat-file 8daa12004db8862b22f6c7dd244a88ac6108b194: bad file
> 
> Why is this?  Does the object not exist in the object store at all?

Correct. The tree entry is a pointer to the commit inside your submodule that 
shall be checked out. Obviously the submodule's commit is not part of the 
superproject. 
IOW: There are are actually 2 object stores: the superproject's and the 
submodule's. This tree entry makes a (perstiable) connection between the two.

> Then how was it embedded in the toplevel tree object in the first
> place?
The .gitlink for submodules has quite some special handling associated to it. 
You can commit (and diff) it like any other blob. 

> Also, why (how) does 'git diff' give me the impression that
> it's a blob?

>     $ git diff
>     diff --git a/dotfiles b/dotfiles
>     index 8daa120..ff61f40 160000
>     --- a/dotfiles
>     +++ b/dotfiles
>     @@ -1 +1 @@
>     -Subproject commit 8daa12004db8862b22f6c7dd244a88ac6108b194
>     +Subproject commit ff61f40e0938024aa3b748eb733a974b17082ec2

See above. Git smartly converts the "state" of the submodule into a one line 
text, allowing you to "diff 2 states of the submodule"

cd dotfiles
git pull # pulls some updates
cd ..
git add dotfiles && git commit -m"Update dot files to Version xxx"
git push

This will record the dotfiles submodule's new HEAD SHA1 as the current one 
inside the superproject. When you now checkout the superproject to another 
location and do: a "git submodule update --init" it will clone the dotfiles 
submodule and checkout the exact same version that you just commited with the 
above commit.

> If it is really a blob, I should be able to stage and unstage it
> normally, but the following command is a no-op:
> 
>     $ git checkout -- dotfiles
> 
> What is going on?  Shouldn't we get rid of these ugly inconsistencies?

HTH,
Sascha

Re: Submodule design

[Junio C Hamano]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

> Hi,
>
> Today I learnt that a gitlink is a commit object embedded in a tree.
> However, I can't seem to be able to cat it.
>
>     $ git ls-tree HEAD
>     100644 blob 5a91f388f3648b98ae34a19ec42ba9acc7852ef4    .gitmodules
>     160000 commit 8daa12004db8862b22f6c7dd244a88ac6108b194  dotfiles
>     $ git cat-file 8daa12004db8862b22f6c7dd244a88ac6108b194
>     fatal: git cat-file 8daa12004db8862b22f6c7dd244a88ac6108b194: bad file

Is this handcrafted typescript?  You do not have "-t" nor "commit"
after cat-file, so you should have got the usage message.

In any case, not having the commit object available in the
superproject is essential and fundamental.

Binding a separate project as a submodule at a specific path in the
superproject, instead of adding the tree structure as a subdirectory
as part of the superproject, is what allows you (note this is not
"requires") to work with the superproject _without_ having to
populate the submodule.  Imagine a submodule for the source of a
library the superproject uses and the superproject is arranged in
such a way that you can build the whole thing from the source, or
you can use the installed library and link to it.  When doing the
latter, you do not have to "submodule init" that part.

The only thing the superproject needs to record is what specific
state of the submodule is meant to appear, if it is instantiated, in
the path.  We (primarily Linus, actually) chose to do so by
recording the name of the commit object from the submodule after
considering other possibilities (check the list archive).

And having to include that commit object in the superproject defeats
the whole point of binding a _separate_ and _independent_ project as
a submodule.  You could deliberately arrange the submodule so that
it shares the object store with the superproject, but that is not
the common or default mode of operation.  Not finding an object from
the submodule's history in the superproject is perfectly normal.

> What is going on?  Shouldn't we get rid of these ugly inconsistencies?

I do not see anything ugly or inconsistent, except that the way you
phrased your message may be unnecessarily an ugly way to show
frustration coming either from a lack of understanding or from a
simple misunderstanding.