Git Commit Tips & Best Practices

[Erin-Cecele]

What You Should Not Git Commit

If you’re using GitHub or a related service to manage your Quire projects, you should be mindful of how you handle third-party assets (like images you license for use), as well as files with large files sizes (like high-resolution images and even the PDF and e-book outputs from Quire itself). Neither should be committed into a git repository without some careful forethought.

One of the amazing things about git/GitHub is that a project tracked with git can be rolled back and fully restored to any point in its history. That means that git keeps track of every file that’s ever been associated with the project. This includes deleted files, which by design are never truly deleted. They're kept in version control in case you want to revert back to an older version that uses that file. Keep in mind that these deleted files can contribute to the overall size of your repository.

Third-Party Licensed Assets

If you plan to make your project repository visible at some point, we highly recommend not committing third-party licensed assets into it, as this can expose those assets to easy, unlicensed use by other people.

Getty makes many of our publication repositories public for those interested in the subject matter or how we use Quire. This also provides a public, detailed record of any changes made to the book after its publication date. Because the repositories are public, you’ll see in most cases, the images we’ve included in the books are not included in the repository. Instead, we put them in a secondary repository that always remains private but can be connected to the main repo through a git submodule.

This makes managing the repositories and deploying the site a little more complicated in some instances, but in general, it’s a good way of keeping all parts of the project in version control properly siloed as public and private while still connected.

Large Files

Individual large files (greater than 100MB) will be blocked by GitHub if you commit them into your project and then try to push them up. Also, multiple large files of even more modest size can quickly lead to bloated repository sizes and slowed performance.

Deleting committed files doesn’t clear up issues with GitHub or reduce the repo's overall size because these files remain in your git version history. You’ll find you need to jump through some technical hoops to remove the files and rewrite the git history permanently. It is best not to commit them in at all.

As a solution, when you are working with larger file sizes, we recommend utilizing GitHub's LFS (Large File Storage). This allows larger files to be stored in a separate location that can be linked to your repository.

If you are working on a larger project in GitHub, it’s a good idea to set up and start using LFS from the beginning. It will save you many headaches down the road. Read more about managing large files in GitHub’s docs.