GitHub gives developers an incredible amount of free functionality to use as they build on the platform. Storage of their code is one of many things developers likely take for granted on GitHub. However, not just anything can be stored in a repository on the platform.
GitHub has a few limitations on file and repository size that developers are forced to deal with. For projects that depend on particularly large files, understanding these limitations and the ways that they can be overcome can make a huge difference. This article will give you an idea of what can and cannot be stored in your repository on GitHub as well as what you can do to store more without breaking any rules or risking your project.
GitHub repository storage size limits
Repositories on GitHub are not limited to a strict maximum size, but developers are strongly encouraged to keep their own repositories under 5GB in size.
GitHub communicates with owners of repositories that border on being too large for their infrastructure to easily accommodate. Generally, anything over 1GB is likely to trigger a message from GitHub, encouraging repository owners to cut down on excess files and make changes that keep the repository from ballooning beyond that point.
Alternatives to repository size limits on GitHub
Repository size limits keep GitHub running smoothly, but they may also get in the way of your development plans. Thankfully, there are other ways to associate large files with your code on the platform.
GitHub releases are the platform's special means of offering versioned releases of software in a flexible fashion. Instead of storing all of the different versions of your software in your repository, you can simply specify a new release.
The way this all works comes down to Git tags and the information that they can contain. With tags, you can view all of the files within a given repository at a specific moment in time. These tags can be turned into releases in their own right, making it possible to specify an exact point of time at which your repository held the code for a distinct version of your software.
Releases benefit from a much higher included file size limit and absolutely no limit on the size of the release itself. Individual files included in the release can be as large as 2 GB. By leveraging the more permissive data limits associated with releases on GitHub, you can store far more than would be possible in your main repository. After all, by design, repositories managed with Git and GitHub are intended to be used for source control, not direct distribution. That's what makes releases so useful. Releases that you create can be associated first with a tag and then have any number of assets uploaded to them (bearing the 2GB individual file size limit mentioned above in mind).
GitHub individual file storage limits
Besides repository-wide size limitations, GitHub also imposes some constraints on the maximum sizes of individual files that are added to a repository. However, the maximum file size differs based on the access method by which you choose to interact with your repository. There are two distinct size restrictions—one for each access option:
When adding files to your repository from within your browser: GitHub sets the bar at 25MB for files contributed to a repository from within the browser-based interactive development environment (IDE).
When adding files to your repository from the command line: GitHub gives developers much more leeway when they make use of the command line to add new files to their repositories. Instead of a maximum file size of 25MB, developers can add files as large as 100MB.
Alternatives to individual file storage limits on GitHub
File storage limits can seriously hamper your development goals in many cases; it’s important to know what options are available to GitHub users to help them overcome such an obstacle.
Git Large File Storage or "LFS"
In 2015, GitHub announced its Large File Storage feature—a handy option for those looking to integrate all kinds of large files into their workflows without getting bogged down by the file size limitations inherent to their repositories.
The files themselves are merely referenced by pointers within Git, while they are actually stored elsewhere. Up to 1 GB of storage and monthly bandwidth is available for free to developers and more can be purchased as needed.
Get more out of GitHub with Mergify 🥰
Mergify can help make many tedious tasks on GitHub much easier to manage. Through powerful automation, Mergify can eliminate repetitive tasks like queueing up merges and assigning reviewers to pull requests from your daily schedule, allowing your team to focus on what matters most for your project. Learn more about Mergify today.