# `HuggingfaceClient.Hub.Repos`
[🔗](https://github.com/huggingface/huggingface_client/blob/v0.1.0/lib/huggingface_client/hub/repos.ex#L1)

Repository management on the HuggingFace Hub.

Covers creating, updating, and deleting repos, branch/tag operations,
and individual file downloads.

## Usage

    # Create a new model repository
    {:ok, repo} = HuggingfaceClient.Hub.Repos.create("my-model",
      repo_type:    :model,
      private:      false,
      access_token: token
    )

    # Download a single file
    {:ok, content} = HuggingfaceClient.Hub.Repos.download_file(
      "gpt2", "config.json",
      access_token: token
    )

# `create`

```elixir
@spec create(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Exception.t()}
```

Creates a new repository on the Hub.

## Required arguments

- `repo_id` — `"namespace/name"` or just `"name"` (owner inferred from token)

## Optional options

- `:repo_type` — `:model` (default), `:dataset`, `:space`
- `:private`   — `false` (default)
- `:exist_ok`  — if `true`, return `:ok` on 409 Conflict (default `false`)
- `:access_token`

# `create_branch`

```elixir
@spec create_branch(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Exception.t()}
```

Creates a new branch in a repository.

## Required arguments

- `repo_id`     — full repo id (e.g. `"my-org/my-model"`)
- `branch_name` — name for the new branch

## Options

- `:starting_point` — commit SHA or existing branch (default: `"main"`)
- `:repo_type`, `:access_token`

# `create_tag`

```elixir
@spec create_tag(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Exception.t()}
```

Creates a new tag pointing to a commit or branch.

# `delete`

```elixir
@spec delete(
  String.t(),
  keyword()
) :: :ok | {:error, Exception.t()}
```

Deletes a repository. Irreversible.

## Options

- `:repo_type`, `:access_token`

# `delete_branch`

```elixir
@spec delete_branch(String.t(), String.t(), keyword()) ::
  :ok | {:error, Exception.t()}
```

Deletes a branch from a repository.

## Required arguments

- `repo_id`     — full repo id
- `branch_name` — branch to delete

# `delete_tag`

```elixir
@spec delete_tag(String.t(), String.t(), keyword()) :: :ok | {:error, Exception.t()}
```

Deletes a tag from a repository.

# `download_file`

```elixir
@spec download_file(String.t(), String.t(), keyword()) ::
  {:ok, binary()} | {:error, Exception.t()}
```

Downloads a single file from a Hub repository.

Returns `{:ok, binary}` on success.

## Required arguments

- `repo_id`   — e.g. `"gpt2"` or `"meta-llama/Llama-3.1-8B-Instruct"`
- `file_path` — path inside the repo, e.g. `"config.json"`

## Options

- `:repo_type`  — `:model` (default), `:dataset`, `:space`
- `:revision`   — branch/tag/commit SHA (default: `"main"`)
- `:access_token`

# `list_commits`

```elixir
@spec list_commits(
  String.t(),
  keyword()
) :: Enumerable.t()
```

Returns a lazy stream of commits for a repository.

# `list_files`

```elixir
@spec list_files(
  String.t(),
  keyword()
) :: {:ok, list()} | {:error, Exception.t()}
```

Lists all files in a repository at a given revision.

Returns `{:ok, [file_map]}` where each map has `"path"`, `"size"`, `"type"`, `"oid"`.

# `update`

```elixir
@spec update(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Exception.t()}
```

Updates repository metadata (visibility, description, etc.).

---

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