> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/ko/knowledge-base/040-git-integration.md).

# Git 연동

**Overleaf의 Git 통합** 은(는) [프리미엄 기능입니다](/latex/ko/knowledge-base/120-overleaf-premium-features.md)입니다. Overleaf 프리미엄 기능은 다음 참가자에게 제공됩니다 [Overleaf Commons](https://www.overleaf.com/for/universities)의 그룹 [구독](https://www.overleaf.com/for/groups)의 소유자 및 [구독](https://www.overleaf.com/user/subscription/plans). Git 통합은 Overleaf Cloud와 Overleaf Server Pro(버전 4.0 이상)에서 사용할 수 있습니다.

### Overleaf Git 통합이란 무엇인가요?

Overleaf의 Git 통합을 사용하면 Overleaf 프로젝트에서 Git URL을 얻어 원격 Git 저장소(repo)처럼 다룰 수 있습니다. 프로젝트를 로컬 Git 저장소로 클론한 뒤 로컬에서 작업하고, 로컬 컴퓨터에서 프로젝트로 변경 사항을 푸시하거나 Overleaf 온라인 편집기에서 발생한 업데이트를 로컬 repo로 가져올 수 있습니다.

이 기능을 사용하면 온라인 작업이 어려운 경우 로컬에서 프로젝트 작업을 할 수 있고, Overleaf 프로젝트 작업 시 원하는 다른 로컬 편집기를 사용할 수 있으며, 다른 로컬 소프트웨어의 결과물을 Overleaf 프로젝트에 쉽게 추가할 수도 있습니다.

프로젝트의 Overleaf 메뉴에서 Git 옵션을 통해 Git URL과 클론 명령을 확인할 수 있습니다.

![프로젝트 메뉴 git.png](/files/86b68f95f79cb2717dd0c9429a62a680f069da13)

### Git 통합을 사용할 때 인증하는 방법

원격 Overleaf 프로젝트에 대해 clone, pull, push와 같은 Git 작업을 수행하면 인증하라는 요청이 표시됩니다.

Git에서 Overleaf 프로젝트에 접근하려면 Overleaf 토큰 기반 인증을 사용해야 합니다. 단계별 안내는 다음을 참조하세요: [토큰 기반 인증](/latex/ko/knowledge-base/042-git-integration-authentication-tokens.md).

### 프로젝트를 로컬 저장소로 클론하기

에서 [**메뉴**](/latex/ko/knowledge-base/148-using-the-overleaf-project-menu.md) 프로젝트 내에서 동기화 옵션에서 Git을 선택할 수 있습니다. 그러면 다음을 보여주는 대화상자가 열립니다. `git clone` 로컬 저장소를 만들 때 사용할 명령.

![프로젝트 메뉴 git.png](/files/86b68f95f79cb2717dd0c9429a62a680f069da13)

또는 프로젝트 URL(프로젝트 안에 있을 때 브라우저 주소 표시줄의 URL)에서 Git URL을 찾을 수도 있습니다.

#### Overleaf Cloud

Overleaf Cloud를 사용 중이고 Overleaf 프로젝트 URL이 다음과 같다면:

```
https://www.overleaf.com/project/1234567
```

그러면 프로젝트를 클론하는 데 사용할 Git URL은 다음과 같습니다.

```
https://git.overleaf.com/1234567
```

그리고 프로젝트를 로컬 Git 저장소로 클론하는 데 사용되는 명령은 다음과 같습니다:

```
git clone https://git.overleaf.com/1234567
```

**참고** : 사용자 이름과 비밀번호를 입력하라는 메시지가 표시될 수 있습니다. 다음을 참조하세요. [Git 통합 비밀번호 인증](/latex/ko/knowledge-base/043-git-integration-password-based-authentication.md)

#### Overleaf Server Pro(버전 4.0 이상)

**참고** : Server Pro에서는 Git-브리지 통합이 기본적으로 활성화되어 있지 않습니다. 활성화 방법은 다음 가이드를 참조하세요. [Git 통합](https://github.com/overleaf/overleaf/wiki/Git-Integration) 설명서

Overleaf Server Pro를 사용 중이고 프로젝트 URL이 다음과 같다면:

```
https://<SHARELATEX_SITE_URL>/project/1234567
```

그러면 프로젝트를 클론할 때 사용되는 Git URL은 다음과 같습니다:

```
https://git@<SHARELATEX_SITE_URL>/git/1234567
```

그리고 Git 명령줄을 사용해 프로젝트를 로컬 Git 저장소로 클론하는 데 사용되는 명령은 다음과 같습니다:

```
git clone git@<SHARELATEX_SITE_URL>/git/1234567
```

**참고** : 비밀번호를 입력하라는 메시지가 표시될 수 있습니다. 다음을 참조하세요: [Git 통합 인증 토큰](/latex/ko/knowledge-base/042-git-integration-authentication-tokens.md)

### 기존 Git 저장소에서 Overleaf 프로젝트 만들기

기존 저장소가 있다면 Overleaf 프로젝트를 원격 저장소로 추가할 수 있습니다. 시작하려면 아래의 몇 가지 명령을 실행해야 합니다. Overleaf는 각 프로젝트에 대해 하나의 선형 히스토리만 지원한다는 점에 유의하세요. Git 통합은 브랜치 수를 하나로 제한하여 이 제약을 강제합니다. 그 하나의 브랜치는 현재 하드코딩되어 `master`.

1. 라고 불립니다. 먼저, 컴퓨터에 `my-paper`라는 폴더의 Git 저장소가 있다고 가정합니다. (GitHub, GitLab, Bitbucket 등에서 호스팅될 수도 있지만, 로컬에도 클론되어 있어야 합니다.)
2. 만들기 [새 프로젝트](/latex/ko/knowledge-base/031-creating-a-document-in-overleaf.md) 를 Overleaf에서 만듭니다. 프로젝트의 모든 내용은 덮어써지므로, 이 프로젝트를 만들 때 'Blank' 프로젝트 옵션을 사용하고 `main.tex` 파일을 Overleaf에서 삭제하세요.
3. 프로젝트의 Git URL을 찾습니다( [위의](#cloning-your-project-as-a-local-repository)).

   ![Git-bridge-url.png](/files/aa794a3d635960f935f74bf1930738a4de28e284)
4. 프로젝트의 Git URL을 로컬 프로젝트의 원격 저장소로 추가합니다.

   ```
   $ cd my-paper
   $ git remote add overleaf <GIT-URL>
   ```

   (예시 링크가 아니라 본인의 링크를 사용하세요.)
5. Overleaf 프로젝트에서 최신 내용을 가져와 master 브랜치에 병합합니다.

   ```
   $ git checkout master
   $ git pull overleaf master --allow-unrelated-histories --rebase=false
   ```
6. 프로젝트를 Overleaf로 푸시합니다.

   ```
   $ git push overleaf master --set-upstream
   ```

   로컬에서 다른 브랜치 이름을 사용하고 싶다면, 예를 들어 `my-branch`라면, 별칭을 사용해 변경 사항을 푸시할 수 있습니다:

   ```
   $ git push overleaf my-branch:master
   ```
7. Overleaf에서 프로젝트를 방문하세요. 변경 사항이 반영되어 있어야 합니다. (Overleaf 프로젝트 메뉴를 열어 어떤 파일이 주 문서 파일로 설정되었는지 확인하고, 필요하면 이 초기 선택을 변경해야 할 수도 있습니다.)

### Git 커밋과 Overleaf Git 통합

Overleaf에는 내부 [히스토리 시스템](/latex/ko/more-topics/49-using-the-history-feature.md) 이 있어 Overleaf 프로젝트 내에서 동시에 협업할 수 있습니다. 이는 Git과 같은 것이 아니므로, Overleaf Git 통합은 본질적으로 Overleaf의 히스토리 및 버전 관리 메커니즘을 Git으로 변환하는 것입니다. 이를 통해 많은 Git 지원 사용 사례를 사용할 수 있지만, Overleaf를 완전한 Git 구현처럼 사용할 수는 없습니다.

#### 커밋은 언제 생성되나요?

다음 명령을 실행할 때 `pull` 또는 `fetch` 를 실행하고 현재 프로젝트 상태에 대한 커밋이 없으면 새 커밋이 동적으로 생성됩니다. 파일을 로컬 저장소에서 Overleaf 원격 저장소로 `push` 하면 그때도 커밋이 생성되며, 이후 Overleaf 프로젝트를 다시 클론할 때 확인할 수 있습니다. Overleaf에서 당신이나 다른 사용자가 편집 중일 때는 필요할 때까지 커밋이 자동으로 생성되지 않습니다.

#### 커밋 강제 생성

Overleaf 히스토리의 특정 지점에서 커밋이 생성되도록 강제하고 싶다면, [버전 레이블 지정](/latex/ko/more-topics/49-using-the-history-feature.md) 을 통해 할 수 있습니다. 레이블이 지정된 버전은 즉시 git pull을 하지 않더라도 자체 커밋 해시를 갖게 됩니다. 커밋은 레이블이 지정되는 Overleaf 히스토리 지점보다 더 최근에 다른 커밋이 생성된 적이 없을 때만 레이블에서 생성됩니다.

#### 저자 추적

Overleaf Git 통합의 커밋은 필요 시점에 생성되는 특성 때문에, 커밋이 생성되기 전에 Overleaf 쪽에서 여러 변경이 있었다면 가장 최근 변경의 작성자가 해당 커밋의 작성자로 표시됩니다.

공동 저자와 작업할 때는 각 협업자가 중요한 업데이트를 완료할 때마다 레이블을 만들어(커밋을 생성하여) 두는 것이 도움이 됩니다. 이렇게 하면 Git에서 보이는 커밋 시퀀스가 Overleaf에서 일어나는 변경 사항을 가장 잘 반영하게 됩니다.

### 다른 원격 저장소와 동기화하기

Overleaf의 Git 통합을 사용하면 Overleaf 프로젝트를 로컬 저장소의 원격 저장소처럼 사용할 수 있습니다. 그러나 GitHub, GitLab 또는 다른 Git 호스팅 서비스에 있는 다른 원격 저장소와 Overleaf 프로젝트를 동기화하고 싶을 수도 있습니다.

GitHub에 호스팅된 저장소(<https://github.com/>)와 프로젝트를 동기화하는 경우 Overleaf의 직접 [GitHub 동기화](/latex/ko/knowledge-base/044-github-synchronization.md) 기능을 사용하는 것이 좋습니다.

GitLab, GitHub Enterprise 또는 다른 호스트와 프로젝트를 동기화하는 경우 Overleaf Git 통합을 사용해 중간 로컬 저장소를 설정할 수 있습니다.

위의 안내에 따라 [프로젝트 클론하기](#cloning-your-project-as-a-local-repository) 또는 [프로젝트를 기존 저장소에 연결하기](#creating-an-overleaf-project-from-an-existing-git-repository)를 수행하면 Overleaf와 변경 사항을 push/pull할 수 있는 로컬 저장소를 갖게 됩니다. 그런 다음 이 저장소에 호스팅된 저장소를 가리키는 두 번째 원격 저장소를 추가할 수 있습니다. 로컬 저장소는 Git 호스트와 Overleaf 프로젝트 둘 다를 가리키도록 두 개의 원격 저장소를 가져야 합니다.

Overleaf 프로젝트와 Git 저장소 사이에 직접 연결은 없지만, 이를 통해 둘을 동기화된 상태로 유지할 수 있습니다.

![Git other remote.png](/files/e274f997797ca05060a56ee25bf77e480145e165)

### Overleaf 프로젝트를 Git 서브모듈로 추가하기

Overleaf의 각 프로젝트는 독립적인 Git 저장소처럼 동작하지만, 여러 프로젝트를 하나의 Git 저장소로 구성하고 싶다면 각 프로젝트의 저장소를 일반적인 방식으로 Git 서브모듈로 추가할 수 있습니다. 그런 다음 각 서브모듈 저장소를 개별적으로 Overleaf로/에서 push 및 pull할 수 있으면서도, 더 큰 프로젝트 안에 서브모듈로 함께 묶어둘 수 있습니다.

**참고:** Overleaf 프로젝트는 다른 저장소의 서브모듈이 될 수 있지만, Overleaf 프로젝트 자체에는 다른 서브모듈을 포함할 수 없습니다.

### 알려진 제한 사항

**브랜치**: Overleaf Git 시스템은 브랜칭을 지원하지 않습니다.

**심볼릭 링크**: Overleaf Git 시스템은 심볼릭 링크를 잘 처리하지 못합니다. 심볼릭 링크는 Overleaf 프로젝트로 push할 수는 있지만 일반 파일로 변환되며, 다음에 프로젝트를 pull할 때 로컬 심볼릭 링크를 덮어씁니다.

**태그**: Overleaf Git 시스템은 태깅을 지원하지 않습니다.

**파일 권한**: Overleaf Git 시스템은 실행 권한을 보존하지 않습니다. 이를 우회하려면 로컬 저장소 복제본에서 `git config core.fileMode false` 를 실행하면 됩니다. 그런 다음 영향을 받은 파일의 실행 권한을 다시 설정할 수 있습니다. 이렇게 하면 이후 Git 작업에서 다시 수정되지 않습니다.

**Git LFS:** Overleaf 프로젝트는 Git Large File Storage를 지원하지 않습니다.

**Git 서브모듈:** Overleaf 프로젝트는 다른 저장소 안에서 Git 서브모듈로 동작할 수 있지만, 다른 Git 서브모듈을 포함할 수는 없습니다. 다른 프로젝트의 파일을 참조하려면 [다른 프로젝트에서 추가 기능](/latex/ko/knowledge-base/009-can-i-share-files-e.g.-.bib-and-some-graphics-across-my-projects.md).

**폴더 이름 바꾸기**: 사용자가 폴더 이름을 바꾸고 그 변경 사항을 Overleaf로 push하면, 프로젝트에는 새 폴더와 함께 이전 이름의 빈 폴더도 남게 됩니다. (예를 들어 images/를 img/로 이름을 바꾸면 프로젝트에는 두 개의 폴더가 남습니다. 이미지 파일이 들어 있는 img/와 비어 있는 images/입니다. 사용자가 한 커밋에서 폴더 이름을 바꾸고 동시에 이전 폴더와 같은 이름의 새 파일을 만들면 문제가 발생할 수 있습니다. Overleaf Git 시스템은 이 커밋을 거부합니다. 이 경우 커밋을 두 부분으로 나누고 남아 있는 폴더를 삭제하는 것을 권장합니다.

**파일 이름 바꾸기 및 파일 이동:** 로컬 저장소에서 파일 이름을 바꾸면 Overleaf 측에서는 삭제와 생성으로 처리됩니다. 이로 인해 Overleaf 측의 파일에 연결된 메타데이터가 손실되어 추적된 변경 사항과 댓글이 삭제될 수 있습니다. Overleaf에서 추적된 변경 사항이나 댓글이 있는 파일을 Git 쪽에서 이동하거나 이름을 바꾸는 것은 권장하지 않습니다.

**수정 내용 추적 및 댓글**: 안타깝게도 Git에서 Overleaf로의 push는 수정 내용 추적과 댓글의 손실 또는 위치 변경을 초래할 수 있습니다. 따라서 Git의 적극적인 사용과 수정 내용 추적 및/또는 댓글 사용을 함께 섞어 쓰는 것은 권장하지 않습니다.

### 문제 해결

#### 저장소를 찾을 수 없음 오류

저장소를 찾을 수 없음 오류가 표시된다면 잘못된 URL을 사용하고 있을 가능성이 큽니다. 올바른 URL은 프로젝트 안의 메뉴에서 Git 옵션을 클릭하면 찾을 수 있습니다. Overleaf Cloud에서는 Git 통합이 유료 기능이므로, 프로젝트 소유자가 Overleaf 유료 구독을 보유했거나 해당 기능에 대한 접근 권한을 부여받은 경우에만 사용할 수 있습니다(예: 초기 베타 테스트에 참여한 경우).

#### 인증 실패 오류

다음에 대한 문제 해결 안내를 참조하세요. [Git 통합 인증 토큰](/latex/ko/knowledge-base/042-git-integration-authentication-tokens.md) 또는 [Git 통합 비밀번호 인증](/latex/ko/knowledge-base/043-git-integration-password-based-authentication.md) 사용 중인 로그인 방법에 따라

#### 속도 제한

Git 작업을 수동으로 실행할 때는 일반적으로 Git Bridge 속도 제한이 발생하지 않습니다. 일부 Git 클라이언트는 변경 사항을 위해 원격 저장소를 자동으로 폴링하도록 설정할 수 있으며, 이 경우 일부 상황에서 속도 제한 오류가 발생할 수 있습니다. 일반적으로 자동 폴링을 비활성화하거나 Git 작업 빈도를 줄이면 이러한 문제를 해결할 수 있습니다.

#### 참조 푸시 실패

원격 프로젝트로 일부 참조를 푸시하지 못하는 원인은 [프로젝트의 파일 크기 또는 개수 제한을 초과했거나](/latex/ko/knowledge-base/119-overleaf-plan-limits.md) 지원되지 않는 파일 형식(예: 심볼릭 링크 또는 LFS)을 포함했기 때문일 수 있습니다. 커밋에 문제가 있는 파일이 있는지 위에 나열된 알려진 제한 사항을 검토하세요.

경우에 따라 **postBuffer** 설정을 늘리면 로컬 저장소에서 Overleaf 프로젝트로 참조를 푸시하는 실패를 해결할 수 있습니다.

먼저 다음 명령으로 현재 설정을 확인할 수 있습니다:

```
     git config http.postBuffer
```

출력이 없으면 기본값인 1MB가 사용되고 있다는 뜻입니다.

다음으로, 다음 명령을 시도해 보세요.

```
     git config --global http.postBuffer 10485760
```

그러면 값이 대신 10MB로 설정됩니다.

이제 커밋을 다시 푸시해 볼 수 있습니다(원래 프로젝트나 새 프로젝트 중 어느 쪽이든). 그래도 작동하지 않으면 이전 설정으로 되돌리거나 다음 명령으로 설정을 제거할 수 있습니다:

```
     git config --global --unset http.postBuffer
```

#### 시간 초과

많은 변경 사항을 포함한 Git 커밋은 시간 초과를 유발할 수 있습니다. 시간 초과가 발생하면 커밋을 더 작은 변경으로 나누어 보세요. 문제가 계속되면 위에서 설명한 대로 **postBuffer** 를 10MB로 설정하는 것을 고려하세요.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://overleaf-pro.ayaka.space/latex/ko/knowledge-base/040-git-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.