Git LFS

Git LFS (Large File Storage) is a Git extension that allows storing binary files (images, PDF, Word, or Excel documents) separately from the repository. These files are uploaded to the S3 storage provided by your Git service. This helps speed up cloning and synchronization and reduces repository size.

Enable LFS

The catalog must be published in one of the supported Git storage services first:

LFS patterns are configured differently depending on the space type:

  • In a Gramax Enterprise Server space, patterns can be set once at the space level — the settings apply to all repositories.

  • In a regular space, LFS is configured separately for each catalog in the Git LFS tab in Catalog Settings.

You can either add patterns manually or use auto-configuration, which adds commonly used file types to the list.

The .gitattributes file in the repository root defines which files are tracked by LFS. They should be listed as glob patterns.

When you save settings, selected patterns are written to this file with the filter=lfs attribute — this is the marker used by Git LFS. If needed, you can edit this file manually to add custom attributes.

*.png filter=lfs
*.pdf filter=lfs
*.docx filter=lfs
*.xlsx filter=lfs
*.pptx filter=lfs

After that, the selected files will be tracked and marked with an LFS badge in the changes view.

Git storage services also display such files differently. For example, this is how it looks in GitLab.

Lazy Resource Loading

By default, the editor app does not download LFS objects during repository cloning. Instead, they are fetched when you open an article. This reduces clone time and local repository size.

If needed, you can enable automatic downloading of all LFS objects for the current revision in Catalog actions → Tools → Automatic LFS download. The first sync may take significant time in large repositories.

Migrate Existing Catalog Resources to LFS

In long-lived catalogs, enabling LFS alone does not solve repository size issues. Older resources remain in repository history.

To migrate them, you can use git-lfs. This is a destructive action that rewrites the entire repository history. Creating a backup beforehand is strongly recommended.

# Install git-lfs
git lfs install

# Fetch all branches; otherwise only existing local branches are rewritten
git fetch --all

# Calculate and show total size of files grouped by type
git lfs migrate info --everything --pointers=ignore

# You can specify your own file types
git lfs migrate import --everything --include "*.png,*.mp4,*.gif"

# Push changes and rewrite history for all refs
git push --force --all

Known Limitations

The application does not use the original git-lfs extension. It partially implements the specification.

Not implemented: