Skip to main content
One migration commit replaces the current LFS pointers with gat.lock metadata. Old commits remain unchanged and may still require Git LFS and its storage. See Gat’s file lifecycle for how new versions are recorded and published.

​
Before you start

Start from a and restore the real file contents:
Do not add LFS pointer files to Gat. If a file starts with version https://git-lfs.github.com/spec/v1, restore the real LFS object first.
Initialize Gat and configure storage. Replace the example bucket and region, and set provider credentials:

​
Migrate the files

This example moves models/encoder.bin and models/decoder.bin. Substitute your paths. For a partial migration, preserve LFS rules for files that stay in LFS.
1

Remove the matching LFS rule

Replace models/** with the rule you intend to remove. Preserve unrelated attributes, and narrow broader rules if other files still need them.
2

Remove only Git's index entries

Keep --cached: plain git rm can delete the working files you need to migrate.
3

Track the bytes with Gat

Confirm the files remain on disk and both paths appear in Gat’s listing.
4

Review and commit the metadata

Git shows the original paths as deleted; their versions are now recorded in gat.lock.
5

Publish the bytes, then the branch

Confirm the required objects are present before publishing the branch. --path . overrides any configured default selection.

​
Validate from a fresh clone

Replace the repository URL:
Open the restored files and confirm their contents before merging the migration branch. No history rewrite or force-push is needed.

​
Roll out to the team

After the migration branch is merged, existing clones run:
Files may briefly disappear while Git removes the old tracked paths. Gat restores those recorded in the new lock. Keep Git LFS and its old storage for historical revisions. Migrate any git lfs lock workflow separately; Gat does not replace it.

​
Troubleshooting

git lfs untrack changes attributes, not the index. Run git rm --cached -- PATH, then gat add PATH for each migrating file. Avoid removing an entire directory from the index unless every file is moving.
Recover the real bytes from the pre-migration revision or a clean LFS checkout. Run git lfs pull there before copying the files into the migration checkout and repeating gat add.
That is expected for a partial migration. Inspect git lfs track and git lfs ls-files; remove only rules for paths Gat should own.
That command can rewrite history and turn LFS content into ordinary Git blobs. It is not required here. If the rewrite was unintended, use your original branch or backup before starting this migration.
If the branch is unmerged, preserve needed local work and return to the original branch. Earlier commits still use LFS. Keep its client and storage available to restore those revisions.

Storage troubleshooting

Credentials, endpoints, and connection failures.

Missing files or conflicts

Restore files, preserve edits, or repair cached objects.