# 레포지토리 시작하기

입문자 친화적인 이 가이드는 Hub에서 저장소를 생성하고 관리하는 데 필요한 기본 기술을 습득하는 데 도움이 됩니다. 각 섹션은 이전 섹션을 기반으로 하므로 원하는 위치에서 시작해 보세요!

## 요구 사항

이 문서는 웹 인터페이스와 터미널을 통해 저장소를 관리하는 방법을 보여줍니다. UI를 사용하는 경우 특별한 요구 사항은 없습니다. 터미널을 사용하려면 다음 설치 지침을 따르십시오.

CLI 명령어로 `git`을 아직 사용할 수 없다면, 해당 플랫폼에 [Git을 설치](https://git-scm.com/downloads)해야 합니다. 이미지와 모델 가중치와 같은 대용량 파일을 처리하는 데 사용되는 [Git-Xet도 설치](./xet/using-xet-storage#git-xet)해야 합니다.

> [!TIP]
> Git에서 대용량 파일을 다운로드하고 업로드하려면 [Git Xet](./xet/using-xet-storage#git) 확장을 설치해야 합니다.

Hub에 코드를 push하려면 인증이 필요합니다. 가장 쉬운 방법은 [`hf` CLI](https://huggingface.co/docs/huggingface_hub/guides/cli)를 설치한 후 login 명령을 실행하는 것입니다:

```bash
# Install hf:
#   brew install hf
#   or
#   pip install hf
hf auth login
```

**이 문서의 Getting Started 섹션에 포함된 내용은 동영상으로도 제공됩니다!**

## 리포지토리 생성

Hub의 웹 인터페이스를 사용하면 저장소를 쉽게 생성하고, 파일(대용량 파일 포함!)을 추가하고, 모델을 탐색하고, 차이를 시각화하는 등 다양한 작업을 수행할 수 있습니다. Hub에는 세 가지 유형의 저장소가 있으며, 이 가이드에서는 데모 목적으로 **모델 저장소**를 생성합니다. 모델, 데이터셋, Spaces의 생성 및 관리에 대한 정보는 각 해당 문서를 참고하세요.

1. 새 저장소를 만들려면 [huggingface.co/new](http://huggingface.co/new)을 방문하세요:

2. 저장소 소유자를 지정합니다. 이는 사용자 자신 또는 사용자가 소속된 조직 중 하나일 수 있습니다.

3. 모델 이름을 입력하세요. 이는 저장소 이름으로도 사용됩니다.

4. 모델을 공개로 할지 비공개로 할지 지정합니다.

5. 라이선스를 지정합니다. *License* 필드는 당분간 비워 두셔도 됩니다. 라이선스에 대한 자세한 내용은 [**Licenses**](repositories-licenses) 문서를 참고하세요.

모델 저장소를 생성한 후, 다음과 같은 페이지가 표시되어야 합니다:

Hub에서는 *Model Card* 생성을 안내하며, [**Model Cards 문서**](./model-cards)에서 이에 대해 자세히 알아볼 수 있습니다. 모델 저장소에 Model Card를 포함하는 것이 권장 사항이지만, 현재는 테스트 저장소만 생성하는 것이므로 이 단계를 건너뛸 수 있습니다.

## 리포지토리에 파일 추가 (Web UI)

웹 UI를 통해 저장소에 파일을 추가하려면 **Files** 탭을 선택하고 원하는 디렉터리로 이동한 다음 **Add file**을 클릭하세요. 새 파일을 만들거나 컴퓨터에서 파일을 직접 업로드하는 옵션이 제공됩니다.

### 새 파일 만들기

새 파일 생성을 선택하면 파일 이름 지정, 콘텐츠 추가, 변경 사항을 요약하는 메시지와 함께 파일을 저장할 수 있는 다음 편집기 화면으로 이동합니다. 새 파일을 저장소의 `main` 브랜치에 직접 커밋하는 대신 `Open as a pull request`를 선택하여 [Pull Request](./repositories-pull-requests-discussions)를 생성할 수 있습니다.

### 파일 업로드

_Upload file_를 선택하면 저장소에 대한 변경 사항을 요약한 메시지와 함께 업로드할 로컬 파일을 선택할 수 있습니다.

새 파일 생성과 마찬가지로, `Open as a pull request`를 선택하여 변경 사항을 저장소의 `main` 브랜치에 직접 추가하는 대신 [Pull Request](./repositories-pull-requests-discussions)를 생성할 수 있습니다.

## 리포지토리에 파일 추가 (CLI)[[cli]]

터미널에서 [`hf` CLI](https://huggingface.co/docs/huggingface_hub/guides/cli)를 사용하여 저장소에 파일을 직접 업로드할 수 있습니다. `hf upload` 명령을 사용하여 로컬 파일 또는 전체 폴더를 푸시하세요:

```bash
# Upload a single file to your model repo
hf upload your-username/your-model-name model.safetensors

# Upload an entire directory
hf upload your-username/your-model-name ./my-model-directory

# Upload to a dataset repo
hf upload your-username/your-dataset-name ./data --repo-type dataset
```

`hf` CLI는 대용량 파일을 자동으로 처리하므로 추가 설정이 필요하지 않습니다.

## 저장소(git)에 파일 추가[[terminal]]

### 리포지토리 클론

로컬 머신으로 저장소를 다운로드하는 작업은 *클로닝*이라고 합니다. 다음 명령어를 사용하여 저장소를 로드하고 해당 디렉터리로 이동할 수 있습니다:

```bash
git clone https://huggingface.co/<your-username>/<your-model-name>
cd <your-model-name>
```

또는 데이터셋 저장소의 경우:

```bash
git clone https://huggingface.co/datasets/<your-username>/<your-dataset-name>
cd <your-dataset-name>
```

다음 명령을 사용하여 SSH를 통해 클론할 수 있습니다:
```bash
git clone git@hf.co:<your-username>/<your-model-name>
cd <your-model-name>
```

변경 사항을 푸시하거나 비공개 저장소에 액세스하려면 [사용자 설정](https://huggingface.co/settings/keys)에 SSH 공개 키를 추가해야 합니다.

### 설정

이제 원하는 파일을 저장소에 자유롭게 추가할 수 있습니다! 🔥

10MB보다 큰 파일이 있나요? 이러한 파일은 [`git-xet`](./xet/using-xet-storage#git-xet)로 추적해야 하며, 다음 명령으로 초기화할 수 있습니다:

```bash
git xet install
```

Hugging Face를 사용하여 저장소를 생성하면, Hugging Face는 `.gitattributes` 파일에 일반적인 Machine Learning 대용량 파일의 공통 파일 확장자 목록을 자동으로 제공합니다. `git-xet`는 이 정보를 사용하여 대용량 파일의 변경 사항을 효율적으로 추적합니다. 다만, 파일 유형이 이미 처리되지 않은 경우 새로운 확장자를 추가해야 할 수 있습니다. `git xet track "*.your_extension"`를 사용하여 이를 수행할 수 있습니다.

### 파일 푸시

Git을 사용하여 새 파일과 기존 파일의 변경 사항을 *commit*이라는 변경 사항 묶음으로 저장할 수 있으며, 이는 프로젝트의 "수정판"으로 볼 수 있습니다. commit을 생성하려면, 변경 사항을 저장할 계획임을 Git에 알리기 위해 파일을 `add`한 다음 해당 변경 사항을 `commit`해야 합니다. Hugging Face Hub와 새 commit을 동기화하려면, commit을 Hub에 `push`합니다.

```bash
# Create any files you like! Then...
git add .
git commit -m "First model version"  # You can choose any descriptive message
git push
```

그리고 완료되었습니다! Hugging Face에서 최근 추가된 파일이 모두 포함된 저장소를 확인할 수 있습니다. 예를 들어, 아래 스크린샷에서는 사용자가 여러 파일을 추가했습니다. 참고로 이 예시에서 일부 파일의 크기가 `1.04 GB`이므로, 해당 저장소는 Xet을 사용하여 이를 추적합니다.

> [!TIP]
> 리포지토리를 HTTP로 클론한 경우, push 작업을 수행할 때마다 사용자 이름과 비밀번호를 입력하라는 요청을 받을 수 있습니다. 반복을 피하는 가장 간단한 방법은 HTTP 대신 [SSH로 전환](#cloning-repositories)하는 것입니다. 또는 HTTP를 사용해야 하는 경우, 사용자 이름과 비밀번호를 자동으로 입력하도록 [git credential helper](https://git-scm.com/docs/gitcredentials#_avoiding_repetition)를 설정하는 것이 도움이 될 수 있습니다.

## 리포지토리의 히스토리 보기

`add`-`commit`-`push` 사이클을 거칠 때마다 저장소는 파일에 적용한 모든 변경 사항을 추적합니다. UI를 통해 모델 파일과 커밋을 탐색하고 각 커밋에서 도입된 차이(또는 *diff*)를 확인할 수 있습니다. 히스토리를 보려면 **History: X commits** 링크를 클릭하세요.

개별 커밋을 클릭하여 해당 커밋에서 어떤 변경 사항이 도입되었는지 확인할 수 있습니다: