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 Gramax Enterprise Server and the cloud, patterns can be set once at the space level, in the Space section of space settings — they apply to every catalog.

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

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

The .gitattributes file next to .doc-root.yaml defines which files are tracked by LFS. They should be listed as glob patterns. If the documentation lives in a subdirectory of the repository, the .gitattributes at the repository root is left untouched — for example, if it's maintained by hand for the project's code.

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

To skip picking masks by hand, turn on the Store new attachments in LFS toggle — then every new image, video, or file you add to an article goes into LFS automatically.

The Exclusions list below the toggle names file types that stay out of LFS even with auto-tracking on. By default it's *.svg, *.puml, *.yaml, *.mermaid, and *.html — you can edit the list.

If the catalog already has attachments not yet tracked by LFS, turning the toggle on offers to move them: Gramax shows their count and total size and moves them in a single service commit, without touching your edits or article text. Declining doesn't break anything — only new attachments start going into LFS. Turning the toggle off doesn't move anything back: whatever is already in LFS stays there.

A toggle turned on at the space level applies to every catalog at once — in each of them, the toggle on the Git LFS tab shows "on" and can't be edited until the space-level setting is turned off.

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: