> 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/044-github-synchronization.md).

# GitHub 동기화

**GitHub 동기화** 은(는) [프리미엄 기능입니다](/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).

요약

GitHub 동기화 기능을 사용하면 Overleaf 프로젝트를 Overleaf 프로젝트의 원격 저장소 역할을 하는 GitHub 저장소에 직접 연결할 수 있으며, 두 곳 사이에서 변경 사항을 푸시하고 가져올 수 있습니다. GitHub 동기화는 다음에서만 사용할 수 있습니다 [GitHub.com](https://www.github.com) 그리고 다른 GitHub Enterprise 설치본에 연결하는 데는 사용할 수 없습니다.

Overleaf 프로젝트는 기존 GitHub 저장소에서 새 Overleaf 프로젝트를 생성하거나 기존 Overleaf 프로젝트에서 새 GitHub 저장소를 생성하여 GitHub 저장소와 동기화할 수 있습니다. 기존 Overleaf 프로젝트를 기존 GitHub 저장소와 동기화하는 것은 불가능합니다.

* GitHub 계정을 Overleaf 계정에 연결하면 GitHub 동기화가 활성화됩니다
* 새 프로젝트는 기존 GitHub 저장소에서 만들 수 있습니다
* 기존 Overleaf 프로젝트를 기반으로 GitHub에서 저장소를 만들 수 있습니다
* 연결된 프로젝트와 저장소는 다음을 사용하여 동기화 상태로 유지됩니다 **GitHub** 프로젝트의 **메뉴**

### Overleaf 계정을 GitHub 계정에 연결하기

GitHub 동기화 기능을 사용하려면 Overleaf 계정을 GitHub 계정에 연결해야 합니다. Overleaf의 [계정 설정](https://www.overleaf.com/user/settings). 또한 귀하의 계정과 연결된 특정 저장소나 조직에 Overleaf가 연결할 수 있는 능력은 GitHub에서 구성한 권한 설정에 따라 달라질 수 있습니다.

### GitHub 저장소에서 새 Overleaf 프로젝트 만들기

새 프로젝트 메뉴에서 GitHub 옵션을 선택할 수 있습니다. 그러면 GitHub 권한 설정에 따라 GitHub 계정을 통해 Overleaf에서 볼 수 있는 저장소 목록이 표시됩니다.

![새 GitHub 만들기.png](/files/f0f0b7aca8a1984b48cb4d50231606c93a1f79fd)

기존 GitHub 저장소에서 새 Overleaf 프로젝트를 만들 때 알아둘 몇 가지 사항이 있습니다.

* Overleaf 프로젝트에는 크기 제한이 적용되므로 더 큰 GitHub 저장소를 사용해 프로젝트를 만들지 못할 [이 페이지](/latex/ko/knowledge-base/119-overleaf-plan-limits.md) Overleaf 프로젝트의 파일 크기 및 파일 수 제한에 대한 개요는 다음을 참조하십시오.
* Overleaf 프로젝트는 Git 서브모듈이나 Git LFS를 지원하지 않습니다.

### Overleaf 프로젝트에서 새 GitHub 저장소 만들기

Overleaf 프로젝트 메뉴에서 동기화 옵션 중 하나로 GitHub를 선택할 수 있습니다. 그러면 Overleaf 프로젝트와 동기화할 새 GitHub 저장소의 이름을 입력할 수 있는 대화 상자가 표시됩니다.

![프로젝트 메뉴 github.png](/files/f9e9667011150f842087ae8d72b22785aebb5cfb)

### GitHub와 동기화하기

GitHub와 Overleaf 간의 동기화는 자동으로 이루어지지 않으며, 동기화 옵션은 **GitHub** 프로젝트의 **메뉴**. 이때 GitHub 모달에는 GitHub에서 가져올 새 변경 사항이 있는지 표시됩니다. 또한 언제나 변경 사항을 GitHub로 푸시하는 옵션이 제공됩니다(참고: 이 옵션은 Overleaf와 GitHub가 모두 최신 상태인 경우에도 표시됩니다).

![GitHub 모달 이미지](/files/a91842f13dee33c3ffa70f9c599a5d620a9eca6d)

Overleaf 변경 사항을 GitHub로 푸시 버튼을 클릭하면 GitHub 커밋이 생성됩니다. 이때 선택적으로 커밋 메시지를 입력할 수 있습니다.

* GitHub에서 가져온 Overleaf 기록의 변경 사항은 작성자가 익명으로 표시됩니다.
* Overleaf에서 가져온 GitHub 기록의 변경 사항은 연결된 GitHub 계정 소유자가 작성한 것으로 표시됩니다.

### 병합 충돌 해결

Overleaf와 GitHub 양쪽에서 변경이 이루어지면 Git이 이를 자동으로 병합하는 방법을 파악하지 못할 수 있습니다. 예를 들어 공동 작업자가 Overleaf에서 한 줄을 변경하고 귀하가 GitHub 저장소에서 같은 줄을 변경한 경우, Overleaf는 어떤 버전을 유지할지 선택하지 못할 수 있습니다.

그런 경우 기본 브랜치로 병합하는 대신 새 브랜치를 저장소에 푸시합니다. 이 브랜치는 설명적인 이름(브랜치 생성 날짜와 시간을 포함)을 가지며, Overleaf에 있는 문서 버전을 포함합니다. GitHub와 동기화를 시도하면 해결해야 할 병합 충돌이 있음을 알리는 메시지가 표시됩니다.

![GitHub 병합 충돌 대화 상자](/files/17575a5624b01997b4a56c619b61d1fe75764118)

다시 동기화하려면 Overleaf 브랜치를 기본(디폴트) 브랜치로 병합해야 합니다. 컴퓨터에서 두 브랜치를 가져와 git이나 다른 도구로 병합한 다음 결과를 GitHub에 다시 푸시하면 됩니다. 또는 Overleaf 브랜치에서 풀 리퀘스트를 생성하고 충돌 해결 기능을 사용하여 GitHub에서 직접 병합할 수도 있습니다. 두 방법 모두 다음에서 설명합니다 [GitHub 문서](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts).

### GitHub 조직의 저장소에 액세스하기

연결된 GitHub 계정과 관련된 저장소와 Overleaf 프로젝트를 동기화할 수 있으며, 회원으로 속한 GitHub 조직의 프로젝트와도 동기화할 수 있습니다. 연결된 GitHub 조직의 저장소와 동기화하려면 해당 조직이 Overleaf OAuth 애플리케이션이 액세스할 수 있도록 권한을 부여해야 합니다.

* 조직 구성원인 경우 다음에 설명된 단계를 따를 수 있습니다 [여기](https://help.github.com/articles/requesting-organization-approval-for-oauth-apps/) Overleaf 앱이 조직에 액세스할 수 있도록 액세스를 요청합니다.
* 조직 소유자인 경우 다음에 설명된 단계를 따를 수 있습니다 [여기](https://help.github.com/articles/approving-oauth-apps-for-your-organization/) 조직에 대해 Overleaf 앱을 승인할 수 있습니다.

### GitHub 동기화 파일 제한

Overleaf 프로젝트는 개별 크기 제한뿐만 아니라 다음에 명시된 프로젝트 내 총 파일 수 제한도 적용됩니다 [여기](/latex/ko/knowledge-base/119-overleaf-plan-limits.md). Git 자체는 한 번의 커밋으로 수천 개의 파일을 변경하는 것을 처리할 수 있지만, Overleaf의 GitHub 동기화 기능에서 사용하는 GitHub API도 푸시하거나 가져올 수 있는 파일 수에 제한을 둡니다. 개별 커밋의 파일 수는 100개 미만으로, GitHub 동기화를 사용하는 경우 전체 프로젝트 크기는 100MB 미만으로 제한하는 것이 좋습니다. 이보다 큰 프로젝트도 작동할 수 있지만, 잠재적인 동기화 문제를 피하려면 이 제한 내에서 사용하는 것을 권장합니다.

### 프로젝트를 저장소에서 연결 해제하기

기존 GitHub 저장소 하나에서 여러 프로젝트를 만드는 것은 가능하지만, **특정 프로젝트에 연결된 저장소를 변경하는 것은 불가능합니다**. 프로젝트가 저장소에 연결되면 연결을 해제하여 새 저장소를 만드는 데 사용할 수 없습니다. 특정 프로젝트에서 새 저장소를 만들어야 하는 경우 프로젝트의 새 복사본을 만든 다음 그 복사본에서 새 저장소를 만들어야 합니다.

### 알려진 제한 사항

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

**심볼릭 링크**: Overleaf Git 시스템은 심볼릭 링크를 처리하지 않습니다. 심볼릭 링크는 Overleaf 프로젝트로 푸시할 수 있지만 일반 파일로 변환되며, 다음에 프로젝트를 가져올 때 로컬 심볼릭 링크를 덮어쓰게 됩니다.

**파일 권한**: Overleaf Git 시스템은 실행 권한을 유지하지 않습니다. GitHub 동기화와 함께 사용할 때 GitHub에서 실행 비트가 설정된 파일이 Overleaf와 동기화되면, 파일 권한을 재설정하기 위해 Overleaf에서 자동 커밋이 트리거됩니다.

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

**Git 서브모듈**: Overleaf 프로젝트는 다른 저장소 내에서 Git 서브모듈로 작동할 수 있지만, 다른 Git 서브모듈을 포함할 수는 없습니다. 다른 프로젝트의 파일을 참조하려면 다른 프로젝트에서 추가 기능을 사용하는 것이 좋습니다.

**수정 내용 추적 및 댓글**: 안타깝게도 GitHub에서 Overleaf로 가져오면 추적 변경 내용과 댓글이 손실되거나 이동될 수 있습니다. 따라서 GitHub에서의 적극적인 작업과 추적 변경 내용 및/또는 댓글 사용을 함께 섞는 것은 권장하지 않습니다.

**GitHub Enterprise 또는 GitLab과의 직접 동기화:** Overleaf에서 사용하는 GitHub API는 github.com에 호스팅된 저장소에만 연결할 수 있습니다. 다음을 사용하여 다른 제공업체에 호스팅된 프로젝트와 간접적으로 동기화할 수 있습니다 [Overleaf Git 통합](/latex/ko/knowledge-base/040-git-integration.md) 기능을 사용하는 것이 좋습니다.

**기존 프로젝트를 기존 저장소에 연결하기**: 기존 Overleaf 프로젝트를 기존 GitHub 저장소와 동기화하는 것은 불가능합니다.

**GitHub로 푸시한 변경의 작성자**: Overleaf가 인식하는 유일한 GitHub 사용자는 Overleaf 계정에 연결되어 있으며 해당 프로젝트를 소유한 사용자의 GitHub 계정입니다. 모든 커밋은 해당 사용자의 신원을 사용하여 커밋을 명시적으로 생성하는 GitHub API를 통해 만들어집니다. 따라서 모든 커밋은 GitHub Git 기록에서 연결된 사용자로부터 온 것으로 표시됩니다. Overleaf의 기록에서는 변경 사항이 "익명( GitHub 경유)"으로 표시됩니다.

**Git 기록 및 Overleaf 기록:** Overleaf 측의 변경 사항은 GitHub 커밋과 일대일로 대응되지 않습니다. 여러 사용자가 Overleaf 측에서 변경을 할 수 있지만, 동기화가 시작되면 이러한 변경 사항은 GitHub에 연결된 사용자 아래 하나의 커밋으로 묶입니다.


---

# 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/044-github-synchronization.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.