hf-hub Rust Library

The Hugging Face Hub provides a raw diff format (a line-oriented variant of git's raw diff) to inspect file changes between repository revisions. You can use HFFileDiff to access metadata for each changed file, such as blob IDs, file status, and size.

For rename or copy operations, file_path represents the source path, while new_file_path contains the destination path. For additions, deletions, or in-place modifications, new_file_path will be None.

// Example of the data structure returned by the parser
HFFileDiff {
    old_blob_id: String, // All zeroes for additions
    new_blob_id: String, // All zeroes for deletions
    status: GitStatus,   // e.g., Addition, Deletion, Modification, Rename, Copy
    file_path: String,   // Source path
    new_file_path: Option<String>, // Destination path for Rename/Copy
    is_binary: bool,     // True if marked 'B', false if 'T'
    new_file_size: u64,  // Size in bytes
}

When the repository kind is decided at runtime (for example, via a CLI flag or a configuration string), use the RepoTypeAny enum.

RepoTypeAny implements FromStr, allowing you to parse strings like "model", "models", "dataset", "datasets", etc., into a valid type. It also implements the RepoType trait, so it can be used as a type parameter for HFRepository<RepoTypeAny>.

Note: While RepoTypeAny supports all standard file, commit, and repository management APIs (uploads, downloads, tree listings, etc.), it does not support Space-only methods like runtime(), pause(), restart(), secrets(), variables(), or hardware(). Those require a typed HFRepository<RepoTypeSpace>.

use hf_hub::{HFClient, RepoTypeAny};

let kind: RepoTypeAny = "datasets".parse().unwrap();
let repo: HFRepository<RepoTypeAny> = client.repository(kind, "rajpurkar", "squad");

The hf-hub crate uses a type-level marker system to encode the Hugging Face Hub repository kind (model, dataset, space, or kernel) into the type system. This allows methods that behave differently depending on the repository type (like info()) to dispatch at compile time.

There are two ways to work with repository types:

1. Typed Markers: Use specific marker structs like RepoTypeModel, RepoTypeDataset, etc. This is preferred when the repository kind is known at compile time. It provides access to type-specific methods (e.g., RepoTypeSpace allows access to runtime() and pause() on an HFRepository).
2. Runtime Dispatch (RepoTypeAny): Use the RepoTypeAny enum when the repository kind is determined at runtime (e.g., from a CLI flag or configuration string). This allows you to use a single HFRepository<RepoTypeAny> type, but you lose access to type-specific methods like those for Spaces.

All markers and the RepoTypeAny enum implement the RepoType trait, which provides the singular name, plural name, and URL prefix for the repository kind.

use hf_hub::{HFClient, RepoTypeDataset};
# #[tokio::main] async fn main() -> hf_hub::HFResult<()> {
// Typed shortcut — preferred when the kind is known at the call site:
let repo = client.dataset("rajpurkar", "squad");

// Explicit marker — useful when the kind comes from a generic context:
let repo = client.repository(RepoTypeDataset, "rajpurkar", "squad");
# let _ = repo; Ok(()) }

Instead of passing repository identifiers to every method, you can bind them to a typed handle using HFClient methods. The repository kind (Model, Dataset, Space, or Kernel) is encoded in the type system using marker structs. This allows for type-specific methods (e.g., Space-specific methods like runtime or pause are only available on HFRepository<RepoTypeSpace>).

Common constructors:

• client.model(owner, name)
• client.dataset(owner, name)
• client.space(owner, name)
• client.kernel(owner, name)

You can use split_id to convert a single string like "owner/name" into the (owner, name) pair required by these constructors.

use hf_hub::{HFClient, split_id};

# #[tokio::main] async fn main() -> hf_hub::HFResult<()> {
let client = HFClient::new()?;
let (owner, name) = split_id("openai-community/gpt2");
let model = client.model(owner, name);
# let _ = model; Ok(()) }