Policy for large files

Due to the inclusion of large files such as sample input data (especially solver meshes), reference data for unit testing, and some documentation, our old repository on Bitbucket grew to a size of approximately 1.5 GB over time. As a result, it took a long time just to clone a working copy. Therefore, in order to keep the new repository lean, large files are no longer allowed. We will continue to provide a number of example cases XGC1 and XGCa. But the example input data will be available for download in a separate Git repository (XGC-Examples) instead of the GitHub repository.

An automatic mechanism to help prevent the addition of large files to the new repo will be put in place. It will check commits in pull requests to verify that they do not add large files. In order to avoid running into trouble at that point, be vigilant while creating commits in the first place:

• Use git add -u habitually to add your changes to existing files for commit. This avoids accidentally adding other files.

• Use git add <new-file> explicitly only for new source files.

• Use git diff --cached --stat after adding changes to review the set of files before committing.

• After committing use git show --stat to review the set of files that changed in the commit.

• Use git log origin/master.. --stat to see a summary of all files changed in all commits that have not been merged.

If you do accidentally commit a large file (e.g. an executable built in the source tree) then it needs to be removed before the commit is merged. It is not enough to just remove the file and commit again. The large file must be removed from history as if it were never committed. Follow these instructions to rewrite history, typically via git commit --amend (for the most recent commit) or git rebase -i (for older commits). While editing the offending commit, use git rm to remove the file and amend the commit.