> ## 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.

# Git LFS

> 대용량 파일 관리

Git LFS(Large File Storage)로 관리되는 대용량 파일도 ParalleLane에서 그대로 보고 다운로드할 수 있습니다. 설정 화면에서 LFS 초기화 상태를 진단하고, diff·저장소 패널에서 LFS 파일 상태를 확인합니다.

<Note>ParalleLane은 git-lfs 바이너리를 대신 설치하지 않습니다. 시스템에 git-lfs가 설치되어 있어야 하며, ParalleLane은 초기화(`git lfs install`)와 상태 표시를 담당합니다.</Note>

## LFS 상태 진단과 초기화

<Steps>
  <Step title="Git 설정 열기">
    **설정 → ParalleLane → Git**으로 이동합니다. 아래쪽 **Git LFS** 항목에서 상태를 확인합니다.
  </Step>

  <Step title="상태별 조치">
    아래 표에 따라 필요한 조치를 취합니다.
  </Step>
</Steps>

| 상태     | 표시                                             | 조치                                                                            |
| ------ | ---------------------------------------------- | ----------------------------------------------------------------------------- |
| 설치 안 됨 | `설치 안 됨` 배지 + "설치되지 않음. git-lfs를 설치하세요." 안내    | 먼저 git-lfs를 설치합니다(예: `brew install git-lfs`).                                 |
| 초기화 필요 | `초기화 필요` 배지 + "설치됨 (v3.3.0). 필터가 초기화되지 않았습니다." | **초기화** 버튼을 눌러 `git lfs install`을 실행합니다. 성공하면 "Git LFS가 초기화되었습니다" 토스트가 표시됩니다. |
| 활성     | `활성` 배지 + "활성 (v3.3.0)."                       | 추가 조치가 없습니다.                                                                  |

<Note>진단과 초기화는 모두 **머신 전역** 기준입니다. 설치 여부는 `git lfs version`으로, 초기화 여부는 전역 Git 설정의 `filter.lfs.smudge` 유무로 판정하며 **초기화** 버튼은 전역 LFS 필터를 등록합니다. 저장소마다 따로 초기화할 필요는 없습니다.</Note>

<Frame>
  <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/settings-lfs-status.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=e64206e41316670315772ea341bc6c4c" alt="Git 설정 화면 아래쪽 Git LFS 행에 상태 배지와 버전이 표시된 모습" width="2906" height="1784" data-path="images/settings-lfs-status.png" />
</Frame>

<Note>git-lfs가 설치되지 않은 환경에서도 ParalleLane은 안전하게 동작합니다. 이 경우 **설정 → ParalleLane → Git**의 Git LFS 행은 `설치 안 됨` 배지만 표시하고 **초기화** 버튼은 나타나지 않으며, 저장소 패널의 LFS 섹션과 파일 행의 LFS 배지도 표시되지 않습니다.</Note>

## diff에서 LFS 파일 보기

LFS로 추적되는 파일을 열면, 다운로드 여부에 따라 다르게 표시됩니다.

* **다운로드됨**: 실제 파일 내용(텍스트 diff, 이미지 미리보기)이 그대로 보입니다.
* **미다운로드**: diff 자리에 **Git LFS 객체** 카드가 뜨고 파일명·용량과 **미다운로드** 라벨이 표시됩니다. 카드의 **다운로드** 버튼을 누르면 해당 파일을 내려받아 실제 내용으로 전환됩니다.

<Tip>미다운로드 상태에서 다운로드 버튼을 누르면 그 파일 하나만 내려받습니다. 저장소 전체를 한 번에 받으려면 아래 **Git LFS** 섹션의 **미다운로드 받기**를 사용하세요.</Tip>

## 저장소 LFS 인벤토리

좌측 사이드바 저장소(Repository) 탭의 접이식 **Git LFS** 섹션에서 저장소의 LFS 파일 목록을 확인할 수 있습니다. 이 섹션은 LFS 파일이 하나 이상 있을 때만 나타납니다.

* 각 행에 파일명·용량과 다운로드 여부 글리프가 표시됩니다. 목록은 최대 100개까지 보여 주고 그보다 많으면 마지막 줄에 `… 외 N개`가 붙습니다.
* 섹션 헤더의 **미다운로드 받기** 버튼으로 아직 받지 않은 LFS 파일을 모두 내려받습니다.

## 변경 파일 목록의 LFS 배지

커밋 상세나 워킹 카피의 변경 파일 목록에서도 LFS로 추적되는 파일을 구분할 수 있습니다. 해당 행의 파일 경로 오른쪽에 작은 **LFS** 배지가 붙습니다.

<Frame>
  <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/settings-lfs-inventory.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=9e68890950ae13dbb20ffd89a2420940" alt="커밋 상세의 변경 파일 목록에서 assets/concept.psd와 assets/walkthrough.mov 행에 LFS 배지가 붙은 모습" width="2386" height="1784" data-path="images/settings-lfs-inventory.png" />
</Frame>

## 사이드바 LFS 배지

프로젝트(Projects) 사이드바의 저장소 행에도 LFS 사용 여부가 표시됩니다.

* `.gitattributes`에 LFS 추적 규칙(`filter=lfs`)이 있는 저장소 행에 작은 **LFS** 배지가 붙습니다. 배지에 마우스를 올리면 "Git LFS로 추적되는 저장소" 툴팁이 표시됩니다.
* 서브모듈을 [자식 저장소로 등록](/settings/submodules)했다면 그 자식 저장소 행에도 같은 배지가 붙습니다.
* 배지 판정은 저장소 목록이 바뀌거나 HEAD·refs가 바뀔 때 다시 계산됩니다. 아직 판정되지 않았거나 추적 규칙이 없으면 배지가 표시되지 않습니다.