eliashaeussler/gitattributes

Parser for .gitattributes files in an object-oriented way

1.0.1 2024-11-09 14:23 UTC

Requires

• php: ~8.1.0 || ~8.2.0 || ~8.3.0
• symfony/filesystem: ^6.4 || ^7.0
• symfony/finder: ^6.4 || ^7.0

Requires (Dev)

• armin/editorconfig-cli: ^1.8 || ^2.0
• eliashaeussler/php-cs-fixer-config: ^2.0
• eliashaeussler/phpstan-config: ^2.0
• eliashaeussler/rector-config: ^3.0
• ergebnis/composer-normalize: ^2.30
• phpstan/extension-installer: ^1.2
• phpstan/phpstan-phpunit: ^1.1
• phpunit/phpunit: ^10.5 || ^11.4

GPL-3.0-or-later

• Elias Häußler

README

Object-oriented .gitattributes file handling

A PHP library to parse and dump .gitattributes file in an object-oriented way. The library provides a GitattributesDumper and GitattributesParser to either read or write contents to or from .gitattributes files. All attributes as of Git v2.46.0 according to the official documentation are supported.

🔥 Installation

composer require eliashaeussler/gitattributes

⚡ Usage

Parse rules from .gitattributes file

The main parsing functionality is provided by the GitattributesParser. It can be used as follows:

use EliasHaeussler\Gitattributes;

$parser = new Gitattributes\GitattributesParser(__DIR__);
$ruleset = $parser->parse('.gitattributes');

The returned ruleset contains the original filename as well as all parsed rules as instances of Rule\Rule. A rule contains the file pattern and a list of attributes:

foreach ($ruleset->rules() as $rule) {
    echo $rule->pattern()->toString().' ';

    foreach ($rule->attributes() as $attribute) {
        echo $attribute->toString().' ';
    }

    echo PHP_EOL;
}

Important

Only attribute names listed in the official documentation are supported by the library. Using other than the supported attributes will raise an exception. See Rule\Attribute\AttributeName for an overview.

Dump .gitattributes file from rules

It is also possible to create a new .gitattributes file by dumping a list of prepared rules. This functionality is provided by the GitattributesDumper:

use EliasHaeussler\Gitattributes;

$rules = [
    // You can create rules in an object-oriented way
    new Gitattributes\Rule\Rule(
        new Gitattributes\Rule\Pattern\FilePattern('/tests'),
        [
            Gitattributes\Rule\Attribute\Attribute::set(Gitattributes\Rule\Attribute\AttributeName::ExportIgnore),
        ],
    ),
    // ... or using a string input
    Gitattributes\Rule\Rule::fromString('/phpunit.xml export-ignore'),
];

$dumper = new Gitattributes\GitattributesDumper(__DIR__);
$result = $dumper->dump('.gitattributes', $rules);

Note

A file must not exist when dumping file contents. Otherwise, an exception is thrown.

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md.

⭐ License

This project is licensed under GNU General Public License 3.0 (or later).