The Ultimate Guide to Git LFS 🚀

(Git Large File Storage)

Welcome to the Git LFS guide! If you already know the basics of Git and GitHub, you are fully ready to learn this tool. This file is designed to be your permanent, comprehensive reference for understanding and managing large files in your repositories.

🧐 What is Git LFS? And why do we need it?

Standard Git is perfectly designed for handling "code" (text files), as it tracks changes line by line. However, when it comes to Large Binary Files such as:

• Videos (.mp4, .mov)
• High-resolution images or design files (.psd, large .png)
• Database files (.sqlite)
• 3D models or game assets (.obj, .fbx)
• Compressed archives (.zip, .iso)

Git becomes extremely slow, and the repository size balloons terrifyingly with every commit. This happens because Git saves a full copy of the binary file every time it is modified.

💡 The Solution: Git LFS Git LFS solves this problem cleverly. Instead of storing the massive file itself inside the Git repository, LFS stores a tiny "Pointer File" (just a few bytes) containing metadata about the original file. The actual large file is uploaded to a specialized LFS server. When anyone clones, checks out, or pulls the repository, LFS automatically reads this "pointer" and downloads the real file from the server in the background.

💻 How to Install Git LFS

Before using it, you need to install the Git LFS extension on your computer.

• Windows: Download the installer from the Git LFS website or install via winget: winget install GitHub.GitLFS
• macOS: Use Homebrew: brew install git-lfs
• Linux (Ubuntu/Debian): sudo apt-get install git-lfs

🛠️ Step-by-Step Setup and Workflow (For Beginners)

To start using Git LFS in any project, follow these exact steps:

1. Initialize LFS on your machine (Do this only once)

Open your terminal and run the following command to set up LFS for your user account:

git lfs install

(Note: You only need to run this command once per computer, not every time you create a new project).

2. Track the large files

Navigate to your project folder. Let's say you want LFS to handle all .iso image files in your project. Run:

git lfs track "*.iso"

⚠️ CRITICAL NOTE: The quotes " around the file extension are extremely important. They ensure the rule applies to all current and future files in all directories.

3. Save the .gitattributes file (Do NOT skip this!)

When you run the track command, Git LFS creates or updates a hidden file called .gitattributes. This file tells Git to hand over these specific files to LFS. You must add and commit this file.

git add .gitattributes
git commit -m "Add Git LFS tracking for .iso files"

4. Work normally (Add, Commit, Push)

Now, you can add your large files, commit, and push exactly like you normally do in Git:

git add file.iso
git commit -m "Add large disk image"
git push

Git LFS will automatically intercept the push in the background, uploading the large file to the LFS server and pushing the pointer file/code to GitHub.

📥 Cloning and Pulling an LFS Repository

If you or a teammate want to download a project that uses Git LFS:

1. Clone normally:

   git clone <repository-url>

   If git lfs install was previously run on your machine, Git will automatically download the real LFS files during the clone.

2. If files show up as tiny text files (pointers) instead of the real files: Simply run this to force download the actual large files:

   git lfs pull

📚 Git LFS Command Reference (Cheat Sheet)

High-level (Porcelain) commands, categorized for easy reference:

🎯 1. Tracking & Status

• git lfs track: View or add file extensions/paths managed by LFS (e.g., git lfs track "*.mp4").
• git lfs untrack: Stop tracking a specific extension (e.g., git lfs untrack "*.mp4").
• git lfs ls-files: Show a list of all LFS-managed files currently in your index and working tree.
• git lfs status: Show the status of LFS files in your working tree (useful to see what's modified but not pushed).

🔄 2. Syncing & Downloading

• git lfs fetch: Download LFS files from the server to your local machine (does not update your working directory).
• git lfs checkout: Populate your working directory with real file content based on the existing pointer files.
• git lfs pull: Combines fetch and checkout; downloads updates from the remote and replaces pointers with real files.
• git lfs push: Push queued large files to the Git LFS endpoint.

🔒 3. File Locking (For Team Collaboration)

Since large binary files (like .psd Photoshop files) cannot be merged like code, LFS offers "locking" to prevent conflicts:

• git lfs lock <file>: Lock a file on the server (under your name) so no one else can edit and push it simultaneously.
• git lfs unlock <file>: Remove the lock after you are done editing.
• git lfs locks: List all currently locked files on the server and who locked them.

🧹 4. Maintenance & Storage

• git lfs prune: Delete old, unneeded LFS files from your local storage to free up disk space.
• git lfs dedup: De-duplicate Git LFS files locally to save space.
• git lfs migrate: A powerful tool used to rewrite Git history. Use this if you accidentally committed large files to standard Git and want to convert them to LFS retroactively (or vice versa).
• git lfs fsck: Check Git LFS files for internal consistency and errors.

⚙️ 5. Advanced Setup & Environment

• git lfs env: Display the current LFS environment and settings (great for debugging).
• git lfs update: Update Git LFS hooks for the current repository.
• git lfs logs: Show errors from previous LFS commands.
• git lfs uninstall: Remove LFS hooks and filters from your machine.
• git lfs version: Check the installed LFS version.
• git lfs ext: Display Git LFS extension details.
• git lfs completion: Generate shell scripts for command-line tab-completion.

🔧 Plumbing Commands (Low-level / Advanced)

These commands work "behind the scenes". You will rarely need to use them manually:

• git lfs clean: The filter that converts large files to pointers before saving to Git.
• git lfs smudge: The filter that converts pointers back to actual files during checkout.
• Hooks (post-checkout, post-commit, post-merge, pre-push): Scripts that trigger LFS operations automatically during standard Git events.
• git lfs pointer: Build and compare pointer files.
• git lfs filter-process: Converts between large files and pointers efficiently.
• git lfs merge-driver: Attempts to merge text-based LFS files.
• git lfs standalone-file: Custom transfer adapter for local file paths.

💡 The Golden Rule of Git LFS

Always make sure to track files (git lfs track "*.ext") BEFORE you git add them.

If you accidentally git add and git commit a large file into standard Git before setting up tracking, it will get stuck in your Git history and bloat your repo forever, even if you track it later. (If this happens, you will need to research and use the git lfs migrate command to fix your history).