pi-skill/skills/git-split-push/SKILL.md

name, description, argument-hint, license, metadata

name	description	argument-hint	license	metadata
git-split-push	Split large git pushes into smaller batches when pushing to Gitea/GitHub/GitLab fails with 'pack exceeds maximum allowed size' error. Detects size errors, groups files by size, commits and pushes in batches. No LFS required.	[git push error] [large files] [split push]	MIT	author version claudekit 1.0.0

Git Split Push

Split large git pushes into smaller batches when the server rejects them due to size limits.

When to Use

• git push fails with: "fatal: the remote end hung up unexpectedly"
• git push fails with: "pack exceeds maximum allowed size"
• git push fails with: "RPC failed; HTTP 413"
• Any push error mentioning size or pack limits

How It Works

1. Detects all untracked/staged/modified files
2. Calculates file sizes and groups into batches (default: 20MB each)
3. Commits each batch with a descriptive message: [split-push] Batch N/M
4. Pushes sequentially, small payloads each time
5. Reports success/failure for each batch

Usage

Quick Start

# Auto-detect and split push
python3 ~/.claude/skills/git-split-push/scripts/batch-push.py

# Use larger batches (30MB each)
python3 ~/.claude/skills/git-split-push/scripts/batch-push.py --max-size 30

# Check size first, don't push
python3 ~/.claude/skills/git-split-push/scripts/batch-push.py --check-size

# Preview what would happen
python3 ~/.claude/skills/git-split-push/scripts/batch-push.py --dry-run

Command Options

Option	Description
--max-size N	Max MB per batch (default: 20)
--dry-run	Preview batches without pushing
--check-size	Show size analysis and exit
--untracked-only	Only push untracked files
--verbose	Show detailed output (default: on)

Workflow

When You Get a Push Error

1. Don't panic — the skill will fix it
2. Run the script — it handles everything automatically
3. Check the output — each batch shows success/fail status
4. Done — all files are pushed in smaller chunks

Example Session

$ git push
Enumerating objects: done.
Counting objects: 100%
Delta compression using up to 8 threads.
Compressing objects: done.
fatal: the remote end hung up unexpectedly
pack exceeds maximum allowed size

$ python3 ~/.claude/skills/git-split-push/scripts/batch-push.py

🚀 Starting split push (5 batches, max 20 MB each):

📦 Batch 1/5: 18.5 MB (23 files)
   ✅ Pushed batch 1
📦 Batch 2/5: 19.2 MB (31 files)
   ✅ Pushed batch 2
📦 Batch 3/5: 20.1 MB (28 files)
   ✅ Pushed batch 3
📦 Batch 4/5: 17.8 MB (19 files)
   ✅ Pushed batch 4
📦 Batch 5/5: 15.3 MB (15 files)
   ✅ Pushed batch 5

============================================================
Git Split Push — Summary
============================================================

Total files to push: 116
Total size: 91.2 MB
Batch size limit: 20 MB
Batches created: 5
Batches failed: 0

✅ All batches pushed successfully!

Handling Oversized Files

If a single file exceeds the batch limit (e.g., a 100MB video):

⚠️  Batch 3 SKIPPED (file too large)
   - video.mp4 (105.3 MB)

💡 To push this file, either:
   1. Split the file manually: split --bytes=40M large.zip
   2. Remove it from git tracking
   3. Use Git LFS (requires server support)

Options for oversized files:

1. Split the file (if it's a zip/ archive):

   split --bytes=40M large.zip part-
   git add part-*
   git commit -m "Split archive"
   

2. Compress first:

   tar -czf archive.tar.gz large-folder/
   git add archive.tar.gz
   

3. Use Git LFS (if server supports it):

   git lfs install
   git lfs track "*.mp4"
   git add .gitattributes video.mp4
   

4. Remove from git (if not needed):

   git rm --cached video.mp4
   echo "video.mp4" >> .gitignore
   

Technical Details

Batching Algorithm

1. Sort files by size (largest first)
2. Add files to current batch until reaching max size
3. If single file exceeds max, add it as a single-file batch (will be skipped)
4. Move to next batch when limit reached

Batch Size Selection

Server Limit	Recommended --max-size	Why
50 MB (Gitea default)	20 MB	50% safety margin
100 MB (GitHub)	40 MB	Leave room for git overhead
500 MB (GitHub LFS free)	100 MB	Only if needed

Safety Features

• Soft reset on push failure — doesn't lose work
• Per-batch commits — can cherry-pick if needed
• Size checking — prevents pushing obviously oversized files
• Dry run mode — preview before executing

Alias (Optional)

Add to your .bashrc or .zshrc for quick access:

alias git-split='python3 ~/.claude/skills/git-split-push/scripts/batch-push.py'

Then use:

git-split                    # Split push all changes
git-split --max-size 30      # Use 30MB batches
git-split --dry-run          # Preview first

Exit Codes

Code	Meaning
0	Success (all batches pushed or nothing to push)
1	Error (not a git repo, no branch, etc.)

Related Skills

• git-cleanup — Clean up large files from git history
• git-lfs — Git LFS setup for binary files