> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parallelane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 푸시 · 풀 · 페치

> 원격 동기화와 ahead/behind 배지

원격 저장소와 로컬을 동기화하는 세 가지 작업입니다. 우측 사이드바 최상단 툴바의 아이콘 버튼으로 실행하며, 각 버튼에는 지금 보낼/받을 커밋 수가 배지로 표시됩니다.

<Note>
  `origin` 리모트가 없는 저장소에서는 세 버튼이 모두 비활성이고, 페치 버튼의 툴팁이 \*\*원격 없음(No remote)\*\*으로 바뀝니다. 브랜치가 아닌 커밋에 체크아웃한 상태(detached HEAD)에서는 푸시·풀만 비활성됩니다.
</Note>

## ahead/behind 카운트 배지 읽기

우측 사이드바 툴바의 **푸시**(위쪽 화살표)와 **풀**(아래쪽 화살표) 버튼에는 각각 작은 알약형 배지가 붙습니다. 원격 작업 전에 몇 개의 커밋이 오갈지 한눈에 파악할 수 있습니다.

<CardGroup cols={2}>
  <Card title="푸시 배지 = ahead" icon="arrow-up">
    로컬 브랜치가 원격 브랜치보다 앞선 커밋 수입니다. 즉 **보낼 커밋**의 개수입니다.
  </Card>

  <Card title="풀 배지 = behind" icon="arrow-down">
    원격 브랜치가 로컬 브랜치보다 앞선 커밋 수입니다. 즉 **받을 커밋**의 개수입니다.
  </Card>
</CardGroup>

<Note>
  카운트가 0이면 배지는 표시되지 않습니다. 보낼 커밋이나 받을 커밋이 있을 때만 나타나며, 100 이상은 `99+`로 축약됩니다.
</Note>

비교 기준은 **브랜치 자신의 원격 브랜치**(`<리모트>/<브랜치>`)입니다. 어느 리모트를 볼지는 `branch.<브랜치>.remote` 설정을 따르고, 설정이 없으면 `origin`을 씁니다. 아직 원격에 올리지 않은 새 브랜치처럼 짝이 되는 원격 브랜치가 없으면 받을 커밋은 0으로 두고, 보낼 커밋은 **그 리모트의 어떤 원격 추적 브랜치에도 없는 커밋 수**로 셉니다. 원격 추적 브랜치가 하나도 없으면 양쪽 모두 0입니다.

좌측 저장소 패널의 브랜치 트리와 워크트리 행에도 같은 값이 `↑N ↓N`으로 표시됩니다.

<Frame>
  <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/remote-ahead-behind.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=e40768d61221710623a9f684b67ce079" alt="좌측 저장소 패널의 브랜치 트리와 워크트리 행에 보낼·받을 커밋 수가 ↑N ↓N으로 표시된 화면" width="2266" height="1784" data-path="images/remote-ahead-behind.png" />
</Frame>

## 푸시

로컬 커밋을 원격 브랜치로 올립니다. 현재 선택된 워크트리의 현재 브랜치가 대상입니다.

<Steps>
  <Step title="푸시 버튼 클릭">
    우측 사이드바 툴바에서 **푸시** 버튼을 눌러 푸시 모달을 엽니다.
  </Step>

  <Step title="대상과 옵션 확인">
    모달의 **Push 대상**에 `<리모트>/<브랜치> ← <브랜치>` 형태의 대상과 보낼 커밋 수(ahead)가 표시됩니다. 필요하면 옵션을 켭니다.

    * **강제 (--force-with-lease)** — 원격 기록을 재작성해 강제로 밀어 넣습니다. rebase/amend 후 다시 올릴 때 사용합니다. 켜면 모달에 경고가 나타나고 실행 버튼이 위험(빨강) 스타일로 바뀝니다.
    * **태그 푸시 (--tags)** — 로컬 태그도 함께 올립니다. 켜면 이 브랜치와 무관한 태그까지 모두 올라간다는 경고와 함께 실제로 푸시될 로컬 태그 목록이 모달에 표시됩니다. 기본값은 [설정 → ParalleLane → Git](/settings/preferences)의 **기본적으로 모든 태그 push**를 따릅니다.

    업스트림이 설정되지 않은 브랜치라면 "업스트림을 `<remote>/<branch>`로 설정합니다" 안내가 나타나며, 푸시 시 자동으로 업스트림이 등록됩니다.

    리모트가 2개 이상인 저장소에서는 **Remote** 버튼 그룹이 함께 나타나 대상 리모트를 고를 수 있습니다. 기본값은 [설정 → 프로젝트(Projects) → Git](/remote/remotes)에서 지정한 **기본 remote**입니다.
  </Step>

  <Step title="푸시 실행">
    **푸시** 버튼을 누르면 모달이 닫히고 진행·결과가 토스트로 표시됩니다. 완료되면 그래프와 배지가 갱신됩니다.
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/remote-push-dialog.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=049a5e6252a52f27adb62cfc10e1083e" alt="origin/브랜치 대상과 보낼 커밋 수, 강제 푸시·태그 푸시 옵션을 보여주는 푸시 다이얼로그" width="886" height="688" data-path="images/remote-push-dialog.png" />
</Frame>

<Warning>
  **강제 푸시**는 `--force-with-lease`를 사용해도 원격 기록이 재작성될 수 있습니다. 공유 브랜치에서는 다른 사람의 커밋을 덮어쓸 수 있으니 주의하세요. 여러 명과 협업 중이라면 강제 푸시 전에 팀과 상의하세요.
</Warning>

<Tip>
  원격에 새 커밋이 있어 푸시가 거부(non-fast-forward)되면 먼저 [풀](#풀)로 원격 변경을 받아 합친 뒤 다시 푸시하세요.
</Tip>

## 풀

원격의 변경을 가져와 현재 브랜치에 합칩니다.

<Steps>
  <Step title="풀 버튼 클릭">
    툴바의 **풀** 버튼을 눌러 풀 모달을 엽니다. 받을 커밋 수(behind)가 함께 표시됩니다.
  </Step>

  <Step title="전략 선택">
    **Merge**(기본)와 **Rebase** 중 하나를 고릅니다. Merge는 병합 커밋을 만들고, Rebase는 로컬 커밋을 원격 브랜치 위로 다시 쌓습니다.
  </Step>

  <Step title="Autostash 옵션">
    작업 중인 변경이 있으면 **Autostash**를 켜 임시저장 후 풀하고 자동으로 복원하도록 할 수 있습니다.
  </Step>

  <Step title="풀 실행">
    **풀** 버튼을 누르면 모달이 닫히고 진행·결과가 토스트로 표시됩니다. 완료되면 그래프와 배지가 갱신됩니다.
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/remote-pull-dialog.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=7c4f93f99bc313816df64c955a597991" alt="Pull 출처와 Merge·Rebase 전략, Autostash 옵션을 보여주는 풀 다이얼로그" width="886" height="788" data-path="images/remote-pull-dialog.png" />
</Frame>

<Note>
  풀 중 병합 충돌이 발생하면 워킹 카피(Working copy) 패널에서 해결해야 합니다. 자세한 내용은 [병합 충돌 해결](/review/merge-conflicts)을 참고하세요.
</Note>

<Tip>
  좌측 저장소 패널의 **원격 브랜치** 행을 더블클릭하면, 현재 그 브랜치에 체크아웃되어 있을 때 곧바로 fast-forward 풀을 시도합니다. 로컬을 원격에 맞추는 빠른 방법입니다.
</Tip>

## 페치

원격의 최신 상태를 가져오되 **작업 트리는 건드리지 않습니다**. 원격에 무엇이 올라왔는지 먼저 확인하고 싶을 때 사용합니다.

<Steps>
  <Step title="페치 버튼 클릭">
    툴바의 **페치** 버튼을 눌러 페치 모달을 엽니다.
  </Step>

  <Step title="옵션 확인">
    * **모든 remote (--all)** — 등록된 모든 리모트에서 가져옵니다. 켜면 **Fetch 출처**가 `모든 remote`로 바뀌고 **Remote** 선택은 사라집니다.
    * **태그 (--tags)** — 리모트의 태그도 함께 가져옵니다.

    두 옵션의 기본값은 [설정 → ParalleLane → Git](/settings/preferences)에서 바꿀 수 있습니다. 모달에서 바꾼 값은 이번 한 번만 적용되고 설정에 저장되지 않습니다.
  </Step>

  <Step title="페치 실행">
    **페치** 버튼을 누르면 모달이 닫히고 진행·결과가 토스트로 표시됩니다. 완료되면 원격 추적 브랜치와 배지가 갱신됩니다.
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/remote-fetch-dialog.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=3c0077f5e201e129a2ec71eed08e9fb9" alt="Fetch 출처와 모든 remote·태그 가져오기 옵션을 보여주는 페치 다이얼로그" width="886" height="688" data-path="images/remote-fetch-dialog.png" />
</Frame>

<Note>
  페치는 항상 **prune**을 함께 수행합니다. 즉 원격에서 삭제된 브랜치의 낡은 `origin/*` 추적 참조가 자동으로 정리됩니다. (로컬 태그는 삭제하지 않습니다.) 특정 리모트만 명시적으로 정리하려면 상단 바의 **원격 트래킹 브랜치 정리(Prune)** 버튼을 사용하세요. 이 버튼을 누르면 열리는 모달의 이름이 **Prune**입니다.
</Note>

### 그래프에서 pushed/unpushed 구분

커밋 그래프의 각 노드는 원격에 올라가 있는지에 따라 시각적으로 구분됩니다. 어떤 원격 추적 브랜치에서도 도달할 수 없는 커밋은 아직 올리지 않은(unpushed) 커밋으로, 지금 체크아웃한 브랜치에서 다음에 푸시될 끝 커밋에는 물결 파장 효과가 표시됩니다. 페치/푸시로 상태가 바뀌면 표시도 갱신됩니다.

## 이벤트 기반 자동 페치

주기적 타이머 대신, 특정 순간에 조용히 백그라운드로 페치하도록 설정할 수 있습니다. 항상 최신 원격 상태를 유지하면서도 방해가 없습니다.

자동 페치는 다음 순간에 실행됩니다.

* 앱 창이 다시 포커스를 얻을 때
* 워크트리를 전환할 때
* 앱을 실행하거나 세션을 복원한 직후
* 저장소를 전환할 때

<Steps>
  <Step title="설정 열기">
    [설정 → ParalleLane → 일반](/settings/preferences)의 **Fetch** 항목으로 이동합니다.
  </Step>

  <Step title="자동으로 전환">
    Fetch 모드를 **수동**에서 **자동**으로 바꿉니다.
  </Step>

  <Step title="간격 조정">
    자동으로 전환하면 **자동 fetch 간격** 드롭다운이 나타납니다. 10\~60초 중에서 고릅니다(기본 30초). 같은 워크트리는 이 간격 안에는 다시 페치하지 않습니다.
  </Step>
</Steps>

<Note>
  자동 페치는 완전히 무음입니다. 성공·실패 모두 알림이 뜨지 않으며, 오프라인이거나 원격이 없는 저장소에서는 건너뜁니다. 수동 페치의 에러 알림은 그대로 표시됩니다. 자동 페치도 수동 페치와 동일하게 prune과 `--all`/`--tags` 설정을 따릅니다.
</Note>

## 인증

푸시·풀·페치는 시스템 Git 자격증명(HTTPS 토큰, SSH 키, 키체인)을 그대로 사용합니다. 자격증명이 없으면 터미널 프롬프트에서 멈추지 않고 즉시 인증 오류로 실패하며, 오류 메시지는 에러 토스트로 표시됩니다.

<Note>
  푸시·풀·페치는 300초 안에 끝나지 않으면 타임아웃으로 중단되고 실행 중이던 Git 프로세스가 정리됩니다. 응답 없는 원격 때문에 앱이 무한정 붙잡히지 않도록 하는 안전장치입니다. (진행률을 보고하는 [클론](/remote/clone)에는 더 느슨한 규칙이 적용됩니다.)
</Note>

<Warning>
  "인증 실패" 오류가 나오면 계정과 토큰/SSH 키가 등록되어 있는지 확인하세요. 계정 등록과 저장소별 계정 연결은 [설정 → ParalleLane → 계정](/settings/accounts)에서 관리합니다.
</Warning>