Drupal + Git submodules: recipes

This article will discuss the basic methods of working with submodules of the guitar , if you use them together with Drupal.

This post will be most useful for those who, having a modest experience with git, got on a Drupal project where submodules are used. (That’s how I met submodules and it was such an article that I really missed at that time.)

Conditions

We have Linux, drush is installed and there is an installation of the seventh drupal. The main repository contains the core of Drupal (and, possibly, our custom modules). All commands are executed from the root directory of the Drupal installation, unless otherwise specified. A module is a Drupal module, a submodule is a guitar submodule.

Minimum Submodule Information

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 a file .gitmodules) and information about which specific state (version / release / commit / tag) of the submodule will be used (in the bowels of the catalog .git).

Project update #

If your project uses submodules, then it is best git pullto execute these commands every time after :

git submodule sync # обновляем используемые УРЛы репозиториев
git submodule update --init # устанавливаем новые подмодули и обновляем состояние уже установленных

Installing the module #

The drash team knows dlhow to work with modules as with sub-modules of a gith :

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

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

In dlorder not to constantly write additional parameters of the command , you can configure the values ​​of the drash parameters used by default by adding to the drushrc.phpfollowing lines:

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

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

drush dl module_name

If you need to install the submodule manually, for example, not from the official repository, then we use the usual git command:

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

Determining the module version #

If you download the module “the old fashioned way” from drupal.org, then the version of the module 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 to determine the version of the modules, the git_deploy module is needed . It supplements the information received by the Drupal from info-files by adding to it a version of the module, which it “extracts” using various commands of the git. You git_deploycan use submodules without , but you cannot use the update through drush up, because Drupal will not know the current version of installed modules.

You can also find out the module version like this:

git submodule status | grep module_name

In brackets the tag that is used in our project will be indicated.
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 most common command to update is used:

drush up module_name

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

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

git fetch # обновляем информацию из удаленного репозитория
git checkout 7.x-3.5 # переключаем код на требуемый релиз (тег)

After that, do not forget to start the database updates:

drush updb

Patch module #

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

• patches are mostly written for dev versions
• drash "targets" the submodule to a specific release (tag), which means that your submodule is in the "detached head" state and further work may be difficult.

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

git fetch # обновляем информацию из удаленного репозитория
git checkout 7.x-3.x # переключаемся на рабочую ветку
git pull # обновляем ветку

I’ll 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 github.

Updating the URL of your submodule repository. To do this, find the appropriate section in the file .gitmodules, 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 the git to start using the new URL, we do:

git submodule sync

Now you can commit our changes and push everything into our new repository. From the submodule directory, do the following:

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 go into your repository.

Updating the 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 brunch 7.x-3.x, from the directory of its submodule, run:

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

(To be honest, this is the only way I have used up to this point.)

Module repository recovery #

If your patch is committed or is no longer needed, it makes sense to return the submodule to collateral git.drupal.org. To do this, update (return the previous) URL, synchronize the URLs of the submodules, make git fetchthe submodule’s catalog and check out the necessary release. All of this is described above.

Removing a submodule #

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

1. delete submodule sections from files .gitmodulesand .git/config,
2. perform 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 offers several advantages. Patching modules becomes more convenient, while maintaining them up to date is easy. You can use patched or your own modules in several projects, while centrally conducting work on them. And if you consider that to work with submodules you need to learn just a few simple tricks, then we get solid pluses and conclude that submodules are a simple and effective tool that can and should be used in Drupal projects.