Implementation Details – Git Submodule Support

Here are some implementation details about the Git Submodule support which is now available in the Orion Web IDE. If you have not already read about the features, please check the Git Submodule Support post. A Detailed User Guide is also available.

Remove submodule

There are two ways to entirely remove a submodule from its parent repository. The old way involves manually changing all the configuration files and removing the actual submodule directory. It can also be done by using the deinit command, available since git 1.8.3 (April 22, 2013).

Since JGit does not yet support the deinit command, we have to use the previous method to do the job. Here is a list of operations the remove command will do for you:

1. Remove the corresponding submodule entry in the .gitmodules file, if there is no more entries left, remove the file itself.
   
   
2. Remove the corresponding section in the .git/config file. It will look like this.
   
3. Run git rm –cached path/to/submodule.
4. Delete the .git/modules/name_of_submodule folder.
   rm -rf .git/modules/name_of_ submodule
5. Use git rm on the submodule directory, so it removes the submodule’s work tree from that of the parent repository and the gitlink from the index.
   rm -rf path/to/submodule

A lengthy but standard procedure. If it is different from what you are used to do for submodule removal, you might have to tweak the configurations yourself afterwards.

Regretting removing a submodule?

The Orion Git page has a convenient way of undoing changes. What it is actually doing is calling git checkout on specific paths to undo the changes in those paths. It works in most cases, but, it might work differently from what you expect it to do.

In Orion the Git component, submodules are treated similarly as in Git command line, this means that the parent repository will not have any knowledge of what is going on inside the submodule, and when it tries to remove a submodule, it will simply remove the whole folder without checking the contents inside it. Because of this, when undoing the removal, the content of the folder can never be recovered as it is never recorded in the first place.

Undoing the removal at this point will only bring back the empty folder and the config changes, the submodule will be treated as an uninitialized submodule and you need to init and update it to fetch the content from the remote URL.

Add submodule

Adding a submodule is basically the same as git submodule add command in the command line, where you can specify the path of which the submodule is going to be contained.

Also it has the same problem as in the command line, that is, when you clone, sync or update, you have the –recursive flag to make the operation affect submodules at all levels. But add submodule command does not have that, it only initializes the first level submodule for you. Consider this scenario:

1. Create repository “subrepo” and add submodule “submodule” into it
2. Create repository “mainrepo” and add submodule “subrepo” into it

Now in the “mainrepo”, “subrepo” will be initialized, but “submodule” will just be an empty folder inside of “subrepo” since it is not initialized.

You will have to update the nested submodules by yourself.

Update submodule

To make the user’s life easier, update and init command for submodule are combined into one single command. When you invoke the update command, it runs the equivalent of git submodule update –init for you.

If you have used submodules intensively in the past, you would probably be using git submodule update –init –recursive a lot. But since JGit does not have native recursive flag support, we consider the recursive flag not essential and we do not have it for update at this point.

Until nested repositories containing hundreds of layers of submodules becomes common, if you have nested submodules, you will be to update them one layer at a time.

Sync submodule

Sync is the kind of operation that has to be there but nobody really uses it. It mimics git submodule sync command, and due to the reason mentioned above, sync does not have recursive flag either.

Undoing Changes

Submodules are pretty messy to work with if you do not follow a strict workflow. If you have been using submodules, I would assume that there were times you hope that you did not press update, since it nukes all the changes you have in the submodules, and the name of the command does not suggest the nuclear nature of it at all.

Unfortunately as I have mentioned the parent repository has no ideas about the content of the submodules, and there is no undoing after it is done.