CLI Companion

  • Hugging Face CLI
    • login
    • whoami
    • repo create
    • upload
    • download
    • lfs-enable-largefiles
    • scan-cache
    • delete-cache
  • Hapi CLI
    • new
    • start
    • build
    • test
    • plugin create
    • route add
  • Cloudflared
    • tunnel
    • tunnel run
    • tunnel list
    • tunnel delete
    • access
    • access tcp
    • update

    The `huggingface-cli lfs-enable-largefiles` command is used to configure a local Git repository to work with Git Large File Storage (LFS) for handling large files when interacting with Hugging Face Hub repositories. This is particularly useful for models, datasets, and other artifacts that exceed Git's typical file size recommendations.

    Syntax

    bash
    huggingface-cli lfs-enable-largefiles [REPOSITORY_PATH]

    - `REPOSITORY_PATH`: (Optional) The path to the local Git repository you want to configure. If omitted, the command assumes the current directory is the root of the repository.

    Explanation

    When you clone a repository from the Hugging Face Hub that contains large files managed by Git LFS, or when you intend to push large files to a Hub repository, your local Git configuration needs to be aware of LFS. This command streamlines that setup.

    Specifically, `huggingface-cli lfs-enable-largefiles` performs the following actions:

    1. **Installs Git LFS hooks**: It ensures that the necessary Git LFS hooks (e.g., `pre-push`, `post-checkout`) are installed in the `.git/hooks` directory of your repository. These hooks intercept Git operations to correctly handle LFS pointers and actual large file content.

    2. **Configures `.gitattributes`**: While this command primarily focuses on enabling LFS in the *local Git configuration and hooks*, managing which files are tracked by LFS is typically done by adding entries to a `.gitattributes` file at the root of your repository (e.g., `*.safetensors filter=lfs diff=lfs merge=lfs -text`). This command *doesn't automatically create or modify your `.gitattributes`* file, but rather sets up the environment so that Git LFS *can* function once such a file is present and committed.

    3. **Verifies LFS setup**: It essentially makes sure that `git lfs install` (or its equivalent setup) has been run for the specified repository, making it ready to track and push large files.

    Usage Examples

    #### 1. Enable LFS for the current directory (assuming it's a Git repo)

    If you are inside your local repository directory and want to enable LFS, simply run:

    bash
    huggingface-cli lfs-enable-largefiles

    Output might look like:

    Git LFS hooks successfully installed in the current directory.

    #### 2. Enable LFS for a specific repository path

    If your repository is located at a different path, e.g., `~/my-model-repo`, you can specify it:

    bash
    huggingface-cli lfs-enable-largefiles ~/my-model-repo

    Output might look like:

    Git LFS hooks successfully installed in /home/user/my-model-repo.

    #### 3. Workflow Example: Cloning, Enabling LFS, and Pushing a Large File

    Let's say you clone a new repository and want to add a large model file to it.

    bash
    # 1. Clone a new repository (or start a new one)
git clone https://huggingface.co/your-username/your-new-model-repo
cd your-new-model-repo

# 2. Enable LFS for this repository
huggingface-cli lfs-enable-largefiles

# 3. Inform Git LFS to track specific file types (e.g., .safetensors) by adding to .gitattributes
echo '*.safetensors filter=lfs diff=lfs merge=lfs -text' >> .gitattributes
git add .gitattributes
git commit -m "Configure LFS for safetensors files"

# 4. Add your large file
# (Assume 'large_model.safetensors' is a file you want to add)
mv /path/to/your/large_model.safetensors .
git add large_model.safetensors

# 5. Commit and Push
git commit -m "Add large model file"
git push

    After these steps, `large_model.safetensors` will be tracked by Git LFS, and its content will be uploaded to the LFS store when you push, rather than directly into the Git repository.