Commit operations for uploading files to HuggingFace Hub.
This module provides functions to create commits that add, delete, or copy files in a repository.
Upload Modes
Files are uploaded in one of two modes:
- Regular: Base64-encoded in commit payload (for files < 10MB)
- LFS: Git Large File Storage protocol (for files >= 10MB)
The upload mode is automatically determined based on file size.
Examples
# Upload a single file
{:ok, info} = HfHub.Commit.upload_file(
"/path/to/model.bin",
"model.bin",
"my-org/my-model",
token: token,
commit_message: "Add model weights"
)
# Create a commit with multiple operations
{:ok, info} = HfHub.Commit.create("my-model", [
Operation.add("model.safetensors", "/path/to/model"),
Operation.add("config.json", config_content),
Operation.delete("old_model.bin")
], token: token, commit_message: "Update model")Summary
Functions
Creates a commit with one or more operations.
Deletes a file from a repository.
Deletes a folder and all its contents from a repository.
Returns the LFS size threshold in bytes (10MB).
Checks if a file path matches a gitignore-style pattern.
Determines if a file needs LFS upload based on its size.
Uploads a single file to a repository.
Uploads an entire folder to a repository.
Uploads a large folder using multiple commits if needed.
Types
Functions
@spec create(String.t(), [HfHub.Commit.Operation.t()], commit_opts()) :: {:ok, HfHub.Commit.CommitInfo.t()} | {:error, term()}
Creates a commit with one or more operations.
This is the primary function for making changes to a repository. Operations can include adding files, deleting files, or copying existing LFS files.
Options
:token- Authentication token (required):repo_type- Repository type: :model, :dataset, :space (default: :model):revision- Target branch (default: "main"):commit_message- Commit message (required):commit_description- Extended commit description:create_pr- Create a pull request instead of direct commit:parent_commit- Parent commit SHA for atomic operations
Examples
alias HfHub.Commit.Operation
{:ok, info} = HfHub.Commit.create("my-model", [
Operation.add("config.json", ~s({"hidden_size": 768})),
Operation.delete("old_config.json")
], token: token, commit_message: "Update config")@spec delete_file(String.t(), String.t(), commit_opts()) :: {:ok, HfHub.Commit.CommitInfo.t()} | {:error, term()}
Deletes a file from a repository.
Examples
{:ok, info} = HfHub.Commit.delete_file(
"old_model.bin",
"my-model",
token: token,
commit_message: "Remove old weights"
)@spec delete_folder(String.t(), String.t(), commit_opts()) :: {:ok, HfHub.Commit.CommitInfo.t()} | {:error, term()}
Deletes a folder and all its contents from a repository.
@spec lfs_threshold() :: non_neg_integer()
Returns the LFS size threshold in bytes (10MB).
Checks if a file path matches a gitignore-style pattern.
Pattern Syntax
*matches any sequence except/**matches any sequence including/?matches single character[abc]matches character class
Examples
iex> HfHub.Commit.matches_pattern?("file.json", "*.json")
true
iex> HfHub.Commit.matches_pattern?("path/to/file.json", "**/*.json")
true
iex> HfHub.Commit.matches_pattern?("__pycache__/cache.pyc", "__pycache__/**")
true@spec needs_lfs?(HfHub.Commit.Operation.Add.t()) :: boolean()
Determines if a file needs LFS upload based on its size.
@spec upload_file(binary() | Path.t(), String.t(), String.t(), commit_opts()) :: {:ok, HfHub.Commit.CommitInfo.t()} | {:error, term()}
Uploads a single file to a repository.
Convenience wrapper around create/3 for single-file uploads.
Examples
# From file path
{:ok, info} = HfHub.Commit.upload_file(
"/path/to/model.bin",
"model.bin",
"my-model",
token: token
)
# From binary content
{:ok, info} = HfHub.Commit.upload_file(
config_json,
"config.json",
"my-model",
token: token,
commit_message: "Update config"
)@spec upload_folder(Path.t(), String.t(), commit_opts()) :: {:ok, HfHub.Commit.CommitInfo.t()} | {:error, term()}
Uploads an entire folder to a repository.
Files are uploaded in batch with automatic LFS detection. Use patterns to filter which files to include or exclude.
Options
:token- Authentication token (required):repo_type- Repository type (default: :model):revision- Target branch (default: "main"):commit_message- Commit message (default: "Upload folder"):commit_description- Extended description:create_pr- Create pull request (default: false):allow_patterns- Only include files matching patterns:ignore_patterns- Exclude files matching patterns:delete_patterns- Delete remote files matching patterns
Pattern Syntax
Patterns use gitignore-style matching:
*matches any sequence except/**matches any sequence including/?matches single character[abc]matches character class
Examples
# Upload entire folder
{:ok, info} = HfHub.Commit.upload_folder(
"/path/to/model_dir",
"my-org/my-model",
token: token
)
# With pattern filtering
{:ok, info} = HfHub.Commit.upload_folder(
"/path/to/model_dir",
"my-model",
token: token,
ignore_patterns: ["*.pyc", "__pycache__/**", ".git/**"],
allow_patterns: ["*.safetensors", "*.json"]
)
# Delete old files matching pattern
{:ok, info} = HfHub.Commit.upload_folder(
"/path/to/model_dir",
"my-model",
token: token,
delete_patterns: ["*.bin"] # Delete old .bin files, upload new
)@spec upload_large_folder(Path.t(), String.t(), commit_opts()) :: {:ok, [HfHub.Commit.CommitInfo.t()]} | {:error, term()}
Uploads a large folder using multiple commits if needed.
For folders with many files or large total size, this function automatically splits the upload into multiple commits.
Options
Same as upload_folder/3, plus:
:multi_commits- Enable automatic splitting (default: false):multi_commits_verbose- Log progress (default: false)
Examples
{:ok, infos} = HfHub.Commit.upload_large_folder(
"/path/to/huge_model",
"my-model",
token: token,
multi_commits: true
)