filters.rst

Filters

pygit2 supports defining and registering libgit2 blob filters implemented in Python.

The Filter type

.. autoclass:: pygit2.Filter
   :members:

.. autoclass:: pygit2.FilterSource

Registering filters

.. autofunction:: pygit2.filter_register

.. autofunction:: pygit2.filter_unregister

Example

The following example is a simple Python implementation of a filter which enforces that blobs are stored with unix LF line-endings in the ODB, and checked out with line-endings in accordance with the .gitattributes eol setting.

class CRLFFilter(pygit2.Filter):
    attributes = "text eol=*"

    def __init__(self):
        super().__init__()
        self.linesep = b'\r\n' if os.name == 'nt' else b'\n'
        self.buffer = io.BytesIO()

    def check(self, src, attr_values):
        if src.mode == pygit2.enums.FilterMode.SMUDGE:
            # attr_values contains the values of the 'text' and 'eol'
            # attributes in that order (as they are defined in
            # CRLFFilter.attributes
            eol = attr_values[1]

            if eol == 'crlf':
                self.linesep = b'\r\n'
            elif eol == 'lf':
                self.linesep = b'\n'
        else:  # src.mode == pygit2.enums.FilterMode.CLEAN
            # always use LF line-endings when writing to the ODB
            self.linesep = b'\n'

    def write(data, src, write_next):
        # buffer input data in case line-ending sequences span chunk boundaries
        self.buffer.write(data)

    def close(self, write_next):
        # apply line-ending conversion to our buffered input and write all
        # of our output data
        self.buffer.seek(0)
        write_next(self.linesep.join(self.buffer.read().splitlines()))