# `HfHub.FS`
[🔗](https://github.com/North-Shore-AI/hf_hub_ex/blob/v0.3.1/lib/hf_hub/fs.ex#L1)

Filesystem utilities for HuggingFace cache management.

Provides low-level functions for managing the local cache directory structure,
file paths, and locking mechanisms.

## Examples

    # Ensure cache directory exists
    :ok = HfHub.FS.ensure_cache_dir()

    # Get repository path
    path = HfHub.FS.repo_path("bert-base-uncased", :model)

    # Get file path in repository
    path = HfHub.FS.file_path("bert-base-uncased", :model, "config.json")

    # Acquire file lock for concurrent downloads
    {:ok, lock} = HfHub.FS.lock_file("bert-base-uncased", "pytorch_model.bin")
    # ... download file ...
    :ok = HfHub.FS.unlock_file(lock)

# `cache_dir`

```elixir
@spec cache_dir() :: Path.t()
```

Gets the configured cache directory.

## Examples

    dir = HfHub.FS.cache_dir()
    # => "/home/user/.cache/huggingface"

# `ensure_cache_dir`

```elixir
@spec ensure_cache_dir() :: :ok | {:error, term()}
```

Ensures the cache directory exists.

Creates the cache directory and any necessary subdirectories if they don't exist.

## Examples

    :ok = HfHub.FS.ensure_cache_dir()

# `file_path`

```elixir
@spec file_path(
  HfHub.repo_id(),
  HfHub.repo_type(),
  HfHub.filename(),
  HfHub.revision()
) :: Path.t()
```

Gets the local path for a file in a repository.

## Arguments

  * `repo_id` - Repository ID
  * `repo_type` - Type of repository
  * `filename` - Name of the file
  * `revision` - Git revision (defaults to "main")

## Examples

    path = HfHub.FS.file_path("bert-base-uncased", :model, "config.json")
    # => "/home/user/.cache/huggingface/hub/models--bert-base-uncased/snapshots/main/config.json"

# `lock_file`

```elixir
@spec lock_file(HfHub.repo_id(), HfHub.filename()) ::
  {:ok, reference()} | {:error, term()}
```

Acquires a lock on a file for concurrent download protection.

Returns `{:ok, lock}` where `lock` is a reference that can be used to unlock the file.

## Arguments

  * `repo_id` - Repository ID
  * `filename` - Name of the file

## Examples

    {:ok, lock} = HfHub.FS.lock_file("bert-base-uncased", "pytorch_model.bin")
    # ... perform download ...
    :ok = HfHub.FS.unlock_file(lock)

# `repo_path`

```elixir
@spec repo_path(HfHub.repo_id(), HfHub.repo_type()) :: Path.t()
```

Gets the local path for a repository.

## Arguments

  * `repo_id` - Repository ID
  * `repo_type` - Type of repository (`:model`, `:dataset`, or `:space`)

## Examples

    path = HfHub.FS.repo_path("bert-base-uncased", :model)
    # => "/home/user/.cache/huggingface/hub/models--bert-base-uncased"

# `unlock_file`

```elixir
@spec unlock_file(reference()) :: :ok | {:error, term()}
```

Releases a file lock.

## Arguments

  * `lock` - Lock reference from `lock_file/2`

## Examples

    {:ok, lock} = HfHub.FS.lock_file("bert-base-uncased", "config.json")
    :ok = HfHub.FS.unlock_file(lock)

---

*Consult [api-reference.md](api-reference.md) for complete listing*