To ensure the optimal performance, stability, and reliability of our Git infrastructure, we are introducing a limit on the size of individual files that can be pushed to your project repositories.

Effective immediately, any git push operation containing one or more files larger than 100MB will be rejected.

This practice aligns with industry standards and helps prevent issues associated with oversized Git repositories.

Why this limit?

Git is designed for managing source code and text files, which are typically small. It’s not optimized for storing large binary assets like videos, high-resolution images, backups, or compiled artifacts. Committing large files directly into Git history can lead to:

1. Repository bloat: The entire history, including large files (even if later “deleted” without rewriting history), is cloned by every developer and deployment process, significantly increasing repository size.
2. Performance degradation: Cloning, fetching, and pushing become much slower for everyone working on the project.
3. Increased resource consumption: Larger repositories consume more disk space and network bandwidth on build/deploy servers and local machines.
4. Potential instability: Extremely large pushes can strain Git server resources.

Platforms like GitHub have similar restrictions (as detailed in their documentation on large files) for the same reasons. This limit helps maintain a healthy and efficient experience for all Upsun users on our API, Console and CLI.

What happens when you hit the limit?

If you attempt to push a commit containing a file exceeding the 100MB limit, the push operation will fail, and you will see an error message similar to this:

❯ git push origin HEAD:branch
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 20 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 103.78 KiB | 348.00 KiB/s, done.
Total 3 (delta 1), reused 0 (delta 0), pack-reused 0

You are attempting to check in one or more files which exceed the file size limit (100.0 MB):
File: ./linux.iso - Size: 104.0 MB - Commit: 2ef839759cac0cbda51b5f090e6ff9d775d584b7

error: remote unpack failed: push rejected
To git.ch-1.platform.sh:ptnmwvw4dhaavc.git
 ! [remote failure]  HEAD -> branch (remote failed to report status)
error: failed to push some refs to 'git.ch-1.platform.sh:ptnmwvw4dhaavc.git'

Preventing large files in your repository

The best approach is to avoid committing large files in the first place:

1. .gitignore: Ensure large files, build artifacts, logs, vendor directories, and local backups are listed in your .gitignore file before you commit them.
2. Alternative Storage: For large assets needed by your application (e.g., media files, datasets), consider using mounts.

Removing large files from existing history

If a large file has already been committed (even in past history), simply deleting it in a new commit is not enough. The large object still exists in the repository’s history. You need to rewrite the repository’s history to remove it completely.

Warning: Rewriting Git history is a destructive operation. It changes commit SHAs. Coordinate carefully with your team before proceeding, as everyone will need to re-clone or perform specific steps to update their local repositories. Always back up your repository before attempting history rewriting.

Two recommended tools for cleaning repository history are:

BFG Repo-Cleaner: Generally faster and simpler to use for common tasks like removing large files.

• Example command to remove files over 100MB:

# Make a fresh clone --bare
git clone --bare <PROJECT_URL>.git repo-backup
cd repo-backup

# Download bfg.jar (see BFG docs)
java -jar bfg.jar --strip-blobs-bigger-than 100M .

# Clean up Git's internal refs and optimize
git reflog expire --expire=now --all && git gc --prune=now --aggressive

# Push the rewritten history (FORCE PUSH REQUIRED)
git push --force

git filter-repo: The modern, recommended replacement for the older git filter-branch. It’s powerful and safer.

• Example command remove files over 100MB:

# Make a fresh clone (not bare this time)
git clone --bare <PROJECT_URL>.git repo-backup
cd repo-backup

# Run filter-repo
git filter-repo --strip-blobs-bigger-than 100M

git push --force

After cleaning the history and force-pushing, all team members will need to update their local copies, typically by deleting their old local repository and re-cloning the cleaned version from Upsun.

Conclusion

The 100MB file size limit helps ensure a smooth and efficient experience on Upsun. If you encounter the limit, use tools like BFG Repo-Cleaner or git filter-repo to clean your repository history, remembering to coordinate with your team due to the nature of history rewriting.

If you have any questions or need assistance, please contact us on our Discord server.