Drupal Best Practices: Version Control with Git for Streamlined Development

In the modern web development landscape, version control is a non-negotiable best practice. For Drupal development, Git is the most widely used version control system, offering a way to track changes, collaborate across teams, and manage the deployment process efficiently. By implementing a well-structured Git workflow and properly configuring files to be ignored, you can maintain clean, scalable, and secure development environments.

This blog post will cover the best practices for using Git in your Drupal projects:

Git Workflow: Use Git for version control and maintain separate branches for development, staging, and production. Utilize feature branches for new functionalities and bug fixes.
Ignore Files: Properly configure your .gitignore file to exclude files and directories that should not be version-controlled, such as /sites/default/files and sensitive configuration files.

Following these practices will help ensure that your development process is efficient, collaborative, and secure, making it easier to track changes, collaborate with your team, and deploy updates to your Drupal site.

Git Workflow: Structure Your Development Process with Branches

A well-defined Git workflow is essential for managing your Drupal project’s codebase. It ensures that code is properly tested and reviewed before being deployed to production and allows multiple developers to work on different features simultaneously without causing conflicts.

Why Git is Essential for Drupal Development

Track Changes: Git allows you to track every change made to your codebase, from small tweaks to major feature updates. This gives you a history of changes and the ability to revert back to previous states when necessary.
Collaborate Efficiently: With Git, multiple developers can work on the same project simultaneously, without overwriting each other’s work. Branches and pull requests make it easy to review, test, and merge code changes.
Deploy Safely: Git workflows allow you to manage different environments (development, staging, and production) with separate branches, ensuring that code is fully tested before being deployed to the live site.

Structuring Your Git Workflow

1. Main Branches: Development, Staging, and Production

A common Git workflow for Drupal involves maintaining separate branches for different environments:

main (or master): This is the branch that reflects the production environment. Only stable, thoroughly tested code should be merged into the main branch.
staging: The staging branch is used to prepare code for the production environment. Before code is pushed to production, it should first be merged into the staging branch for final review and testing.
develop: The develop branch is where active development happens. It is typically used as a base for feature branches and is updated frequently with new functionality, bug fixes, and changes.

2. Feature Branches for New Functionalities

For each new feature, bug fix, or significant change, create a feature branch from the develop branch. This approach ensures that developers can work on individual features without affecting the main development environment.

Example workflow:

Create a feature branch:

   git checkout -b feature/my-new-feature develop

Develop the feature: Work on the feature in this branch, making commits as necessary.

   git add .
   git commit -m "Add new feature"

Push the branch: Once you’re done, push the feature branch to the remote repository.

   git push origin feature/my-new-feature

Create a pull request (PR): Open a pull request to merge the feature branch into the develop branch. This allows other developers to review the code before it is integrated.
Merge into develop: After the code has been reviewed and approved, merge it into the develop branch.
Merge into staging and main: Once the feature has been tested in the staging environment and is ready for production, merge the develop branch into the staging branch for final tests, and eventually into the main branch when deploying to production.

Example Git Workflow:

# Start from develop
git checkout develop

# Create a feature branch
git checkout -b feature/add-news-section

# Make some changes
git add .
git commit -m "Implement news section layout and functionality"

# Push the changes to the remote repository
git push origin feature/add-news-section

# After code review, merge into develop
git checkout develop
git merge feature/add-news-section

This workflow ensures that the development, testing, and production environments remain stable and organized, while enabling developers to work on different features in parallel without causing conflicts.

3. Hotfix Branches for Emergency Fixes

If a bug is discovered in the production environment, you can create a hotfix branch directly from the main branch. Once the issue is resolved, merge the hotfix into both main and develop (or staging), ensuring the fix is reflected across all environments.

Ignore Files: Keep Your Git Repository Clean with .gitignore

One of the most important aspects of version control in Drupal is ensuring that your Git repository doesn’t include files and directories that shouldn’t be version-controlled. This is where the .gitignore file comes into play.

Why Ignoring Files is Important

Security: Certain files, like configuration files that contain sensitive information (e.g., database credentials, API keys), should not be committed to Git. Excluding them from version control prevents unauthorized access to these sensitive details.
File Size: Files like images, user-uploaded content, and other assets in the /sites/default/files directory should be excluded to avoid bloating your repository. These files should be handled by your file storage or deployment process, not by Git.
Avoid Conflicts: Automatically generated files, like cache or compiled CSS/JavaScript files, can cause unnecessary conflicts when working in teams. These files are best excluded from version control.

Essential Entries in Your .gitignore for Drupal

Here’s an example of a typical .gitignore file for a Drupal project:

# Ignore the Drupal files directory
/sites/default/files/

# Ignore configuration sync directory
/config/sync/

/sites/*/settings.php
/sites/*/services.yml

# Ignore composer vendor directory
/vendor/

# Ignore generated files
/node_modules/
/*.log
*.cache
*.css
*.js

Key Directories and Files to Exclude:

/sites/default/files/: This is where Drupal stores user-uploaded content like images, documents, and other assets. These files should not be committed to Git because they are typically large and can change frequently. Instead, they should be managed by your deployment process or file storage solution.
/config/sync/: When using Drupal’s Configuration Management system, configuration changes are exported to YAML files in the /config/sync directory. It’s generally recommended to exclude this directory from version control to avoid sensitive information being stored. However, some workflows include configuration in version control with encrypted secrets or other strategies, so this depends on your specific project needs.
settings.php and services.yml: These configuration files contain sensitive information like database credentials. Never commit them to your repository. Instead, use environment variables or deploy these files separately.
Vendor Directory: If you’re using Composer to manage Drupal core and modules, the vendor/ directory, which contains all the downloaded dependencies, should be excluded from Git. Composer ensures that everyone working on the project has the correct dependencies installed locally by running composer install.
Node Modules: If you’re using a front-end build process like Node.js, exclude the node_modules/ directory, as these dependencies can be reinstalled by running npm install.

Customizing Your .gitignore

Depending on the specifics of your project, you may need to customize your .gitignore file further. For example, if you’re using a different configuration sync directory or if your deployment process requires certain files to be handled in a specific way, you’ll need to adjust the .gitignore file accordingly.

Best Practices for Managing Git in Drupal Projects

Commit Often, But Meaningfully: Break your work into small, manageable chunks, and commit frequently with clear, descriptive messages. Each commit should reflect a meaningful change that is easy to understand when revisiting the history.
Pull Before You Push: Always pull the latest changes from the remote repository before pushing your own changes to avoid conflicts.
Review Code Before Merging: Use pull requests or merge requests to review code before merging it into develop or main. This ensures that all changes are reviewed for quality, security, and potential bugs.
Tag Releases: Use Git tags to mark significant releases, such as new versions of your Drupal site. This makes it easy to track releases and roll back to a previous version if needed.
Use Hooks for Automation: Set up Git hooks (like pre-commit or post-merge) to automate tasks such as running tests, linting code, or clearing caches, ensuring that code meets quality standards before it’s committed.

Conclusion

Using Git effectively is essential for managing Drupal projects in a collaborative, scalable, and secure way. By implementing a well-structured Git workflow—using branches for development, staging, production, and feature development—you can ensure that your code is always well-organized and easy to manage. Additionally, properly configuring your .gitignore file will keep your repository clean, secure, and optimized.

By following these best practices, you’ll improve the efficiency of your development process, enhance collaboration across teams, and maintain the stability of your Drupal site as it evolves. Whether you’re working on a small site or a large enterprise project, Git will be an invaluable tool in maintaining your Drupal project’s integrity.

Deployments & Environment Management