# 레포지토리 생성 및 관리

Hugging Face Hub는 git 저장소의 모음입니다. [Git](https://git-scm.com/)은 협업 환경에서 프로젝트를 쉽게 버전 관리하기 위해 소프트웨어 개발에서 널리 사용되는 도구입니다. 이 가이드에서는 Hub의 저장소와 상호 작용하는 방법을 보여 드리며, 특히 다음을 다룹니다:

- 리포지토리를 생성하고 삭제합니다.
- 브랜치와 태그 관리
- 리포지토리를 이름 변경합니다.
- 리포지토리 가시성을 업데이트하세요.
- 리포지토리의 로컬 복사본을 관리합니다.

> [!WARNING]
> GitLab/GitHub/Bitbucket과 같은 플랫폼에서 작업하는 데 익숙하시다면, `git` CLI를 사용하여 저장소를 클론(`git clone`)하고, 변경 사항을 커밋(`git add, git commit`)한 후 푸시(`git push`)하는 것이 첫 번째 직관일 수 있습니다. Hugging Face Hub를 사용할 때 이는 유효한 방법입니다. 그러나 소프트웨어 엔지니어링과 머신러닝은 동일한 요구 사항과 워크플로를 공유하지 않습니다. 모델 저장소는 다양한 프레임워크와 도구를 위한 대규모 모델 가중치 파일을 유지할 수 있으므로, 저장소를 클론하면 방대한 크기의 대규모 로컬 폴더를 유지 관리하게 될 수 있습니다. 그 결과, 자체 HTTP 메서드를 사용하는 것이 더 효율적일 수 있습니다. 자세한 내용은 [Git vs HTTP paradigm](../concepts/git_vs_http) 설명 페이지를 참고하세요.

Hub에서 저장소를 생성하고 관리하려면 머신에 로그인되어 있어야 합니다. 로그인되어 있지 않다면 [이 섹션](../quick-start#authentication)을 참조하세요. 이 가이드의 나머지 부분에서는 머신이 로그인되어 있다고 가정합니다.

## 리포지토리 목록 보기

[list_user_repos()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.list_user_repos)를 사용하여 계정 또는 조직의 모든 저장소(모델, 데이터셋, 스페이스, 버킷)를 나열할 수 있습니다. 결과에는 저장소 정보가 포함되며, 저장소 사용량 기준으로 정렬됩니다.

```py
>>> from huggingface_hub import list_user_repos

# List repos for the authenticated user
>>> repos = list(list_user_repos())
>>> for repo in repos[:3]:
...     print(f"{repo.id} ({repo.type}) - {repo.storage} bytes")
username/my-model (model) - 4828692480 bytes
username/my-dataset (dataset) - 598427559 bytes
username/my-space (space) - 120620146 bytes

# List repos from an organization
>>> repos = list(list_user_repos(namespace="my-org"))
```

또는 CLI를 통해 (기본적으로 30개 저장소를 표시하며, `--limit 0`을 사용하여 전체 목록을 표시할 수 있습니다):

```bash
>>> hf repos ls
>>> hf repos ls --namespace my-org --type model
>>> hf repos ls --limit 0 --format json | jq '.[].id'
```

## 레포지토리 생성 및 삭제

첫 단계는 저장소를 생성하고 삭제하는 방법을 아는 것입니다. 사용자 이름 네임스페이스에 있는 저장소(본인이 소유한 저장소)나 쓰기 권한이 있는 조직의 저장소만 관리할 수 있습니다.

### 리포지토리 생성

[create_repo()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.create_repo)를 사용하여 빈 저장소를 생성하고 `repo_id` 매개변수로 이름을 지정합니다. `repo_id`는 네임스페이스 뒤에 저장소 이름을 붙인 형태입니다: `username_or_org/repo_name`.

```py
>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model")
'https://huggingface.co/lysandre/test-model'
```

또는 CLI를 통해:

```bash
>>> hf repos create lysandre/test-model
Successfully created lysandre/test-model on the Hub.
Your repo is now available at https://huggingface.co/lysandre/test-model
```

기본적으로 [create_repo()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.create_repo)는 모델 저장소를 생성합니다. 하지만 `repo_type` 매개변수를 사용하여 다른 저장소 유형을 지정할 수 있습니다. 예를 들어, 데이터셋 저장소를 생성하려면:

```py
>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-dataset", repo_type="dataset")
'https://huggingface.co/datasets/lysandre/test-dataset'
```

또는 CLI를 통해:

```bash
>>> hf repos create lysandre/test-dataset --repo-type dataset
```

리포지토리를 생성할 때 `visibility` 파라미터를 사용하여 리포지토리 가시성을 설정할 수 있습니다:

```py
>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-private", visibility="private")
```

또는 CLI를 통해:

```bash
>>> hf repos create lysandre/test-private --private
```

나중에 저장소 가시성을 변경하려면 [update_repo_settings()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.update_repo_settings) 함수를 사용할 수 있습니다.

> [!TIP]
> Enterprise 플랜을 사용하는 조직의 구성원이라면 [create_repo()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.create_repo)에 `resource_group_id`를 매개변수로 전달하여 특정 리소스 그룹에 리포지토리를 생성할 수 있습니다. 리소스 그룹은 조직의 어떤 멤버가 특정 리소스에 접근할 수 있는지를 제어하는 보안 기능입니다. Hub의 조직 설정 페이지 URL에서 리소스 그룹 ID를 복사하여 확인할 수 있습니다(예: `"https://huggingface.co/organizations/huggingface/settings/resource-groups/66670e5163145ca562cb1988"` => `"66670e5163145ca562cb1988"`). 리소스 그룹에 대한 자세한 내용은 이 [가이드](https://huggingface.co/docs/hub/en/security-resource-groups)를 참고하세요.

`region`을 매개변수로 전달하여 특정 클라우드 리전에 저장소를 만들 수도 있습니다:

```py
>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model", region="us")
```

### 리포지토리 삭제

[delete_repo()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.delete_repo)를 사용하여 저장소를 삭제합니다. 이 작업은 되돌릴 수 없으므로 저장소를 삭제할지 신중하게 확인하세요!

삭제하려는 저장소의 `repo_id`를 지정하세요:

```py
>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset")
```

리포지토리가 존재하지 않는 경우 호출을 조용히 무시하려면 `missing_ok=True`를 전달하세요:

```py
>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset", missing_ok=True)
```

또는 CLI를 통해:

```bash
>>> hf repos delete lysandre/my-corrupted-dataset --repo-type dataset
```

### 리포지토리 복제

일부 경우에는 다른 사람의 저장소를 복사하여 자신의 사용 사례에 맞게 수정하고 싶을 수 있습니다. [duplicate_repo()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.duplicate_repo) 메서드를 사용하면 이를 수행할 수 있습니다. 이 메서드는 전체 저장소를 복제하며, 전체 git 히스토리를 보존합니다. 이 기능은 모델, 데이터셋, Spaces에 모두 적용됩니다. Spaces의 경우, 하드웨어, sleep-time, 저장소, 변수 및 secrets에 대한 설정을 직접 구성해야 합니다. 자세한 내용은 [Manage your Space](./manage-spaces) 가이드를 참고하세요.

```py
>>> from huggingface_hub import duplicate_repo

# Duplicate a Space
>>> duplicate_repo("multimodalart/dreambooth-training", repo_type="space", private=False)
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

# Duplicate a dataset
>>> duplicate_repo("openai/gdpval", repo_type="dataset")
RepoUrl('https://huggingface.co/datasets/nateraw/gdpval',...)
```

[create_repo()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.create_repo)와 마찬가지로, [duplicate_repo()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.duplicate_repo)는 `resource_group_id`를 받아 Enterprise 조직의 리소스 그룹 안에 복본을 직접 생성할 수 있습니다(`hf repos duplicate`에 `--resource-group-id` 사용).

git 히스토리는 즉시 복사되지만, [duplicate_repo()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.duplicate_repo)가 반환된 후에도 LFS/Xet 파일은 백그라운드에서 복사될 수 있습니다. 복사가 완료될 때까지 새 저장소에서 이러한 파일을 다운로드하면 실패할 수 있습니다. 복사가 아직 진행 중인지 확인하려면 반환 값의 `files_copy_pending`를 확인하세요:

```py
>>> from huggingface_hub import duplicate_repo
>>> repo_url = duplicate_repo("openai/gdpval", repo_type="dataset")
>>> repo_url.files_copy_pending
True
```

## Spaces 검색

Hub은 Spaces를 발견하기 위한 의미론적 검색 API를 제공합니다. [search_spaces()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.search_spaces)를 사용하여 자연어 쿼리로 검색할 수 있습니다:

```py
>>> from huggingface_hub import search_spaces
>>> results = list(search_spaces("generate image"))
>>> results[0].id
'mrfakename/Z-Image-Turbo'
```

자세한 내용과 필터링 옵션에 대해서는 [Spaces 관리](./manage-spaces#search-for-spaces) 가이드를 참조하세요.

## 파일 업로드 및 다운로드

…리포지토리를 생성했으므로 이제 변경 사항을 푸시하고 파일을 다운로드하는 데 관심이 있을 것입니다.

이 두 주제는 각각 별도의 가이드가 필요합니다. 저장소를 사용하는 방법에 대해서는 [업로드](./upload) 및 [다운로드](./download) 가이드를 참고하세요.

## 파일 복사

Hub에 이미 호스팅된 파일을 다운로드 및 재업로드하지 않고 한 저장소에서 다른 저장소(또는 동일한 저장소 내)로 복사하려면 [copy_files()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.copy_files)를 사용하세요. 개별 파일과 전체 폴더 모두 지원되며, Xet 또는 LFS로 추적되는 파일은 해시를 기반으로 서버 측에서 복사됩니다.

```py
>>> from huggingface_hub import copy_files

# Copy a single file from one repo to another
>>> copy_files(
...     "hf://username/source-model/config.json",
...     "hf://username/dest-model/config.json",
... )

# Copy an entire folder (a trailing "/" copies the folder *contents*, rsync-style)
>>> copy_files(
...     "hf://datasets/username/my-dataset/data/",
...     "hf://datasets/username/my-dataset-copy/data/",
... )
```

또는 통합 `hf cp` 명령어(또는 `hf repos cp`로도 사용 가능)를 통해 CLI로:

```bash
# Copy a single file between repositories
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json

# Copy a file from a repo to your local machine
>>> hf repos cp hf://username/my-model/config.json ./config.json

# Upload a local file to a repository
>>> hf repos cp ./model.safetensors hf://username/my-model/model.safetensors
```

> [!TIP]
> `copy_files`(그리고 `hf cp`)는 저장소에서 [Bucket](./buckets)로 파일을 복사하는 데에도 사용할 수 있습니다. *Bucket*에서 *저장소*로 복사하는 것은 지원되지 않습니다. 자세한 내용은 [Buckets](./buckets) 가이드를 참조하세요.

> [!WARNING]
> 서버 측 복사본은 동일한 [스토리지 리전](https://huggingface.co/docs/hub/storage-regions) 내에서만 작동합니다.

## Branches and tags

Git 저장소는 동일한 저장소의 서로 다른 버전을 저장하기 위해 브랜치를 사용하는 경우가 많습니다. 태그는 저장소의 특정 상태를 표시하는 데에도 사용할 수 있으며, 예를 들어 버전을 릴리스할 때 사용할 수 있습니다. 보다 일반적으로, 브랜치와 태그는 [git references](https://git-scm.com/book/en/v2/Git-Internals-Git-References)라고 불립니다.

### 브랜치와 태그 만들기

[create_branch()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.create_branch)와 [create_tag()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.create_tag)를 사용하여 새 브랜치와 태그를 만들 수 있습니다:

```py
>>> from huggingface_hub import create_branch, create_tag

# Create a branch on a Space repo from `main` branch
>>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker")

# Create a tag on a Dataset repo from `v0.1-release` branch
>>> create_tag("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.")
```

또는 CLI를 통해:

```bash
>>> hf repos branch create Matthijs/speecht5-tts-demo handle-dog-speaker --repo-type space
>>> hf repos tag create bigcode/the-stack v0.1.1 --repo-type dataset --revision v0.1-release -m "Bump release version."
```

[delete_branch()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.delete_branch) 및 [delete_tag()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.delete_tag) 함수를 동일한 방식으로 사용하여 브랜치 또는 태그를 삭제할 수 있으며, CLI에서는 각각 `hf repos branch delete` 및 `hf repos tag delete`를 사용할 수 있습니다.

### 모든 branch와 tag를 나열합니다

[list_repo_refs()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.list_repo_refs)를 사용하여 저장소의 기존 git refs를 나열할 수도 있습니다:

```py
>>> from huggingface_hub import list_repo_refs
>>> list_repo_refs("bigcode/the-stack", repo_type="dataset")
GitRefs(
   branches=[
         GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
         GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
   ],
   converts=[],
   tags=[
         GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
   ]
)
```

## 저장소 설정 변경

Repository에는 설정할 수 있는 몇 가지 설정이 있습니다. 대부분의 경우, 브라우저의 repo 설정 페이지에서 수동으로 설정하는 것이 좋습니다. repo를 설정하려면 해당 repo에 대한 쓰기 권한이 있어야 합니다(소유자이거나 조직의 일원이어야 합니다). 이 섹션에서는 `huggingface_hub`을 사용하여 프로그래밍 방식으로 설정할 수 있는 설정을 살펴보겠습니다.

일부 설정은 Spaces(하드웨어, 환경 변수 등)에 특화되어 있습니다. 이러한 설정을 구성하려면 [Manage your Spaces](../guides/manage-spaces) 가이드를 참고하세요.

### 가시성 업데이트

리포지토리는 공개 또는 비공개일 수 있습니다. 비공개 리포지토리는 해당 리포지토리가 속해 있는 조직의 멤버나 본인에게만 표시됩니다. 다음과 같이 리포지토리를 비공개로 변경할 수 있습니다.

```py
>>> from huggingface_hub import update_repo_settings
>>> update_repo_settings(repo_id=repo_id, private=True)
```

또는 CLI를 통해:

```bash
>>> hf repos settings lysandre/test-private --private true
```

### 게이트된 액세스 설정

리포지토리의 사용 방식을 더 세밀하게 제어할 수 있도록, Hub는 리포지토리 작성자가 자신의 리포지토리에 대해 **액세스 요청**을 활성화할 수 있도록 지원합니다. 활성화된 경우, 사용자는 파일에 액세스하려면 리포지토리 작성자와 연락처 정보(사용자 이름 및 이메일 주소)를 공유하는 데 동의해야 합니다. 액세스 요청이 활성화된 리포지토리를 **게이트드 리포지토리**라고 합니다.

[update_repo_settings()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.update_repo_settings)를 사용하여 저장소를 게이트드(gated)로 설정할 수 있습니다:

```py
>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> api.update_repo_settings(repo_id=repo_id, gated="auto")  # Set automatic gating for a model
```

또는 CLI를 통해:

```bash
>>> hf repos settings lysandre/test-private --gated auto
```

### 리포지토리 이름 변경

Hub에서 [move_repo()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.move_repo)를 사용하여 저장소 이름을 변경할 수 있습니다. 이 메서드를 사용하면 저장소를 사용자에서 조직으로 이동하는 것도 가능합니다. 이 경우 알아야 할 [몇 가지 제한 사항](https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo)이 있습니다. 예를 들어, 다른 사용자에게 저장소를 이전할 수 없습니다.

```py
>>> from huggingface_hub import move_repo
>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model")
```

또는 CLI를 통해:

```bash
>>> hf repos move Wauplin/cool-model huggingface/cool-model
```

## 커널 저장소

Hub는 컴퓨트 커널을 호스팅하기 위한 `"kernel"` 저장소 유형을 지원합니다. 이는 **완전히** 호환되는 저장소 유형이 아닙니다. 테스트되고 공식적으로 지원되는 메서드는 제한적입니다:

- [kernel_info()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.kernel_info)
- [hf_hub_download()](/docs/huggingface_hub/v2.4.0/ko/package_reference/file_download#huggingface_hub.hf_hub_download)
- [snapshot_download()](/docs/huggingface_hub/v2.4.0/ko/package_reference/file_download#huggingface_hub.snapshot_download)
- [list_repo_refs()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.list_repo_refs)
- [list_repo_files()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.list_repo_files)
- [list_repo_tree()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.list_repo_tree)

[create_repo()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.create_repo)와 [delete_repo()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_api#huggingface_hub.HfApi.delete_repo)도 호환되지만, Hub에서 허용된 소수의 사용자 및 조직으로 제한됩니다.

커널 저장소를 빌드, 게시 및 사용하려면 대신 전용 [`kernels`](https://github.com/huggingface/kernels) 패키지를 사용하세요. 자세한 내용은 [Kernels 문서](https://huggingface.co/docs/kernels/index)를 참조하세요.