Drupal + Git submodules: recipes

This article will discuss the basic techniques for working with gita submodules , if used together with drupal.

This post will be most useful for those who, having a modest experience with git, got to the Drupal project where submodules are used. (This is how I became acquainted with the sub-modules, and this particular article was very lacking for me at that time.)

Conditions

We have Linux, installed drush and there is an installation of the seventh drupal. The main repository stores the core of Drupal (and, possibly, our custom modules). All commands are executed from the root directory of Drupal istalation, unless otherwise noted. The module is the drupal module, the submodule is the submodule of the gita.
')

Minimum information about submodules

Submodules are regular git repositories. They are stored separately from the main repository.

The project repository stores a list of used submodules, their location and URLs (in the .gitmodules file) and information about which specific state (version / release / commit / tag) of the submodule will be used (in the depths of the .git directory).

Project Update #

If submodules are used in your project, then it’s best to run these commands after git pull every time:

 git submodule sync #     git submodule update --init #         

Module installation #

The dlash drash team can work with modules as with the submodules of the gita:

 drush dl module_name --package-handler=git_drupalorg --gitsubmodule 

Drash only supports the official repository - git.drupal.org .

In order not to constantly write additional parameters of the dl command, you can configure the drash parameters used by default by adding the following lines to drushrc.php :

 $options['package-handler'] = 'git_drupalorg'; $options['gitsubmodule'] = TRUE; 

In this case, all modules by default will be downloaded as gita submodules and you can write simply:

 drush dl module_name 

If the submodule needs to be installed manually, for example, not from the official repository, then we use the usual command of the gita:

 git submodule add git://github.com/example/module_name.git sites/all/modules/module_name 

Then you need to go to the directory of the installed submodule and switch to the desired release:

 git checkout 7.x-1.0 

Module Version Detection #

If you download the module “in the old manner” from the site drupal.org, then the module version will be indicated in the file module_name.info . It is added to this file automatically when creating a release, it is not in the repository.

In order for Drupal itself to determine the version of the modules, the git_deploy module is needed . He supplements the information received by the drupal from the info-files by adding to it a version of the module, which he “extracts” using various commands of the gita. You can use submodules without git_deploy , but you will not be able to use the update via drush up , because the drush up will not know the current version of the installed modules.

You can find out the version of the module as follows:

 git submodule status | grep module_name 

In brackets will be indicated the tag that is used in our project.
UPD: This method does not always work correctly, as it turned out. It is better to run from the submodule directory:

 git describe --all 

Module update #

The command to update is the most common:

 drush up module_name 

Again, it will only work if we have git_deploy installed.

If we need to update the module manually, let's say we want to upgrade to a specific version. Then we launch two commands from the submodule directory:

 git fetch #      git checkout 7.x-3.5 #      () 

After that, do not forget to run the database update:

 drush updb 

Patch module #

First, it is desirable to switch the submodule to a specific brunch, because

• patches are mostly written for dev versions
• Drash “aims” a submodule at a certain release (tag), which means that your submodule is in a state of “detached head” and further work can be difficult.

For example, if we used the version of the 7.x-3.5 module, switch to the working branch of this release:

 git fetch #      git checkout 7.x-3.x #     git pull #   

Apply the patch using the command line , your favorite IDE or other tools.

We create a separate repository for the module that we patched. For example, on a githaba.

Update the URL of the repository of your submodule. To do this, we find the corresponding section in the .gitmodules file, for example:

  [submodule "sites/all/modules/module_name"] path = sites/all/modules/module_name - url = git://git.drupal.org/project/module_name.git + url = https://github.com/example/module_name.git 

In order for a git to start using a new URL, we perform:

 git submodule sync 

Now you can commit our changes and push everything into our new repository. From the submodule catalog we execute:

 git commit -m "Applied patch from http://drupal.org/node/00000#comment-0000000" git push 

Both your commit and the entire previous module history will get into your repository.

Updating patched module #

Sometimes it is necessary to update the module in which we made our changes, for example, in connection with the release of a security update or the appearance of new features we need.

The easiest solution is to update from the working branch of the official repository. For example, if we previously patched a module based on the 7.x-3.x branch, we launch from the submodule's directory:

 git pull http://git.drupal.org/project/module_name.git 7.x-3.x 

(To be honest, this is the only way I used until now.)

Restore module repository #

If your patch is commited or it is no longer needed, it makes sense to return the submodule to the provision of git.drupal.org . To do this, we update (return the former) URL, synchronize the URLs of the submodules, make git fetch from the submodule directory and check out the desired release. All this is described above.

Removing submodule #

There is no simple command, but there is a stackoverflow recipe :

1. remove submodule sections from .gitmodules and .git/config files,
2. run git rm --cached sites/all/modules/module_name ,
3. commit the changes and delete the submodule directory.

Conclusion

In the context of drupal, the use of submodules provides several advantages. Patching modules becomes more convenient, and keeping them up-to-date is easy. You can use patched or your own modules in several projects, while centrally working on them. And if you consider that to work with submodules you need to learn just a few simple techniques, then we get solid advantages and we conclude that the submodules are a simple and effective tool that can and should be used in Drupal projects.