Skip to content
ambientphantomPublic

About

Keep large binary assets out of Git — store them in GitHub Releases

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

Repository files navigation

assetout

English | Русский

Keep large binary assets out of Git.
Store them in a local mirror (.assetout/) and sync with GitHub Releases.

A simple alternative to Git LFS when you only need to keep big files out of the repository history and distribute them via Releases.

Features

  • Track large files outside Git (manifest + hashes)
  • Local mirror in .assetout/data/
  • Pack into zip archives and upload to GitHub Releases
  • Automatic split into multiple archives when over the size limit
  • Optional grouping by top-level project folder
  • Sync between project files and the mirror (remote / local / manual)
  • Automatic update of the release tag so Source code archives stay current
  • Wrappers: git-add, git-push

Requirements

  • Python 3.11+
  • Git repository with origin on GitHub
  • GitHub CLI (gh) — authenticated (gh auth login)

Install

Recommended (isolated CLI tool):

pipx install git+https://github.com/ambientphantom/assetout.git

Via pip:

pip install git+https://github.com/ambientphantom/assetout.git

Specific branch / tag:

# branch
pipx install git+https://github.com/ambientphantom/assetout.git@main

# tag
pipx install git+https://github.com/ambientphantom/assetout.git@v0.2.1

Upgrade:

pipx upgrade assetout
# or
pip install --upgrade git+https://github.com/ambientphantom/assetout.git

If the assetout command is not found:

python -m assetout --help

Quick start

# inside your git repo
assetout init

# register large files (copy into .assetout/data/, update manifest & .gitignore)
assetout add path/to/big/files_or_dirs

assetout status

# upload archives to GitHub Releases
assetout push

# on another machine / clean checkout
assetout pull
assetout sync          # mirror → project files

Commands

Command Description
init Create .assetout/ (config, manifest, data dir)
add Add large files to the mirror
rm Remove from manifest and mirror
status Show tracked files + release tag status relative to HEAD
push Pack mirror and upload to GitHub Releases (updates tag by default)
pull Download release archives into .assetout/data/
sync Sync between .assetout/data/ and project files
git-add assetout add then git add
git-push git push then assetout push

Useful flags

# push
assetout push --replace-all          # delete old assetout archives, then upload
assetout push --update-tag           # move tag to HEAD (default)
assetout push --no-update-tag        # delete + recreate release instead of moving tag

# sync / rm
assetout sync --policy local --force
assetout rm path/to/file --project   # also delete from working tree

How it works

project files  ←→  .assetout/data/  ←→  GitHub Release (zip archives)
     ↑ sync              ↑ push / pull
  • Files larger than max_git_file_size are kept out of Git
  • Manifest stores size + hash for each path
  • Archives are named binaries-01.zip, project-binaries-01.zip, …

Configuration

Created by assetout init at .assetout/config.yaml:

max_git_file_size: 10MB
hash_algorithm: xxh3
use_only_git_files: true
storage_backend: github_releases
sync_policy: remote          # remote | local | manual

packaging:
  group_by_top_level: false  # true → group by first folder name
  max_archive_size: 1900MB
  max_file_size: 2048MB

github:
  tag: assets-latest
  asset_name: binaries.zip   # legacy; names are generated automatically
  owner: ""                  # optional; taken from git remote if empty
  repo: ""

Typical workflow

# day-to-day
assetout git-add .
git commit -m "Update assets"
assetout git-push                # = git push + assetout push (with tag update)

# or explicitly
assetout add assets/
assetout push --replace-all

Updating the release tag

By default assetout push moves the configured tag (assets-latest) to the current HEAD and force-pushes it. This makes GitHub's automatic Source code archives contain the latest code.

assetout push                  # update tag (default)
assetout push --no-update-tag  # delete + recreate release instead

Use --no-update-tag if your team forbids force-pushing tags.

License

MIT

About

Keep large binary assets out of Git — store them in GitHub Releases

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages