Got a huge pile of changes that a single push would choke on? CommitRocket splits them into size-limited batches, commits each batch, and pushes as it goes, with live progress.
CommitRocket is a command-line tool: you install it and run commitrocket. It is not a
Python library and has no Python API to import.
Pushing a lot of data in one go tends to go wrong. A single commit with gigabytes of videos, datasets, archives or generated assets can time out halfway, be rejected for containing a file over your host's limit (GitHub refuses anything over 100 MiB), or leave you with nothing pushed after hours of waiting. CommitRocket turns that one fragile push into many small ones: each batch is committed and uploaded on its own, so progress is saved as you go, a failure costs you one batch instead of everything, and you can always see how far along you are.
It is a good fit for:
- First uploads of big folders: course material, media libraries, backups, game assets, data dumps, or a repository you are migrating.
- Slow or unreliable connections, where small pushes that can be retried beat one huge one.
- Repositories with a few very large files, which it can store with Git LFS for you without leaving LFS configuration behind.
- Unattended runs: scheduled jobs and CI, with a JSON report and notifications.
- Size-based batching: choose how big each commit is, how files are picked (in order, or packed tightly), and the largest single file you will accept. Anything too large is skipped and listed at the end instead of failing the run.
- Live progress with elapsed time and an ETA based on how fast your upload really is.
- Safe with large files: files over the 100 MiB host limit are detected before anything
is committed. With
--use-lfsthey go through Git LFS, installed and removed again for you. - Recovers from trouble: failed pushes are retried, every push is checked against the remote, and if a run is interrupted (even with Ctrl+C) you just run the same command to carry on from where it stopped.
- Under your control: preview everything with
--dry-run, pick files with.gitignore-style patterns, choose the remote and branch, commit without pushing, and shape the commit messages with a template. - Easy to automate: save your options in a config file, read results from a JSON
report, get a desktop or webhook notification when a long run ends, and check your setup
with
commitrocket doctor. - Leaves a trail: every run writes a log file you can attach to a bug report.
It runs on Windows, macOS and Linux and talks to your remote through plain Git, so it works with any host you can already push to. It never changes your global Git configuration: temporary settings live in the repository and are restored afterwards.
pip install commitrocket
Requires Python 3.11 or later and Git. Because it is a program rather than a library, pipx and uv are a good fit too, and keep it out of your project environments:
pipx install commitrocket
uv tool install commitrocket
Check the install with commitrocket --version. Git LFS is optional: only --use-lfs
needs it, and CommitRocket offers to install it when it is missing.
commitrocket --repo path/to/repo --message "Add assets"
Each batch is committed as Add assets #1, Add assets #2, and so on, and pushed
right away.
Before it starts, CommitRocket checks that you are on a branch with an upstream and have nothing staged, then asks for confirmation.
The options you will use most:
| Option | What it does |
|---|---|
--message |
Commit message used for every batch (required, here or in a config file) |
--resume |
Continue the interrupted run in this repository with the parameters it started with (see Interrupted or failed runs) |
--limit-mib |
Target size of each batch in MiB (default 100) |
--dry-run |
Show the planned batches and commit messages without changing anything |
--include / --exclude |
Only handle / leave alone files matching a pattern (repeatable) |
--use-lfs |
Store files over 100 MiB with Git LFS for this run (see "Large files with Git LFS") |
--no-push |
Commit every batch but don't push them |
--force |
Skip the confirmation prompt |
There is also commitrocket doctor, which checks Git, git-lfs, your config and the remote without changing anything
(see doctor).
Run commitrocket --help or see the command line guide for every
option with its default and limits, and the exit codes.
Save your usual options so you don't have to retype them, in commitrocket.toml in the
repository folder or in the [tool.commitrocket] table of pyproject.toml:
# commitrocket.toml
message = "Videos"
use-lfs = true
limit-mib = 50
exclude = ["raw/", "*.tmp"]Options typed on the command line win over the file. A config file inside a repository is
not fully trusted, so it cannot turn on force, choose remote or branch, or set
report, log-file, notify-webhook or the pattern files; pass such a file yourself with
--config to use those. The configuration guide lists every
key and explains how files are found and trusted.
Everything else is in the command line guide:
- File patterns for
--includeand--exclude - Commit messages, templates and the attribution line
- Batch types
- Report and notifications for scripts and CI
- Logs and
commitrocket doctor - Examples, and settings in the configuration guide
Hosts like GitHub reject files over 100 MiB. With --use-lfs, CommitRocket stores those
files with Git LFS instead: it installs git-lfs if it is missing (asking first, unless
--force), commits one rule per file type to .gitattributes so clones get the real
files, pushes your files as usual, and removes its local LFS setup when it finishes, even
if the run fails. Without --use-lfs, a file over 100 MiB stops the run before anything is
committed. See Using Git LFS for the threshold, the
rules commit, thread settings and what happens after a failed run.
If a run stops, whether it failed or you pressed Ctrl+C, CommitRocket remembers it in a small
file inside .git, so it is never committed. Carry on with the same command, or let it reuse
the settings the run started with:
commitrocket --repo . --resume
Commits that were made but not pushed are pushed first, the files the run had staged are
committed with their original message, and numbering continues where it stopped. Repeating a
setting with --resume is fine as long as the value is the same; to change settings, run
without --resume and a new run starts. See
Interrupted runs for the details and the cases where
--resume refuses to continue.
After every push CommitRocket confirms that the remote branch now points at your latest commit, and stops with an error if it does not. With LFS, it also confirms right after each commit that the large files really were turned into LFS pointers, before uploading them, so a misconfiguration is caught before a doomed upload.
If an earlier run left local commits that contain files over 100 MiB, GitHub will keep rejecting them. CommitRocket detects this at the start, changes nothing, and shows the command to drop those commits while keeping your files:
git reset --mixed origin/main
Then run the same CommitRocket command again.
For help, see SUPPORT.md. Contributions are welcome. Start with CONTRIBUTING.md and follow the Code of Conduct. To report a vulnerability, please read SECURITY.md first and do not open a public issue. The guides and technical notes are listed in docs/README.md.
See LICENSE. CommitRocket depends on Rich (MIT) and pathspec (MPL-2.0). Git and Git LFS are separate programs with their own licenses and are never bundled.