git-lfs

Initialize Git LFS

$ git lfs install

$ git lfs track '[*.bin]'

$ git config [[-f|--file]] .lfsconfig lfs.url [lfs_endpoint_url]

$ git lfs track

$ git lfs ls-files

$ git lfs push --all [remote_name] [branch_name]

$ git lfs fetch

$ git lfs checkout

git lfs [options] [arguments]

install
    Sets up Git LFS by installing Git hooks (e.g., `pre-push`, `post-checkout`, `post-merge`) that manage LFS pointers and files. It's usually the first command you run once per user account on a machine to enable LFS functionality.

track [...]
    Tells Git LFS to track files matching one or more specified patterns (e.g., `*.psd`, `*.zip`). This command adds or updates entries in your `.gitattributes` file, indicating that these files should be stored via LFS when committed.

untrack [...]
    Stops Git LFS from tracking files matching one or more patterns. This removes the corresponding entries from `.gitattributes`. Note that this does not remove the actual large files from LFS storage if they were already committed.

status
    Shows which files are currently being tracked by Git LFS in your working directory and staging area, along with their LFS status (e.g., whether they are clean or modified).

ls []
    Lists LFS files in a given Git revision (defaulting to `HEAD`). It displays the file path, their size, and their OID (Object ID) in the LFS store.

migrate
    Provides powerful subcommands (e.g., `import`, `export`, `info`) to rewrite Git history. This allows converting existing large files in standard Git commits to LFS pointers, or vice-versa. Use with caution as it alters repository history and should be done carefully, ideally on a fresh clone.

pull [] []
    Downloads Git LFS files for the specified Git ref or the current branch. Normally, LFS files are pulled automatically by standard Git commands like `git clone` or `git checkout`.

push [] []
    Uploads Git LFS objects to the remote LFS store for the specified Git ref or the current branch. This is typically triggered automatically during a `git push` operation.

config
    Prints Git LFS configuration settings. This can include settings from `.git/config`, global Git configuration, or environment variables, useful for debugging LFS behavior.

env
    Displays detailed information about the Git LFS environment, including version, Git configuration, OS details, and LFS server URLs. This command is valuable for diagnostics.

version
    Prints the installed version of Git LFS.

git-lfs (Git Large File Storage) is an open-source Git extension that allows Git to handle large files more efficiently.

Traditional Git is optimized for text-based code and struggles with large binary files (e.g., videos, audio, graphics, datasets) because it stores every version of every file directly in the repository's history. This often leads to slow clones, bloats the repository size, and makes operations like fetching and checking out branches sluggish.

git-lfs addresses this by replacing large files in your Git repository with small text pointers. The actual file contents are stored on a remote LFS server (which can be hosted alongside your Git repository, e.g., GitHub, GitLab, Bitbucket). When you clone a repository or check out a specific branch, Git LFS transparently downloads only the specific versions of the large files needed for your current checkout.

This mechanism keeps the Git repository lean and fast, while still allowing developers to manage large assets within their familiar Git workflow, preserving Git's version control benefits.

When using git-lfs, be aware of the following considerations:

Server Dependency: git-lfs requires a compatible LFS server to store the actual file content. Most major Git hosting services (GitHub, GitLab, Bitbucket) provide built-in LFS support.

Migration Complexity: Using `git lfs migrate` to rewrite history can be complex and potentially destructive if not handled carefully. Always back up your repository before performing history rewrites, and ensure all collaborators are aware of the changes.

Storage and Bandwidth Limits: LFS storage and bandwidth are often subject to limits and potential costs on hosting platforms, especially for large projects or high usage.

Atomic Pushes: For a successful `git push`, the Git LFS objects must be successfully uploaded to the LFS server before the corresponding Git commit (which contains the LFS pointer) can be pushed to the Git remote. If the LFS upload fails, the Git push will also fail.

The common workflow for incorporating git-lfs into your project is as follows:

1. Install LFS: Run `git lfs install` once per user account on your machine. This sets up necessary Git hooks.

2. Track Files: In your repository, use `git lfs track "*.ext"` (e.g., `git lfs track "*.psd"`) for each type of large file you want LFS to manage. This command adds an entry to your `.gitattributes` file.

3. Stage & Commit: Add your large files using `git add ` and `git commit -m "Commit message"` as usual. Git LFS automatically replaces the actual file content with a pointer file during the staging process.

4. Push: When you run `git push`, Git LFS automatically uploads the actual file contents to the configured LFS server, and then pushes the lightweight pointer files to the Git remote.

git-lfs primarily relies on Git's `.gitattributes` file to specify which files are managed by LFS. An entry like `*.psd filter=lfs diff=lfs merge=lfs -text` tells Git to use the LFS filter for `.psd` files, ensuring they are handled by LFS.

Further global or repository-specific configuration can be done via `git config` commands, typically under the `lfs` namespace (e.g., `git config lfs.url https://mylfs.server.com`). Environment variables can also influence LFS behavior.

git-lfs was initially developed by GitHub and first publicly released in 2015. It was created to address the growing problem of managing large binary files within Git repositories, a task for which Git was not originally designed. Prior to its existence, developers often resorted to separate file storage solutions, leading to fragmented workflows, or suffered from repository bloat and slow operations. Since its release, git-lfs has been widely adopted across the software development industry and has become the de facto standard for large file management in Git, continually evolving with new features and performance improvements to support diverse use cases.

git(1), git-clone(1), git-config(1), git-add(1), git-commit(1), git-push(1), gitattributes(5)