Updated on June 20, 2022

Drupal's Configuration Management (CM) is a "killer feature" for a web Content Management System (CMS). When setting up a Drupal site, we spend a lot of time on site configuration: Roles, Permissions, Content Types, Menus, Vocabularies, etc. In most CMS's, all these changes are stored in their databases, making it hard to deploy, track, reuse and rollback important changes.

In Drupal, configuration remains on the database, but it can be imported/exported from/to code. And of course, once we can have our site configuration in code, we can keep track of it using a version control system, like Git.

In the following tutorial, I'll explain how to set up git and use drush commands to track your configuration. I'll assume that you already have Drupal installed, and that you've created your Git repository (if you haven't done this before, just create an account on GitHub and run through the steps of creating a repo).

Using Configuration Management and Git to Track Drupal Configuration

Step 1 - Adding a Git Ignore File

Once Drupal is installed, a set of files and folders specific to each Drupal setup are created in the code base. Some of them are installation-specific and for sure you won't want them on your repo. For example:

  • sites/default/settings.php
  • sites/default/files/
  • sites/default/files/css/
  • sites/default/files/js/
  • sites/default/files/php/

To avoid committing these, just duplicate the "example.gitignore" file that comes with Drupal to ".gitignore" and actually use it as supposed to:

$ cp example.gitignore .gitignore

Step 2 - Initiate and Register the Repo

$ git init
$ git add .
$ git commit -m "Initial Commit: Drupal 8.x Code base"

Add your remote repository clone URL

$ git remote add origin REMOTE_CLONE_URL

Push the commit up to GitHub.

$ git push -u origin master

So now that we have our Drupal site working, we will start using Configuration Management to have control of our site changes.

Step 3 - Export the Configuration

The first thing we will do is export our current configuration, so we can see, while working and customizing our site, what is changing with time.

Through the command line, from the root folder of our Drupal install, we will export the entire site configuration to a new folder we'll call config/site :

$ mkdir config
$ drush config-export --destination=config/site

Drupal 8 Configuration management with Git and Drush

Commit and push the changes to the repository. You will notice there are dozens of small YAML files containing all the config of your site. These files are known as Configuration Entities and each one contains a specific part of your site setup. You can learn more about Configuration files from Drupal Docs: Defining and using your own configuration in Drupal.

And now you have a "snapshot" of how was your site configured when you installed it! Thanks to CM, now you have the initial state of your website on your repo and you can roll it back anytime. 

Step 4 - Import the Configuration

You can import the configuration from config/site folder using the following command:

# Import the configuration from the repository
$ drush config-import --source=config/site

Just remember that each time you import, your current configuration will be completely overwritten. Drupal will always warn you and show the conflicting configuration entities.

IMPORTANT: Although on this example, the configuration is being exported to the "config/..." folder, it is mandatory to ensure that the configuration files are not accessible via the web server, either blocking the access to these or placing the folder outside of the Drupal folder.

Tips and Tricks for Using Configuration Management Successfully

I would suggest you take the following into account during your D8 project workflow:

  • Always export before running git pull. Git doesn't know what recent config changes have you made in your database until you actually export them.
  • You can export multiple configuration sets into different folders. This is ideal for testing, and you can export as many as you want. For example, you can have a "staging" and a "prod" configuration.
  • Run database dumps regularly and before each import. It's always good to have a backup just in case.
  • If you want to bundle configuration, try using the Features module.
  • Check for "drush config-import" and "drush config-export" documentation page for more details about additional options (preview, skip modules, etc.)
  • You can also use Drupal Console for importing and exporting configuration

What's Next?

My first suggestion is to take a look at my most recent blog post about Restoring a Drupal site from Configuration Files.

Additionally, here's a list of some useful resources you may want to refer to after reading this blog post:

And if you're looking for hands-on training to help you get up-and-running with configuration management (and learn how to build Drupal modules while you're at it), we regularly run a Drupal Module Development course that covers these and other topics.

Tags
Drupal Planet
Drupal