Binary & Large Files

Overview

Copia is a Git-based distributed version control system. As such, any change to a binary file will be recognized by Git as a change to the entire file (versus a text file, which just stores the difference). This can increase the amount of data that needs to be stored, since the whole file needs to be replicated for each revision. Compounded by the fact that some files can be quite large, this issue can be taxing on disk space, causing slow performance during cloning, fetching, pulling, and other operations.

Copia has solved this problem by installing Git-LFS for customer usage and pre-configuring it for known filetypes.

Repositories created prior to August 2022 (or created based on a template repository before that time) are not automatically configured for Git-LFS. In addition, repositories migrated into Copia are not automatically configured for Git-LFS. These repositories must be migrated manually.

Git-LFS

When a file is tracked by Git LFS, your local machine stores it as a small pointer which references the large file. The large file is downloaded from Copia as-needed when you check out different branches, improving performance and minimizing local repo size. From a user standpoint, this is all done "behind the scenes", so you shouldn't notice any difference in usage.

File renames are discouraged when using Git-LFS as they will be considered a removal of one file and an addition of a new file in its place.

When you create a new LFS-enabled repository, Copia automatically adds a .gitattributes file to the repository. This file configures common file types to be stored as LFS. It also configures vendor-specific filetypes (such as Rockwell .acd files and Siemens .zap## files). A snippet of this file is provided below.

# Copia LFS defaults


## Generic

### *.xml
*.[xX][mM][lL] filter=lfs diff=lfs merge=lfs -text

### *.zip
*.[zZ][iI][pP] filter=lfs diff=lfs merge=lfs -text


## Rockwell: Studio 5000/Logix Designer

### *.acd
*.[aA][cC][dD] filter=lfs diff=lfs merge=lfs -text

### *.l5k
*.[lL]5[kK] filter=lfs diff=lfs merge=lfs -text

### *.l5x
*.[lL]5[xX] filter=lfs diff=lfs merge=lfs -text


## Siemens: TIA

### *.zal14
*.[zZ][aA][lL]14 filter=lfs diff=lfs merge=lfs -text

Tracking Existing Repository Files with LFS

If you start using LFS at the beginning of a repository's history, no further action is needed. But if you already have a repository with large files that aren't in LFS, you may want to start using LFS. Two common scenarios are:

1. Your repository was not using LFS at all, and you want to start using it.

2. Your repository was already using LFS, but you want to start tracking additional file types with LFS, as in Tracking New File Types in Git LFS.

In either case, the steps are similar:

1. Merge all outstanding PRs and branches into the main branch of your repository in the Copia Web App. If you are unable to complete this step, you are likely to run into cross-branch issues.

2. If your repository was not using LFS at all, commit a .gitattributes file to the main branch of your repository - reach out to Copia Support for assistance creating this file.

   • If your repository is already using LFS, follow the steps in Tracking New File Types in Git LFS and commit the resulting .gitattributes file.

3. At this point, the main branch of your repository should have a .gitattributes file with the file types you wish to track in LFS, and you should have no unmerged branches.

If your main branch has branch protections set up, you will need to perform the following steps in a separate branch, and use a PR to merge that branch into your main branch.

4. In the Command Line, run git add --renormalize . . Note the . at the end of the command. This ensures LFS is tracking all of the files you want to start tracking.

5. In the Command Line, run git commit -m "Start tracking files in LFS". Any commits or branches made after this commit will track files in LFS.

6. Push your change to Copia. Since all branches are merged at this point, users should delete their local branches, then pull main, at which point they can then create new branches which will use LFS.

Tracking New File Types in Git LFS

To configure Git-LFS for a new filetype that is not already tracked by Git-LFS, you must add an entry in the .gitattributes file in your repository. If you don't want to edit the file by hand, the Git CLI provides an easy way to do this:

git lfs track "*.xyz"
git lfs track "*.XYZ"

If any files matching that extension are already in the repo, you should be sure to follow the steps in Tracking New File Types in Git LFS to avoid running into issues.

Copia is case-sensitive. When adding a file type to your .gitattributes file, it is recommended to add it directly, using an existing and example line item, to cover all cases.

Migrating

When Git-LFS is involved, migration involves either of the following processes:

• migrating a repository which is not previously Git-LFS enabled

• migrating a repository from another vendor to Copia that is already configured for Git-LFS

We recommend you contact Copia for assistance while we continue to add additional documentation, guidance, and features surrounding these use-cases.

Offline Access

Git-LFS stores older versions of the file as pointers instead of the entire file itself. Because of this, you can't always access check out older commits if you don't have an internet connection. Prior to using your Git-LFS repository without an internet connection, you can cache all of the LFS items locally by running the following command from the Git-CLI while an internet connection is still established:

git lfs fetch --all