drupal / scaffold_gitattributes_guard

1.0.0-beta2 2026-11-10 13:05 UTC

Requires

• php: >=8.2
• composer-plugin-api: ^2.0
• drupal/core-composer-scaffold: ^9 || ^10 || ^11

Requires (Dev)

• composer/composer: ^2.0
• openeuropa/code-review-library: ^1.0@alpha
• phpunit/phpunit: ^10.5

GPL-2.0-or-later

Published on Packagist.org on 2026-11-10 12:08 UTC

README

A Composer plugin that protects your .gitattributes file from being overwritten by drupal/core-composer-scaffold.

Background

The .gitattributes file determines how git should treat files depending on the file extension or path.

In a Drupal project with drupal/core-composer-scaffold, Drupal will place its own .gitattributes file with Drupal-specific definitions. This happens on every composer install or composer update.

In some cases, a developer might want to add additional rules to the .gitattributes file. One such scenario is Git LFS (Large File Storage), when a project contains files that should be tracked by Git but stored remotely and downloaded on demand.

Problem

drupal/core-composer-scaffold overwrites .gitattributes on every composer install or composer update. If you maintain custom rules in .gitattributes (e.g. Git LFS tracking), they get destroyed.

Solution

The idea is to keep custom rules, such as Git LFS mappings, in the tracked .gitattributes file, while storing Drupal's generated mappings in .git/info/attributes, which is local to each checkout and is not tracked by Git.

This plugin hooks into the Drupal scaffold process:

1. Before scaffold: Backs up your tracked .gitattributes (containing your custom rules).
2. After scaffold: Moves the scaffold-generated content to .git/info/attributes (local-only, not tracked by git) and restores your original .gitattributes.

This means:

• Your tracked .gitattributes stays clean (only your custom rules).
• Drupal's scaffold attributes still take effect locally via .git/info/attributes.
• No noise in git history from Drupal core upgrades.

Installation

composer require --dev drupal/scaffold_gitattributes_guard

When prompted, allow the plugin to execute code.

How it works

The plugin subscribes to two events fired by drupal/core-composer-scaffold:

• pre-drupal-scaffold-cmd — backs up .gitattributes
• post-drupal-scaffold-cmd — moves scaffold output to .git/info/attributes, restores the backup

Git attribute precedence

Git resolves attributes in this order (highest priority first):

1. .gitattributes in the directory
2. Parent directory .gitattributes files
3. .git/info/attributes

Since your custom rules remain in .gitattributes, they always take precedence over scaffold rules in .git/info/attributes.

Requirements

• PHP >= 8.2
• Composer 2.x
• drupal/core-composer-scaffold (which provides the pre-drupal-scaffold-cmd and post-drupal-scaffold-cmd script events)

Example

Your tracked .gitattributes:

# Custom rules
*.po merge=po-merge
docs/* linguist-documentation

After composer install, this file remains unchanged. The scaffold-generated attributes are in .git/info/attributes (not tracked).

Local development

From the project root:

ddev config --project-type=php --php-version=8.3 --omit-containers=db
ddev start
ddev composer install
ddev exec vendor/bin/grumphp run --no-interaction
ddev exec vendor/bin/phpunit

License

GPL-2.0-or-later