Skip to content

Latest commit

 

History

History
140 lines (89 loc) · 5.38 KB

26_git_lfs.md

File metadata and controls

140 lines (89 loc) · 5.38 KB

Git LFS (Large File Storage)

While Git is a great version control system when used for non-binary files, it can sometimes struggle with binary files. One of the best ways to store binary files with the rest of your repository files is by using Git Large File Storage (LFS). Git LFS replaces large files such as audio samples, videos, datasets, and graphics with a SHA-256 hash pointer known as OID, short for Object ID inside Git, while storing the file contents on a remote server like GitHub.com or a GitHub Enterprise Server instance.

Note: The following activities utilize the githubschool/lfs-example repository, to follow along with the activities, you will need to Fork the repository to your account.

Background story

ACME Incorporated is planning on using Toggl for time tracking and are using this repository to provide information on how to use Toggl and download the desktop application that has passed the IT Security team's audit.

Unfortunately, the .dmg file was added to the Git repository without using Git LFS, and we need to fix that mistake. Perform the steps found in the upcoming sections to successfully retain the .dmg file in the project but utilizing Git LFS to maintain it in the project.

Activity: Install Git LFS

Before we can begin using Git LFS, we need to install it on our local machine. Below are the steps for installing Git LFS on your machine based on your operating system.

macOS

  1. Navigate to git-lfs.github.com and click Download. Alternatively, you can install Git LFS using a package manager:

    ?> If you install Git LFS with Homebrew or MacPorts, skip to step six.

  2. On your computer, locate and unzip the downloaded file.

  3. Open Terminal.

  4. Change the current working directory into the folder you downloaded and unzipped.

    cd ~/Downloads/git-lfs-1.X.X

    Note: The file path you use after cd depends on your operating system, Git LFS version you downloaded, and where you saved the Git LFS download.

  5. To install the file, run this command:

    ./install.sh

    Note: You may have to use sudo ./install.sh to install the file.

  6. Verify that the installation was successful:

    git lfs install

Windows

  1. Navigate to git-lfs.github.com and click Download.

    ?> For more information about alternative ways to install Git LFS for Windows, see this Getting started guide.

  2. On your computer, locate the downloaded file.

  3. Double-click on the file called git-lfs-windows-1.X.X.exe, where 1.X.X is replaced with the Git LFS version you downloaded. When you open this file Windows will run a setup wizard to install Git LFS.

    ?> When using Git LFS on Windows, ensure you have Git version 2.29.2.windows.2 or later.

  4. Open Git Bash.

  5. Verify that the installation was successful:

    git lfs install

Tracking files with Git LFS

Before we tell Git LFS what files to track, we should identify what files are taking up the most space in our repository.

Activity: Exploring the repository files

  1. Open your command line application.

  2. Change your current working directory to the lfs-example repository.

    cd lfs-example/

  3. List the file types taking up the most space in your repository:

    git lfs migrate info

    Your output should look similar to:

    migrate: Fetching remote refs: ..., done.
migrate: Sorting commits: ..., done.
migrate: Examining commits: 100% (0/0), done.

    By default, git lfs migrate info only displays files that don't exist within commits on the remote repository.

  4. Check for large files in every branch:

    git lfs migrate info --everything

    Your output should look similar to this:

    migrate: Sorting commits: ..., done.
migrate: Examining commits: 100% (8/8), done.
*.dmg 18 MB  1/1 files(s) 100%
*.md  6.4 KB 10/10 files(s) 100%
*.html 2.5 KB 4/4 files(s) 100%

    ?> If we only wanted to include files above a specific size, we could modify the previous command with --above=1mb

Now that we have identified the file that needs to be tracked with Git LFS it is time to import it into Git LFS and automatically fix the existing history of the project.

Activity: Migrating the file to Git LFS

  1. Convert all DMG files in every local branch:

    git lfs migrate import --everything --include="*.dmg"

    !> This is going to modify the history of the project to include the object that is now tracked in Git LFS.

    Note: You can also migrate files without modifying the existing history of your repository by passing an additional attribute --no-rewrite. For example:

    git lfs migrate import --no-rewrite test.zip *.mp3 *.psd

  2. Since we modified the local history of our project, we will need to force push our changes to the remote repository:

    !> This is going to rewrite the commit history of the project. Keep in mind all people working on the project should be made aware that this needs to occur.

    git push --force