User guide

Manage large assets without Git LFS. Git stores chunks automatically while you work with full originals locally. No .NET SDK needed.

Install

Windows — Download the installer, or with Scoop:

scoop bucket add gitchunk https://github.com/MDJ0126/GitChunk.git
scoop install gitchunk/git-chunk

Mac — with Homebrew:

brew tap MDJ0126/gitchunk https://github.com/MDJ0126/GitChunk
brew install --cask MDJ0126/gitchunk/git-chunk

Linux x64 — Download the ZIP, extract it, then run sh install.sh in that folder. Ubuntu/Debian: sudo apt install git python3-tk. Open Git Chunk from the application menu. Add ~/.local/bin to PATH for git chunk. Requires glibc Linux; the .NET runtime is included.

Use

Run git chunk update at the repository root to download the latest release, verify its checksum, and apply it to that repository. Subsequent git chunk commands forward to the verified new executable. Apply it to other repositories with git chunk install. Use git chunk version to inspect the executable and version.

git chunk install applies the running version and reports a newer release when available. Versions without the updater require a one-time upgrade through the installer or package manager first. Unpublished local changes are not downloaded from public releases.

Run once in your project's Git repository root, including after cloning on a new PC:

git chunk install

For existing tracked files, apply and commit the configuration:

git add -u
git add --renormalize .
git add .gitattributes .gitignore .gitchunk
git commit -m "Configure Git Chunk"

Then use Git as usual. The app also supports setup: select your project and click Install Git Chunk.

Files over 50 MiB become chunks of up to 49 MiB by default. Add paths to the repository-root .chunkignore to store matching files whole, or edit the ignore list in the app. For example, Build/** excludes every file under Build from chunking. An empty ignore list excludes nothing. Do not delete .gitchunk/objects.

Git Chunk does not currently support RAID-style redundancy or parity-based recovery of missing or corrupted chunks. These recovery features are under consideration; implementation and timing have not been decided.

Convert an existing Git LFS project

The current release supports automatic LFS conversion. To run GitChunk.exe directly, stay in the target repository root and replace the install command below with the actual executable path followed by install.

1. In the target repository root, commit or stash tracked changes first. Downloading missing originals requires Git LFS and remote access.
2. Run the commands below. Installation obtains missing originals, verifies size and SHA-256, converts LFS attributes and standard hooks, verifies conversion/restoration, and stages the result.

git chunk install
git diff --cached
git commit -m "Convert current LFS files to Git Chunk"
git push

Current LFS files over 50 MiB become chunks; files at or below that size become ordinary Git files. Large LFS files excluded by .chunkignore or custom commit/push hooks stop conversion with instructions. Installation never commits or pushes automatically. Failed conversion restores the original index, settings and hooks.

After conversion, edit originals and use add/commit/push as usual. Adding files chunks them automatically; the commit hook includes required chunks. Pull/checkout restores originals automatically. On a new computer, clone and run git chunk install once.

Past commits and existing server LFS objects/storage usage are preserved. Keep Git LFS and the corresponding originals to use historical LFS versions.

To reclaim server LFS storage, first upload and verify the converted project. If you only need the latest version, back up the old repository and publish a new root commit containing the verified latest tree; this removes the old history from the published branch. Check every remote branch and tag for remaining LFS references before requesting deletion. A Git bundle backs up Git history, but does not contain LFS payloads; back those up separately if needed.

Save git lfs ls-files --all --long before removing the old history to obtain the historical object IDs and paths. This lists objects referenced by available Git history, not a server inventory or billing total. Submit the repository URLs, old object IDs and verified new commit IDs through GitHub Support. GitChunk does not delete remote LFS objects. GitHub documents that removed LFS objects continue to consume storage until purged.

LFS migration also converts existing large ordinary Git files and batches LFS pointer discovery. This covers mixed repositories containing both LFS resources and large build files.

Distribution details · Technical notes

.gitchunk/chunks.txt lists original paths (JSON strings) and ordered chunk IDs. Installation rebuilds it from existing indexed pointers; the commit hook refreshes and stages it from staged files, including renames and deletions. Restoration still uses the original pointers. Updates archive old presets under the Git metadata directory.

.chunkignore supports one pattern per line, # comments, *, **, ?, a leading / for root paths, and a trailing / for directory contents. Plain patterns exclude files from chunking; ! can re-enable a matching file (last match wins). This affects chunking only; excluded files are still tracked by Git. It does not implement every .gitignore syntax feature. Existing .gitchunk/rules.txt settings are converted while preserving their selection and backed up under Git metadata as gitchunk/rules-backup-*.txt; the old settings file is removed.

Uninstall from a repository

Run git chunk uninstall in the repository root, or choose Uninstall in the app. Commit or stash tracked changes first. The command verifies and converts current chunked files smaller than 100 MiB to ordinary Git files, removes managed filters/hooks and project configuration, and stages the result. It does not commit, push, remove global commands, or affect other repositories. Files of 100 MiB or more block removal before configuration is changed; move them to another storage method first. Custom hooks and unrelated attributes/settings are preserved. A local recovery backup is kept in Git metadata. Historical chunked commits still require reinstalling Git Chunk.