Using git subtree to Make a Distro Your Docroot

A cornerstone of good Drupal development is deploying your site’s code from a version control system like Git or SVN. A further best practice is to put all your code in a directory in the repository, instead of at the top level of the repository. Doing this allows you to put other things into the repository that are not intended to be served publicly. For example, Acquia’s Cloud Hooks are scripts you put into the hooks directory that run when you deploy code, databases, or files, but should never be served as site content. Using Cloud Hooks, your repository looks like:

/docroot/... your site code …

/hooks/... your Cloud Hooks here …

At first glance, though, this approach has a downside. Many people want to use Git to track the Drupal distro their site is built from (Drupal core, Acquia Drupal, Pressflow, etc.) so they can easily pull in changes. However, most distro repositories keep their code directly in the top level of the repository. Simply adding the distro repository as a Git remote and running git pull puts the distro code in the top level of your repository too, which is not where you want it. In addition, you certainly cannot install contributed Drupal modules and themes into the top level of your repository.

Thus, the question for today is: How do you merge a remote repository (the distro) into a directory in your repository (the docroot), such that you preserve the remote repository's history and can easily merge in future updates? The best answer (according to stackoverflow and others) is to use the added set of git subtree commands rather than git's built-in subtree merging facility or the git submodule system.

In brief, here are the steps (assuming you already have git set up):

Install the new git subtree command

Clone your Acquia Cloud git repository

Delete the docroot

Subtree merge the distro as the new docroot so you can later run subtree pull to get updates

Note that you may want to use the --squash flag so this is a single commit, rather than pulling in the whole history. However, pressflow has relatively few commits, and you may find it interesting to look at some of the specific changes.

Add the settings.php file and add to it the file include command from the “Databases” section of the Acquia Cloud UI.

You can then later update the module by replacing “add” with “pull”, as shown above for the distro. This approach is likely most useful for modules that are in active development or that you contribute to. For stable releases of other modules, you can use drush or just directly download the module and git add it to your repository.

P.S. - The git subtree install instructions also describe how to make and install a man page. Sadly, this tends to require building a couple helper programs or installing more packages just to end up transforming the initial .txt instructions into a slightly different man page text file. You can use the attached man file and copy it into place.

A cornerstone of good Drupal development is deploying your site’s code from a version control system like Git or SVN. A further best practice is to put all your code in a directory in the repository, instead of at the top level of the repository. Doing this allows you to put other things into the repository that are not intended to be served publicly. For example, Acquia’s Cloud Hooks are scripts you put into the hooks directory that run when you deploy code, databases, or files, but should never be served as site content.