5 Critical Files for Every Drupal Project's Git Repository

I’m not sure how I survived without Git early in my career. I didn’t use any version control at all when I was first starting out (I didn’t know any better). Today, I can’t imagine building any project without version control and Git specifically!

What fascinates me today is how varied the repositories of various companies appear to be. Obviously my own teams’ tend to have consistent approaches to building out projects (and therefore have a consistent set of files). But this is hardly the case for Drupal 8 / 9 projects run by different teams. So this post is my must have list for files that should be in every git repository for Drupal projects.

Note: even if you aren’t building with Drupal, a lot of this list applies broadly!

1. lock file(s)

Dependency managers are a critical part of modern software (and web) development. A key part of many dependency managers are a lock file (you’ll find these with composer, yarn, npm, etc.). The goal of these files is to ensure that each person working on a project and each system running that project’s code all have hyper accurate tracking of the versions of dependencies being used.

By committing the lock files (e.g. composer.lock, package.lock) you are ensuring that when it runs the dependency manager will install the specific version of each dependency that is committed. There is some argument for not committing the lock file in the Drupal world. My general rule is:

• are you building an actual site? then always commit the lock file

• are you building a module / distribution / profile / theme? then don’t

Example composer.lock file

2. gitignore

What does not go into version control is almost as important as what does. The gitignore file allows you tell Git to ignore files and/or folders to keep them out of your version control history. Common examples are:

• files / folders generated by IDEs (e.g. .idea by PHPStorm)

• files / folders managed by the dependency manager(s) (e.g. vendor)

• local specific settings / configuration files

• “Drupal” file system (bot public and private)

• OS Specific Files (e.g. .DS_Store on Macs, $RECYCLE.BIN on Windows)

You should also consider what sorts of front end build tools you’ll be using. If you’re writing code in SASS and then compiling to CSS as part of the process, perhaps also gitignore your css file(s) and rely on the compiling process during continuous integration.

Example .gitignore file

3. editorconfig

The editor config file allows you to pre-configure certain key behaviors of your team’s text editors / IDEs. This helps to ensure that each editor will respect the same basic rules without having to manually configure them.

Common / critical configuration here includes:

• line endings

• indent style (space vs. tab)

• number of space characters (usually 2 vs. 4)

One of my biggest pet peeves when working with multiple developers is a constantly shifting git history when editors treat “things” differently. The editor config file helps eliminate much of this churn!

Example of .editorconfig file

4. VM configuration

I’m constantly surprised when I don’t find local environment configuration inside the git repository. We always commit our VM configuration no matter which VM we’re using. Granted, the config files are all a bit different and live in different places depending on if you’re using Drupal VM, Lando, DDev, or Docksal, but at the end of the day having that config in the repo ensures that each developer is using the exact same VM config.

Example Lando Configuration File

5. README

I’m not someone who gets super hung up on if you have a README or CONTRIBUTING file. As long as you have “something” that helps people coming onto the project understand what is going on AND you keep that file up to date AND you keep it in the codebase.

The goal of this / these file(s) is to provide insight into your team into what technologies are being used, provide useful links out to CI tools, issue tracking systems, etc. Everything needed to get up and running should be right there within the project so that there are no additional access requirements to spin up and get started once the developer has access to the repository itself.

Example README.md file

In Conclusion

Having a consistent git template to be used (and reused) across projects is a highly useful tool. Acquia provides several free / open source / recommended templates in the form of the Drupal Recommended Project and Lightning Project repositories. Take careful stock of the tools and software that your team will typically use on projects and forma the gitignore and editorconfig accordingly. A little attention to this detail will ultimately pay significant dividends during actual project builds.

Related Content