git-lfs-transfer

Upload large files tracked by Git LFS to a repository

$ git-lfs-transfer [path/to/repo.git] upload

$ git-lfs-transfer [path/to/repo.git] download

git lfs transfer <direction> [<options>]

<direction> can be 'download' or 'upload'.

<direction>
    Specifies the direction of the transfer. Can be download to retrieve LFS objects or upload to send LFS objects to the server. This is a positional argument.

--concurrency=<n>
    Sets the number of parallel transfers to run simultaneously. Defaults to a configured value (e.g., 3), optimizing for network and server load.

--dry-run
    Performs a 'dry run' of the transfer, showing which objects would be processed without actually moving any data. Useful for previewing operations.

--epoch-time
    Uses Unix epoch time for timestamps in transfer logs, which can be useful for consistent logging and parsing across different systems.

--force-download
    Forces the download of LFS objects, even if they appear to exist locally. This can be useful for repairing corrupted local objects or ensuring a fresh copy.

--force-url=<url>
    Overrides the configured Git LFS URL for the current transfer operation, allowing a specific server to be targeted instead of the default.

--hash-algo=<algo>
    Specifies the hash algorithm used for identifying LFS objects. Defaults to sha256, which is the standard for Git LFS.

--log-upload-only
    Restricts transfer logs to only include information about upload attempts, making it easier to debug issues specifically related to pushing LFS objects.

--object-id=<oid>
    Transfers only the LFS object identified by the given Object ID (OID), rather than a set of objects determined by the repository state. For advanced use cases.

--remote=<remote>
    Specifies the Git remote name (e.g., origin) to use for determining the LFS server configuration. If not specified, the default remote is used.

--transfer-adapter=<name>
    Allows specifying a custom transfer adapter by name. Defaults to the basic HTTP adapter, but others can be configured for different protocols or optimizations.

--upload-only
    Limits the transfer operation to only consider objects that need to be uploaded, ignoring any objects that might need downloading during a bidirectional sync.

--verbose
    Enables verbose output during the transfer process, providing more detailed information about progress, errors, and internal workings.

The git-lfs-transfer command is an internal component of Git LFS, primarily used by Git LFS clients and servers to manage the upload and download of large files (LFS objects). It facilitates the communication between a Git LFS client and a Git LFS server, typically over HTTP, to move the actual file content outside of the core Git repository. Users generally do not invoke this command directly; instead, it is automatically called by higher-level Git LFS commands like git lfs push or git lfs pull to perform the necessary data transfers. Its role is to handle the low-level details of object identification, request generation, and data streaming.

git-lfs-transfer is an internal command of Git LFS. It is generally not intended for direct user invocation. Misusing this command directly can lead to unexpected behavior, incomplete transfers, or corrupted Git LFS state. It is best left to be called automatically by higher-level Git LFS commands like git lfs pull or git lfs push, which handle the context and object selection correctly.

This command acts as the low-level workhorse for Git LFS operations that involve moving large file data. When you run git lfs push or git lfs pull, the Git LFS client constructs appropriate git-lfs-transfer commands with specific directions and options to perform the actual data exchange with the configured LFS server, often using standard HTTP/HTTPS protocols.

While the default transfer adapter uses basic HTTP, Git LFS supports custom transfer adapters. These adapters can be configured to use different protocols or mechanisms for file transfer, allowing for integration with various storage backends (e.g., S3, Google Cloud Storage) or optimized transfer methods. The --transfer-adapter option allows specifying which adapter to use for a particular operation, providing flexibility in how LFS objects are stored and retrieved.

Git LFS identifies large files by their content hash, not by their filename. This content hash (OID, Object ID) is typically a SHA-256 sum of the file's content. The git-lfs-transfer command uses these OIDs to request and upload the correct file data, ensuring integrity and de-duplication across the LFS server.

Git LFS (Large File Storage) was developed by GitHub to address the challenge of managing large binary files within Git repositories, which are traditionally optimized for small text files. The git-lfs-transfer command is a foundational component of this system, designed to efficiently move large file content between local repositories and remote LFS servers. Its development is intertwined with the evolution of Git LFS itself, continuously refined to improve performance, reliability, and security of large file transfers through various iterations of the Git LFS specification.

git-lfs(1), git-lfs-pull(1), git-lfs-push(1), git-lfs-config(1), git(1)