Struct HFBucket 

pub struct HFBucket { /* private fields */ }

A handle for a single bucket on the Hugging Face Hub.

HFBucket is created via HFClient::bucket and binds together the client, owner (namespace), and bucket name. All bucket-scoped API operations are methods on this type.

Cheap to clone — the inner HFClient is Arc-backed.

Example

let client = HFClient::builder().build()?;
let bucket = client.bucket("my-org", "my-bucket");

let info = bucket.info().send().await?;
println!("bucket {} ({} files)", info.id, info.total_files);

let stream = bucket.list_tree().send()?;
futures::pin_mut!(stream);
while let Some(entry) = stream.next().await {
    println!("{:?}", entry?);
}

Implementations

impl HFBucket

pub fn sync<'f1>(&'f1 self) -> HFBucketSyncBuilder<'f1>

Available on non-target_family=wasm only.

Synchronize a local directory with this bucket.

The sync is one-way and controlled by direction:

• BucketSyncDirection::Upload compares local_path against the bucket (optionally scoped by prefix) and uploads changed or missing files.
• BucketSyncDirection::Download compares the bucket against local_path and downloads changed or missing files.

When delete is enabled, files that only exist on the receiving side are removed as part of the sync. The returned BucketSyncPlan describes the operations that were executed; set verbose(true) if you also want explicit Skip entries explaining why untouched files were not transferred.

Comparison behavior

By default, files are considered different when their sizes differ or when the source file is newer than the destination file. Modification times are compared with a small tolerance to avoid unnecessary transfers caused by filesystem timestamp precision. ignore_times switches the comparison to size-only; ignore_sizes switches it to mtime-only. existing and ignore_existing further limit which files are eligible to transfer.

Parameters

• local_path (required): local directory path.
• direction (required): sync direction (upload or download).
• prefix: optional prefix within the bucket (subdirectory).
• delete: delete destination files not present in source.
• ignore_times: only compare sizes, ignore modification times.
• ignore_sizes: only compare modification times, ignore sizes.
• existing: only sync files that already exist at destination.
• ignore_existing: skip files that already exist at destination.
• include: glob-style include patterns.
• exclude: glob-style exclude patterns. Exclusions take precedence over inclusions.
• verbose: include skip operations in the returned plan.
• progress: progress handler for upload/download tracking.

impl HFBucket

pub fn new( client: HFClient, owner: impl Into<String>, name: impl Into<String>, ) -> Self

Construct a new bucket handle. Prefer HFClient::bucket in most cases.

pub fn client(&self) -> &HFClient

Return a reference to the underlying HFClient.

pub fn owner(&self) -> &str

The bucket owner (user or organization namespace).

pub fn name(&self) -> &str

The bucket name (without owner prefix).

pub fn bucket_id(&self) -> String

The full "owner/name" bucket identifier used in Hub API calls.

impl HFBucket

pub fn info<'f1>(&'f1 self) -> HFBucketInfoBuilder<'f1>

Get metadata about this bucket.

Endpoint: GET /api/buckets/{bucket_id}.

pub fn list_tree<'f1>(&'f1 self) -> HFBucketListTreeBuilder<'f1>

List files and directories in this bucket.

This is the main API for browsing bucket contents. For targeted lookups of a known set of paths, prefer HFBucket::get_paths_info.

Endpoint: GET /api/buckets/{bucket_id}/tree[/{prefix}] (paginated).

Parameters

• prefix: filter results to entries under this prefix.
• recursive (default false): traverse subdirectories.

pub fn get_paths_info<'f1>(&'f1 self) -> HFBucketGetPathsInfoBuilder<'f1>

Get info about specific paths in this bucket.

This is useful when you already know which paths you care about and do not want to stream the full tree. Requests are automatically chunked in batches of 1000 paths.

Endpoint: POST /api/buckets/{bucket_id}/paths-info.

Parameters

• paths (required): paths to inspect.

pub fn download_file_stream<'f1>( &'f1 self, ) -> HFBucketDownloadFileStreamBuilder<'f1>

Stream the bytes of a single file in this bucket without writing to disk.

Parallel of HFRepository::download_file_stream for buckets. Returns (content_length, stream) — content_length reflects the file size reported by paths-info. Xet-backed files dispatch through xet streaming; non-xet files fall back to a direct GET on the bucket’s resolve URL.

Endpoint (non-xet branch): GET {endpoint}/buckets/{bucket_id}/resolve/{remote_path}.

Parameters

• remote_path (required): file path within the bucket.
• progress: optional progress handler. Start is emitted before the stream is returned; Progress is emitted as the caller polls each chunk; Complete is emitted when the stream is exhausted.

pub fn get_file_metadata<'f1>(&'f1 self) -> HFBucketGetFileMetadataBuilder<'f1>

Get metadata for a single file in this bucket via a HEAD request.

Endpoint: HEAD /buckets/{bucket_id}/resolve/{path}.

Parameters

• remote_path (required): file path within the bucket.

pub fn batch_operations<'f1>(&'f1 self) -> HFBucketBatchOperationsBuilder<'f1>

Execute batch file operations (add, delete, copy) on this bucket.

This is the low-level file mutation API. add operations only register metadata on the bucket side; the file contents must already have been uploaded to xet so each entry has a valid BucketAddFile::xet_hash.

For simpler upload and download flows, prefer HFBucket::upload_files and HFBucket::download_files.

Endpoint: POST /api/buckets/{bucket_id}/batch (NDJSON). Operations are chunked at 1000 entries per request.

All paths in add, delete, and copy are bucket-relative, slash-separated paths (e.g., "data/train/0001.bin") — no leading slash, forward slashes regardless of platform, no bucket_id prefix.

Parameters

• add_files: files to register in the bucket. Each BucketAddFile requires:
  • path (String): bucket-relative destination path.
  • xet_hash (String): xet content hash from a prior xet upload — the bytes must already be in xet storage; this call only registers metadata.
  • size (u64): file size in bytes.
  • mtime (Option<u64>): last modification time as a Unix timestamp in seconds.
  • content_type (Option<String>): MIME type (e.g., "text/plain").
• delete: bucket-relative paths to remove from the bucket.
• copy: server-side copies into this bucket. Each BucketCopyFile requires:
  • path (String): bucket-relative destination path.
  • xet_hash (String): xet content hash of the source bytes (already present in xet storage from another repo or bucket — copies are by-hash, no data is transferred).
  • source_repo_type (BucketCopySourceType): repo type of the source — one of Bucket, Model, Dataset, or Space. Serializes to the lowercase wire string the Hub expects.
  • source_repo_id (String): full source identifier in "namespace/name" form (e.g., "user/my-bucket").

pub fn delete_files<'f1>(&'f1 self) -> HFBucketDeleteFilesBuilder<'f1>

Delete files from this bucket by path.

Convenience wrapper around HFBucket::batch_operations that sends only deleteFile operations.

Parameters

• paths (required): paths to delete from the bucket.

pub fn upload_source_files<'f1>( &'f1 self, ) -> HFBucketUploadSourceFilesBuilder<'f1>

Upload an arbitrary set of AddSource-backed files to the bucket.

More general analog of HFBucket::upload_files (which only reads from local paths): each pair can use any AddSource variant — Bytes for in-memory content, File for a local path, or Stream for sources too large to materialize at once. For the common in-memory case, build entries with AddSource::bytes:

vec![("logs/run-1.txt".into(), AddSource::bytes(b"hello".as_slice()))]

Goes through the same preupload + xet pipeline as HFBucket::upload_files.

Parameters

• files (required): list of (remote_path, source) pairs.
• progress: optional progress handler.

pub fn upload_files<'f1>(&'f1 self) -> HFBucketUploadFilesBuilder<'f1>

Upload local files to the bucket.

File contents are uploaded to xet first, then registered in the bucket via the batch endpoint. Each entry pairs a local source with a bucket-relative destination via the BucketUpload struct (use BucketUpload::new to construct one).

Parameters

• files (required): list of BucketUpload entries describing each local → remote mapping.
• progress: optional progress handler.

pub fn download_files<'f1>(&'f1 self) -> HFBucketDownloadFilesBuilder<'f1>

Download files from the bucket to local paths.

The method first resolves xet metadata for each remote path, then downloads the file contents through xet. Directory entries are rejected. Each entry pairs a bucket-relative source with a local destination via the BucketDownload struct (use BucketDownload::new to construct one).

Parameters

• files (required): list of BucketDownload entries describing each remote → local mapping.
• progress: optional progress handler.

Trait Implementations

impl Clone for HFBucket

fn clone(&self) -> HFBucket

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HFBucket

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.