# Корзины

Buckets обеспечивают объектное хранилище, аналогичное S3, на Hugging Face, работающее на базе системы хранения Xet. В отличие от репозиториев (которые основаны на git и отслеживают историю файлов), buckets представляют собой удалённые контейнеры объектного хранилища, предназначенные для работы с файлами большого размера с дедупликацией на основе контрольных сумм содержимого. Они созданы для сценариев, где требуется простое, быстрое и изменяемое хранилище, например, для сохранения контрольных точек обучения, журналов, промежуточных артефактов или любых больших коллекций файлов, не требующих контроля версий.

Вы можете работать с бакетами с помощью Python API ([HfApi](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi)) или CLI (`hf buckets`). В этом руководстве мы рассмотрим все доступные операции.

> [!TIP]
> Все команды CLI доступны в разделе `hf buckets <command>`. Запустите `hf buckets --help`, чтобы узнать больше.

## Создание и управление бакетами

### Создать бакет

Создайте бакет с помощью [create_bucket()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.create_bucket). Необходимо указать имя бакета. Если пространство имён не указано, бакет будет создан в вашем пользовательском имени.

```py
>>> from huggingface_hub import create_bucket

# Create a bucket under your namespace
>>> url = create_bucket("my-bucket")
>>> url.bucket_id
'username/my-bucket'
>>> url.uri.to_uri()
'hf://buckets/username/my-bucket'

# Create a private bucket
>>> create_bucket("my-private-bucket", private=True)
BucketUrl(...)

# Don't error if bucket already exists
>>> create_bucket("my-bucket", exist_ok=True)
BucketUrl(...)

# Create a bucket in a specific region
>>> create_bucket("my-bucket", region="us")
BucketUrl(...)
```

Или через CLI:

```bash
>>> hf buckets create my-bucket
✓ Bucket created
  uri: hf://buckets/Wauplin/my-bucket
  url: https://huggingface.co/buckets/Wauplin/my-bucket

# Create a private bucket
>>> hf buckets create my-bucket --private

# Don't error if bucket already exists
>>> hf buckets create my-bucket --exist-ok

# Create a bucket in a specific region
>>> hf buckets create my-bucket --region us
```

Вы также можете указать полный формат `namespace/bucket_name`, чтобы создать бакет в рамках организации:

```py
>>> from huggingface_hub import create_bucket
>>> create_bucket("my-org/shared-bucket")
```

Или через CLI:

```bash
>>> hf buckets create my-org/shared-bucket
```

### Получить информацию о бакете

Используйте [bucket_info()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.bucket_info), чтобы получить метаданные о бакете, включая его видимость, общий размер, количество файлов и дату создания.

```py
>>> from huggingface_hub import bucket_info
>>> bucket_info("username/my-bucket")
BucketInfo(
  id='username/my-bucket',
  private=False,
  created_at=datetime.datetime(2026, 2, 12, 17, 42, 12,
  tzinfo=datetime.timezone.utc),
  size=8411791508,
  total_files=128
)
```

Или через CLI:

```bash
# JSON output
>>> hf buckets info username/my-bucket
{
  "id": "username/my-bucket",
  "private": false,
  ...
}
```

### Список бакетов

Используйте [list_buckets()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.list_buckets), чтобы получить список всех бакетов в пространстве имён. По умолчанию выводятся бакеты из пространства имён текущего пользователя.

```py
>>> from huggingface_hub import list_buckets

# List your own buckets
>>> for bucket in list_buckets():
...     print(bucket.id, bucket.size, bucket.total_files)

# List buckets in an organization
>>> for bucket in list_buckets(namespace="huggingface"):
...     print(bucket.id)
```

Или через CLI (`hf buckets ls` — сокращение от `hf buckets list`):

```bash
# Table format (default)
>>> hf buckets list
ID                   PRIVATE      SIZE TOTAL_FILES CREATED_AT
-------------------- ------- --------- ----------- ----------
username/my-bucket                  32           5 2026-02-16
username/checkpoints         117609095         700 2026-02-13
username/logs                321757477        2000 2026-02-13

# Human-readable sizes
>>> hf buckets list -h
ID                   PRIVATE     SIZE TOTAL_FILES CREATED_AT
-------------------- ------- -------- ----------- ----------
username/my-bucket               32 B           5 2026-02-16
username/checkpoints         117.6 MB         700 2026-02-13
username/logs                321.8 MB        2000 2026-02-13

# List buckets in a specific namespace
>>> hf buckets ls huggingface

# Filter buckets by name
>>> hf buckets list --search "checkpoint"
```

Вы также можете фильтровать бакеты по имени с помощью `search`:

```py
>>> for bucket in list_buckets(search="checkpoint"):
...     print(bucket.id)
```

Вы можете использовать параметры `--quiet` и `--format json`, чтобы получить вывод в другом формате. Это особенно полезно, если вы хотите передать вывод в другой инструмент, например `grep` или `jq`.

```bash
# Quiet mode: prints one bucket ID per line
>>> hf buckets list --quiet
username/my-bucket
username/checkpoints
username/logs

# JSON format
>>> hf buckets list --format json
[
  {
    "id": "username/my-bucket",
    "private": false,
    "created_at": "2026-02-16T15:28:32+00:00",
    "size": 32,
    "total_files": 5
  },
  ...
]
```

### Изменение видимости хранилища

Используйте [update_bucket_settings()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.update_bucket_settings), чтобы переключить существующее хранилище между приватным и публичным режимами.

```py
>>> from huggingface_hub import update_bucket_settings

# Make a bucket private
>>> update_bucket_settings("username/my-bucket", private=True)

# Make it public again
>>> update_bucket_settings("username/my-bucket", private=False)
```

Или через CLI:

```bash
# Make a bucket private
>>> hf buckets settings username/my-bucket --private
✓ Bucket settings updated
  bucket_id: username/my-bucket
  private: True

# Make it public again
>>> hf buckets settings username/my-bucket --public
```

### Удаление хранилища

Используйте [delete_bucket()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.delete_bucket) для удаления бакета. Эта операция необратима.

```py
>>> from huggingface_hub import delete_bucket
>>> delete_bucket("username/my-bucket")

# Don't error if bucket doesn't exist
>>> delete_bucket("username/my-bucket", missing_ok=True)
```

Или через CLI:

```bash
# Prompts for confirmation
>>> hf buckets delete username/my-bucket

# Skip confirmation
>>> hf buckets delete username/my-bucket --yes

# Don't error if bucket doesn't exist
>>> hf buckets delete username/my-bucket --yes --missing-ok
```

### Удаление файлов

Используйте [batch_bucket_files()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.batch_bucket_files) с параметром `delete`, чтобы удалить файлы из бакета:

```py
>>> from huggingface_hub import batch_bucket_files

# Delete specific files
>>> batch_bucket_files("username/my-bucket", delete=["old-model.bin", "logs/debug.log"])
```

Или через CLI с помощью `hf buckets rm` (или `hf buckets remove`):

```bash
# Remove a single file
>>> hf buckets rm username/my-bucket/old-model.bin

# Remove all files under a prefix (requires --recursive)
>>> hf buckets rm username/my-bucket/logs/ --recursive

# Remove only files matching a pattern across the entire bucket
>>> hf buckets rm username/my-bucket --recursive --include "*.tmp"

# Exclude specific files from removal
>>> hf buckets rm username/my-bucket/data/ --recursive --exclude "*.safetensors"

# Preview what would be deleted
>>> hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-run
```

### Переместить бакет

Используйте [move_bucket()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.move_bucket), чтобы переместить или переименовать бакет. Вы можете переименовать его в том же пространстве имён или перенести в другое пространство имён (пользователь или организация).

```py
>>> from huggingface_hub import move_bucket

# Rename a bucket
>>> move_bucket(from_id="username/old-name", to_id="username/new-name")

# Transfer to an organization
>>> move_bucket(from_id="username/my-bucket", to_id="my-org/my-bucket")
```

Или через CLI:

```bash
# Rename a bucket
>>> hf buckets move username/old-bucket username/new-bucket

# Transfer to an organization
>>> hf buckets move username/my-bucket my-org/my-bucket

# Using the hf://buckets/ format
>>> hf buckets move hf://buckets/username/old-bucket hf://buckets/username/new-bucket
```

> [!TIP]
> Для получения дополнительной информации о перемещении репозиториев и бакетов см. [документацию Hub](https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo).

## Просмотр содержимого хранилища

### Список файлов

Используйте [list_bucket_tree()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.list_bucket_tree) для получения списка файлов и каталогов в бакете.

```py
>>> from huggingface_hub import list_bucket_tree

# List all files
>>> for item in list_bucket_tree("username/my-bucket"):
...     print(item.path, item.size)
file.txt 5
big.bin 2048
sub/nested.txt 14
sub/deep/file.txt 4

# List top-level entries only
>>> for item in list_bucket_tree("username/my-bucket", recursive=False):
...     print(item.type, item.path)
file file.txt
file big.bin
directory sub

# Filter by prefix
>>> for item in list_bucket_tree("username/my-bucket", prefix="sub"):
...     print(item.path)
```

Или через CLI, с поддержкой форматов таблицы, читаемого человеком и ASCII-дерева. По умолчанию CLI работает в нерекурсивном режиме.

```bash
# Default table format (non-recursive, directories shown as entries)
>>> hf buckets list username/my-bucket
        2048  2026-01-15 10:30:00  big.bin
           5  2026-01-15 10:30:00  file.txt
              2026-01-15 10:30:00  sub/

# Recursive listing (all files, including nested)
>>> hf buckets list username/my-bucket -R
        2048  2026-01-15 10:30:00  big.bin
           5  2026-01-15 10:30:00  file.txt
          14  2026-01-15 10:30:00  sub/nested.txt
           4  2026-01-15 10:30:00  sub/deep/file.txt

# Human-readable sizes and short dates
>>> hf buckets list username/my-bucket -R -h
      2.0 KB         Jan 15 10:30  big.bin
         5 B         Jan 15 10:30  file.txt
        14 B         Jan 15 10:30  sub/nested.txt
         4 B         Jan 15 10:30  sub/deep/file.txt

# ASCII tree format
>>> hf buckets list username/my-bucket --tree -h -R
2.0 KB  Jan 15 10:30  ├── big.bin
   5 B  Jan 15 10:30  ├── file.txt
                      └── sub/
                          ├── deep/
   4 B  Jan 15 10:30  │       └── file.txt
  14 B  Jan 15 10:30  └── nested.txt

# Tree structure only (no sizes/dates)
>>> hf buckets list username/my-bucket --tree --quiet -R
├── big.bin
├── file.txt
└── sub/
    ├── deep/
    │   └── file.txt
    └── nested.txt

# Quiet mode: one path per line
>>> hf buckets list username/my-bucket -q
big.bin
file.txt
sub/

# Filter by prefix
>>> hf buckets list username/my-bucket/sub -R
```

> [!TIP]
> Команда `hf buckets list` принимает в качестве аргументов как краткий формат (`username/my-bucket/sub`), так и полный идентификатор (`hf://buckets/username/my-bucket/sub`).

> [!TIP]
> Перечисление содержимого бакета с помощью [HfFileSystem](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_file_system#huggingface_hub.HfFileSystem) кэшируется. Чтобы обновления списка происходили автоматически при добавлении, изменении или удалении файлов в бакете другими пользователями, передайте `HfFileSystem(live_follow=True)`, см. [руководство по файловой системе](./hf_file_system#keep-listings-fresh).

## Загрузка файлов

### Загрузка с помощью Python

Используйте [batch_bucket_files()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.batch_bucket_files) для загрузки файлов в бакет. Загрузка возможна из локальных путей к файлам или из сырых байтов:

```py
>>> from huggingface_hub import batch_bucket_files

# Upload from local file paths
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[
...         ("./model.safetensors", "models/model.safetensors"),
...         ("./config.json", "models/config.json"),
...     ],
... )

# Upload from raw bytes
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[
...         (b'{"key": "value"}', "config.json"),
...     ],
... )
```

Вы также можете копировать файлы xet из другого хранилища или репозитория с помощью параметра `copy`. Это серверная операция — данные не скачиваются и не загружаются повторно:

```python
# Copy files by xet hash (source_repo_type, source_repo_id, xet_hash, destination)
>>> batch_bucket_files(
...     "username/my-bucket",
...     copy=[
...         ("bucket", "username/source-bucket", "<xethash_1>", "models/model.safetensors"),
...         ("model", "username/my-model", "<xethash_2>", "models/config.safetensors"),
...     ],
... )
```

Хеши Xet можно получить с помощью `list_repo_tree`.

Вы также можете удалять файлы во время загрузки других.

```python
# Upload and delete in one batch
>>> batch_bucket_files(
...     "username/my-bucket",
...     add=[("./new-model.safetensors", "model.safetensors")],
...     delete=["old-model.bin"],
... )
```

> [!WARNING]
> Вызовы [batch_bucket_files()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.batch_bucket_files) не являются транзакционными. Если в процессе возникает ошибка, часть файлов может быть загружена, скопирована или удалена, тогда как другие — нет. Когда сервер сообщает о неудаче некоторых операций, возникает `BucketBatchError`, в атрибуте `failures` которого указаны пути к неудавшимся операциям.

### Загрузка одного файла с помощью CLI

Используйте `hf buckets cp` для загрузки одного файла:

> [!TIP]
> `hf buckets cp` — это псевдоним для универсальной команды `hf cp` (также доступной как `hf repos cp`). Все три команды идентичны, поэтому любой пример с `hf buckets cp` ниже также работает с `hf cp`.

```bash
# Upload to bucket root (uses local filename as remote name)
>>> hf buckets cp ./config.json hf://buckets/username/my-bucket

# Upload to a subdirectory
>>> hf buckets cp ./data.csv hf://buckets/username/my-bucket/logs/

# Upload with a different remote filename
>>> hf buckets cp ./model.safetensors hf://buckets/username/my-bucket/v2/model.safetensors
```

Вы также можете передать результат команды напрямую в новый файл с помощью `-`:

```
# Upload from stdin
>>> echo "hello" | hf buckets cp - hf://buckets/username/my-bucket/hello.txt
>>> cat model.safetensors | hf buckets cp - hf://buckets/username/my-bucket/model.safetensors
```

### Загрузка каталога с помощью CLI

Используйте `hf buckets sync`, чтобы загрузить всю локальную директорию в бакет:

```bash
# Upload a local directory to a bucket
>>> hf buckets sync ./data hf://buckets/username/my-bucket

# Upload to a specific prefix in the bucket
>>> hf buckets sync ./data hf://buckets/username/my-bucket/train
```

См. раздел [Синхронизация каталогов](#sync-directories) ниже для полного набора вариантов синхронизации.

## Загрузка файлов

### Загрузка с помощью Python

Используйте [download_bucket_files()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.download_bucket_files) для загрузки файлов из хранилища:

```py
>>> from huggingface_hub import download_bucket_files

# Download specific files by path
>>> download_bucket_files(
...     "username/my-bucket",
...     files=[
...         ("models/model.safetensors", "./local/model.safetensors"),
...         ("config.json", "./local/config.json"),
...     ],
... )
```

Для повышения производительности вместо строковых путей можно передавать объекты [BucketFile](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.BucketFile), полученные с помощью [list_bucket_tree()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.list_bucket_tree). Это позволяет пропустить этап получения метаданных:

```py
>>> from huggingface_hub import list_bucket_tree, download_bucket_files

# List and filter files, then download
>>> parquet_files = [
...     item for item in list_bucket_tree("username/my-bucket", recursive=True)
...     if item.type == "file" and item.path.endswith(".parquet")
... ]
>>> download_bucket_files(
...     "username/my-bucket",
...     files=[(f, f"./local/{f.path}") for f in parquet_files],
... )
```

### Загрузка одного файла с помощью CLI

Используйте `hf buckets cp` для загрузки одного файла:

```bash
# Download to a specific file
>>> hf buckets cp hf://buckets/username/my-bucket/config.json ./config.json

# Download to a directory (uses original filename)
>>> hf buckets cp hf://buckets/username/my-bucket/config.json ./data/

# Download to current directory (omit destination)
>>> hf buckets cp hf://buckets/username/my-bucket/config.json
```

Вы также можете передать содержимое файла напрямую в `stdout`, используя `-`:

```bash
# Download to stdout and pretty-print with jq
>>> hf buckets cp hf://buckets/username/my-bucket/config.json - | jq .
```

### Загрузка каталога с помощью CLI

Используйте `hf buckets sync`, чтобы скачать все файлы из бакета в локальный каталог:

```bash
# Download bucket contents to a local directory
>>> hf buckets sync hf://buckets/username/my-bucket ./data

# Download only a specific prefix
>>> hf buckets sync hf://buckets/username/my-bucket/models ./local-models
```

См. раздел [Синхронизация каталогов](#sync-directories) ниже для полного набора вариантов синхронизации.

## Копирование файлов в Bucket

Используйте [copy_files()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.copy_files), чтобы скопировать файлы, уже размещённые на Hub, в Bucket:

```py
>>> from huggingface_hub import copy_files

# Bucket to bucket (same or different bucket)
>>> copy_files(
...     "hf://buckets/username/source-bucket/checkpoints/model.safetensors",
...     "hf://buckets/username/destination-bucket/archive/model.safetensors",
... )

# Repo to bucket
>>> copy_files(
...     "hf://datasets/username/my-dataset/processed/",
...     "hf://buckets/username/my-bucket/datasets/processed/",
... )
```

То же самое доступно из CLI через унифицированную команду `hf cp` (также доступна как `hf buckets cp` и `hf repos cp` — все три идентичны):

```bash
# Bucket to bucket
>>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/destination-bucket/logs/

# Repo to bucket
>>> hf cp hf://username/my-model/config.json hf://buckets/username/my-bucket/models/config.json
```

При копировании папок завершающий `/` в пути источника использует семантику в стиле rsync — копируются только *содержимое* папки, без вложенности самой папки:

```bash
# Without trailing slash: "logs" dir is nested => destination/logs/...
>>> hf cp hf://buckets/username/source-bucket/logs hf://buckets/username/destination-bucket/

# With trailing slash: only contents of "logs" are copied => destination/...
>>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/destination-bucket/
```

Примечания:

- Копирование из бакета в репозиторий пока не поддерживается.
- Копии на стороне сервера работают только в пределах одной и той же [области хранения](https://huggingface.co/docs/hub/storage-regions).
- Файлы, отслеживаемые с помощью Xet (в баках или репозиториях), копируются на стороне сервера по хэшу — данные не скачиваются и не загружаются повторно.
- Небольшие текстовые файлы, не отслеживаемые Xet в источниках репозитория, загружаются и повторно выгружаются в целевое хранилище.
- [copy_files()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.copy_files) также можно использовать для копирования между репозиториями. Подробнее см. в [руководстве по репозиториям](./repository#copy-files).

## Синхронизация каталогов

Команда `hf buckets sync` (и её эквивалент в API [sync_bucket()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.sync_bucket)) — самый мощный способ передачи файлов между локальным каталогом и бакетом. Она сравнивает источник и назначение и передаёт только те файлы, которые изменились.

### Базовая синхронизация

```bash
# Upload: local directory -> bucket
>>> hf buckets sync ./data hf://buckets/username/my-bucket

# Download: bucket -> local directory
>>> hf buckets sync hf://buckets/username/my-bucket ./data
```

> [!TIP]
> `hf sync` — это удобный псевдоним для `hf buckets sync`. Обе команды идентичны.
> ```bash
> >>> hf sync ./data hf://buckets/username/my-bucket
> ```

Или через Python:

```py
>>> from huggingface_hub import sync_bucket

# Upload: local directory -> bucket
>>> sync_bucket("./data", "hf://buckets/username/my-bucket")

# Download: bucket -> local directory
>>> sync_bucket("hf://buckets/username/my-bucket", "./data")
```

### Удаление лишних файлов

По умолчанию sync добавляет или обновляет файлы. Используйте `--delete` (или `delete=True` в Python), чтобы также удалять файлы в пункте назначения, которых нет в источнике:

```bash
# Upload and remove remote files not present locally
>>> hf buckets sync ./data hf://buckets/username/my-bucket --delete

# Download and remove local files not present in bucket
>>> hf buckets sync hf://buckets/username/my-bucket ./data --delete
```

Или через Python:

```py
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", delete=True)
>>> sync_bucket("hf://buckets/username/my-bucket", "./data", delete=True)
```

### Фильтрация

Вы можете управлять синхронизацией файлов с помощью шаблонов включения/исключения:

```bash
# Only sync .txt files
>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.txt"

# Exclude log files
>>> hf buckets sync ./data hf://buckets/username/my-bucket --exclude "*.log"

# Combine include and exclude
>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.safetensors" --exclude "*.tmp"
```

Или через Python:

```py
# Only sync .txt files
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", include=["*.txt"])

# Exclude log files
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", exclude=["*.log"])

# Combine include and exclude
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", include=["*.safetensors"], exclude=["*.tmp"])
```

Для более сложной фильтрации используйте файл фильтра с `--filter-from` (или `filter_from` в Python):

```bash
>>> hf buckets sync ./data hf://buckets/username/my-bucket --filter-from filters.txt
```

Файл фильтров использует префиксы `+` (включить) и `-` (исключить). Строки, начинающиеся с `#`, являются комментариями. Правила оцениваются по порядку (действует первое подходящее правило):

```text
# filters.txt
- *.log
- *.tmp
+ *.safetensors
+ *.json
```

### Режимы сравнения

По умолчанию sync сравнивает файлы по размеру и времени изменения. Вы можете настроить это поведение:

```bash
# Only compare sizes (ignore modification times)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-times

# Only compare modification times (ignore sizes)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-sizes

# Only update files that already exist on the receiver (skip new files)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --existing

# Only create new files (skip files that already exist on the receiver)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-existing
```

Или через Python:

```py
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", ignore_times=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", ignore_sizes=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", existing=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", ignore_existing=True)
```

### Планирование и применение

Для критически важных операций вы можете просмотреть план синхронизации перед его выполнением:

```bash
# Step 1: Generate a plan file (nothing is transferred)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonl
Sync plan: ./data -> hf://buckets/username/my-bucket
  Uploads: 3
  Downloads: 0
  Deletes: 0
  Skips: 1
Plan saved to: sync-plan.jsonl

# Step 2: Review the plan file (JSONL format)
>>> cat sync-plan.jsonl

# Step 3: Apply the plan
>>> hf buckets sync --apply sync-plan.jsonl
```

Или через Python:

```py
# Step 1: Generate a plan file (nothing is transferred)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", plan="sync-plan.jsonl")

# Step 2: Review the plan file (JSONL format), then apply
>>> sync_bucket(apply="sync-plan.jsonl")
```

> [!TIP]
> Файл плана представляет собой JSONL-файл, в котором заголовок сопровождается строкой для каждой операции. Каждая операция включает действие (`upload`, `download`, `delete` или `skip`), путь к файлу и причину выполнения действия. Вы можете отредактировать этот файл вручную перед применением, но будьте внимательны к синтаксису.

### Тестовый прогон

Используйте `--dry-run` (или `dry_run=True` в Python), чтобы получить план синхронизации без выполнения каких-либо действий:

```bash
# Preview what would be synced
>>> hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq '.action'
```

Или через Python:

```py
>>> plan = sync_bucket("./data", "hf://buckets/username/my-bucket", dry_run=True)
>>> plan.summary()
{'uploads': 3, 'downloads': 0, 'deletes': 0, 'skips': 1, 'total_size': 4096}
```

> [!TIP]
> `--dry-run` выводит тот же формат JSONL, что и `--plan`, но печатает его в stdout, а не сохраняет в файл. Печатается только содержимое JSONL, что делает безопасным использование конвейеров (pipe).

### Говорливый и тихий режимы

```bash
# Show per-file operations
>>> hf buckets sync ./data hf://buckets/username/my-bucket --verbose

# Suppress all output
>>> hf buckets sync ./data hf://buckets/username/my-bucket --quiet
```

Или через Python:

```py
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", verbose=True)
>>> sync_bucket("./data", "hf://buckets/username/my-bucket", quiet=True)
```

## Дополнительно

Для задач более низкого уровня также доступны следующие методы:

- [get_bucket_paths_info()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.get_bucket_paths_info): Получает информацию о конкретных путях в бакете в одном пакетном запросе. Полезно, когда точно известно, для каких файлов нужны метаданные.

```py
>>> from huggingface_hub import get_bucket_paths_info
>>> for info in get_bucket_paths_info("username/my-bucket", ["file.txt", "models/model.safetensors"]):
...     print(info.path, info.size, info.xet_hash)
```

- [get_bucket_file_metadata()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.get_bucket_file_metadata): получает метаданные (размер и данные xet) для одного файла. Используется внутри [download_bucket_files()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_api#huggingface_hub.HfApi.download_bucket_files).

```py
>>> from huggingface_hub import get_bucket_file_metadata
>>> metadata = get_bucket_file_metadata("username/my-bucket", "models/model.safetensors")
>>> metadata.size
42000
```