Backdrop CMS configuration files and Git: The figure-8 approach

I've written about how to manage your configuration directory in version control (Git) several times, but now that I've done it in the wild on a few different sites, I thought I'd write it up here as well.

Note: this figure-8 approach works best when there is only a single developer on the project. If there is more than one, this approach can get confusing, and I prefer the versioned staging directory approach.

Below I have outlined how I set up most of my sites, with the Git root a directory above the webroot. This allows me to keep things that should not be web-accessible (like config!) in version control.

/git-root/
/git-root/webroot/
/git-root/webroot/files/
/git-root/config/
/git-root/config/dev-active/
/git-root/config/prod-active/
/git-root/PATCHES.txt

Things not to track

The files directory should NOT be in version control. Files in this directory are actually *content* and are managed in your database. Do not allow Git (or any other VCS) try to manage these files for you.

The settings.php file should probably not be in version control. This is because it contains database credentials that you don't want accidentally made public. If you have other things going on in this file that you *do* want tracked (such as memcache settings, or other configurations) make sure that your database connection information is not in the file when it is committed. You can get around this by storing your db connection string in another file named settings.local.php that's not tracked, but included via settings.php.

Things to track

Add all your backdrop files (except the two things mentioned above) into the webroot directory, and track those with Git. This includes backdrop core as well as your custom and contributed modules, themes, and layouts.

Add all your config. Really? Yes, really! Add the whole config directory, both dev-active and prod-active. We want them both tracked so the figure-eight magic will work :)

What your settings.php files look like

We've moved the config directory, and renamed the folders within. That means we need to update our settings.php file to match. Below you'll see what my file looks like on both my dev environment and on my production server.

Development environment settings.php

On my dev site I need to be actively reading config out of the dev-active directory, so my settings.php file looks like this:

$config_directories['active'] = '../config/dev-active';
$config_directories['staging'] = '../config/prod-active';

Production environment settings.php

On my live site I need to be actively reading config out of the prod-active directory, so my settings.php file looks like this:

$config_directories['active'] = '../config/prod-active';
$config_directories['staging'] = '../config/dev-active';

Workflow: pulling code up to production

Now when I do a git pull on production all the files I added into dev-active on my local site land nicely in the "staging" directory on my production site. Then I can use the all-important importer tool in the Config Management UI to run the necessary changes on my production site when it pulls in those files.

Workflow: pulling config back down to development

I can also log into my production server, git add all the files in prod-active, and git commit those files right there. Then I can do a git pull from my development environment and see all the recent changes land safely in the "staging" directory on my local site, which allows me to run the importer tool in the Config Management UI.

Tips & Tricks

I also keep my PATCHES.txt file right in my git root. It's easy for other developers to find there, and it's out of the web root so inaccessible to nosy neighbors.