Git에서 받은 이미지 파일이 짧은 텍스트로 열리는 이유

checkout은 이미 받은 객체를 펼칩니다. 다운로드가 필요하면 fetch 또는 pull 경로를 확인합니다.

Git LFS 포인터와 실제 객체를 구분하고, 다운로드 권한·체크아웃 경로를 확인한 뒤 파일 손상 여부를 판단하세요.

banner.png가 이미지 뷰어에서는 열리지 않는데 텍스트 편집기에서는 세 줄로 보인다면 파일 내용을 먼저 보세요. 첫 줄이 version https://git-lfs.github.com/spec/v1이라면 Git LFS 포인터일 가능성이 큽니다. 그 안에는 이미지 픽셀 대신 실제 파일을 찾기 위한 정보가 들어 있습니다.

이 글은 2026년 9월 28일 확인한 GitHub·Git LFS 문서를 바탕으로 합니다. assets/banner.png는 설명용 경로이며, 아래 명령을 실제 원격 저장소에 실행한 기록은 아닙니다.

확장자는 PNG인데 내용은 주소표인 상태

Git LFS는 큰 파일 내용을 별도로 보관하고 Git 커밋에는 작은 포인터를 기록합니다. 포인터의 oid sha256:…는 실제 객체의 식별자, size는 그 객체의 크기를 나타냅니다. version은 포인터 형식에 관한 정보입니다. GitHub의 LFS 구조와 포인터 예시

파일 이름이 .png로 끝나도 현재 내용이 이 텍스트라면 이미지 디코더가 읽을 PNG 바이트가 없습니다. 확장자를 JPEG로 바꾸거나 이미지 복구 프로그램을 실행하기 전에 실제 객체를 받아야 합니다.

저장소의 상태를 세 곳으로 나눠 보면 원인이 명확해집니다. 커밋에는 포인터가 있고, 로컬 LFS 저장소에는 내려받은 객체가 있으며, 작업 디렉터리에는 앱이 읽는 파일이 있습니다. 정상적인 저장소에도 첫 번째 포인터는 남습니다. 문제가 되는 것은 앱이 세 번째 위치에서 이미지 대신 포인터를 읽는 경우입니다.

먼저 무엇을 받았는지 확인합니다

Git으로 복제한 저장소에서 확인한다면 다음처럼 시작할 수 있습니다.

git status --short
git rev-parse HEAD
git lfs version
git check-attr filter \
  -- assets/banner.png
git lfs ls-files

첫 명령은 진행 중인 변경을 확인합니다. 이어서 대상 커밋을 기록하고, LFS 도구가 있는지와 해당 경로의 필터가 lfs인지 봅니다. git lfs ls-files는 현재 참조의 LFS 파일을 확인하는 데 씁니다. Git LFS 명령 문서

.gitattributes 규칙과 실제 파일도 함께 확인해야 합니다. 현재 규칙이 맞는다고 과거에 잘못 기록한 모든 커밋이 자동으로 고쳐지는 것은 아닙니다. 반대로 저장소 웹 화면에서 포인터를 봤다는 것만으로 로컬 파일이 미완성이라고 판단할 수도 없습니다. 빌드가 읽는 정확한 경로를 확인하세요.

도구가 없다면 프로젝트가 안내하는 방식으로 LFS를 설치·구성해야 합니다. git lfs install은 상태 조회가 아니라 필터와 훅을 설정하는 명령입니다. 팀의 Git 설정을 확인한 뒤 적용하며, 오류 해결을 위해 기존 훅을 무조건 덮어쓰는 옵션부터 사용하지 않습니다.

checkout을 반복해도 내려받기는 시작되지 않습니다

git lfs checkout은 로컬에 확보된 객체를 작업 파일에 채웁니다. 원격 다운로드는 수행하지 않습니다. 실제 객체가 아직 없는 상태라면 checkout만 반복해도 포인터를 이미지로 바꿀 재료가 생기지 않습니다. checkout의 동작

현재 커밋의 객체를 받아 작업 트리까지 채우는 일반적인 명령은 다음과 같습니다.

git lfs pull

이 명령은 네트워크 다운로드와 작업 파일 변경을 수반합니다. 현재 저장소·브랜치와 작업 변경을 확인하고 실행합니다. LFS의 include/exclude 설정으로 다운로드 범위를 제한한 프로젝트라면 필요한 경로가 제외돼 있지 않은지도 봐야 합니다. pull의 동작과 필터

이미 객체를 별도로 fetch한 상태에서 특정 경로만 펼치려면 다음 형태를 사용할 수 있습니다.

git lfs checkout assets/banner.png

공식 문서는 수정된 파일을 덮어쓰지 않는 checkout 동작을 설명합니다. 실행 후에도 포인터가 남는다면 객체 미확보인지, 현재 파일이 변경된 상태인지, 경로와 참조가 맞는지를 나눠 확인합니다. 파일을 강제로 지우는 작업은 이 진단 순서에 필요하지 않습니다.

다운로드가 실패했다면 포인터보다 오류를 읽습니다

Git 커밋을 읽을 수 있어도 실제 LFS 객체 다운로드가 실패할 수 있습니다. 포인터는 객체의 위치를 찾는 데 필요한 정보이고, 그 객체를 받을 권한이나 서버에 존재한다는 증명까지 담지는 않습니다.

인증 오류라면 현재 LFS endpoint와 인증 경로를 확인합니다. 객체를 찾지 못한다는 오류라면 대상 커밋과 객체 식별자를 저장소 관리자에게 전달해 확인할 수 있습니다. 용량이나 전송 제한에 관한 응답이라면 서비스의 해당 제한을 봅니다. 서로 다른 실패를 모두 “파일이 깨졌다”로 묶으면 이미지 변환을 반복하게 됩니다.

문제를 공유할 때는 커밋, 대상 경로, 명령과 비밀값을 제거한 오류를 남깁니다. 포인터의 size와 현재 작업 파일의 크기를 함께 적으면 실제 객체까지 받았는지 설명하기 쉽습니다. 인증 토큰을 명령줄이나 공개 로그에 붙일 필요는 없습니다.

ZIP과 CI에서는 전달 경로가 달라집니다

GitHub의 소스 ZIP은 저장소 설정에 따라 LFS 객체를 포함할 수도, 포인터만 담을 수도 있습니다. 다운로드 버튼으로 받았다는 사실만으로 실제 이미지가 포함됐다고 보장할 수 없습니다. 아카이브의 LFS 객체 설정

ZIP을 받은 사람이 .git 없는 폴더에서 Git 명령을 실행하면 앞의 진단 절차를 그대로 쓸 수 없습니다. 이 경우 작성자에게 바이너리가 포함된 배포본을 요청하거나, 접근 권한이 있는 저장소를 Git LFS가 준비된 환경에서 복제하는 경로를 선택합니다. 배포 담당자는 소스 아카이브와 바로 실행할 산출물을 구분해 안내하는 편이 좋습니다.

CI에서는 저장소 checkout 뒤, 이미지 처리를 시작하기 전에 필요한 파일의 내용을 확인합니다. 개발자 컴퓨터에는 예전에 받은 LFS 객체가 남아 있을 수 있어 같은 커밋도 로컬과 새 CI의 준비 상태가 다를 수 있습니다. 캐시가 비어 있는 실행에서도 객체 다운로드가 완료되는 흐름인지 봅니다.

받은 뒤에는 이미지로 읽히는지까지 봅니다

복구 확인은 명령 종료 코드에서 한 단계 더 나갑니다. banner.png가 더 이상 포인터 텍스트가 아닌지, 이미지 도구에서 실제로 열리는지 확인합니다. 무결성 검사가 필요하다면 받은 파일의 SHA-256과 바이트 수를 포인터의 값에 대조합니다. 식별자를 임의로 바꿔 파일을 맞추는 것이 아니라 해당 커밋이 요구하는 객체인지 검사하는 것입니다.

이미지는 열리지만 기대한 디자인과 다르다면 파일 수신 문제는 좁혀졌습니다. 그다음에는 브랜치와 커밋, 앱이 참조하는 경로를 확인하면 됩니다. 포인터, 다운로드된 객체, 작업 파일 중 어디까지 준비됐는지를 구분하면 다시 clone하거나 이미지를 변환하기 전에 필요한 조치를 고를 수 있습니다.