[Git] Ubuntu 16.04에서 Git LFS(Large File Storage) 사용법

Git LFS란?

프로젝트를 GitLab에 올리려고 했더니 다음과 같은 오류가 발생했다.

remote: GitLab: LFS objects are missing. Ensure LFS is properly set up or try a manual "git lfs push --all".
To http://localhost:9010/honeybee/issuer-rest.git
 ! [remote rejected] master -> master (pre-receive hook declined)
error: 레퍼런스를 'http://localhost:9010/honeybee/issuer-rest.git'에 푸시하는데 실패했습니다

LFS 때문인 것 같은데 도대체 뭐가 문제인건지 검색을 해보니 대용량 파일을 GitLab에 push하려고 할 때 발생하는 오류였다.

Git/GitLab은 기본적으로 작은 크기의 소스코드 파일들을 저장하기 위한 시스템이기 때문에 50MB가 넘어가는 파일이 있을 경우 Warning이, 100MB가 넘어가는 파일이 있을 경우 Error가 발생한다고 한다.
하지만 시스템적으로는 꼭 필요한 파일이기 때문에 해당 파일만 빼고 push할 수도 없는 노릇이다.

그럴 때 사용할 수 있는 게 Git LFS(Large File Storage)이다.
이름 그대로 용량이 큰 파일을 저장할 수 있도록 해주는 녀셕이다.

 

Git LFS 설치 및 사용 방법

Git LFS 설치

Ubuntu에서는 curl 명령을 통해 Git LFS를 설치할 수 있다. Git LFS 설치 사이트에 사용 방법이 나와있다.

# Ubuntu에서 Git LFS 설치
$ curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
[sudo] password for hyper: 
Detected operating system as Ubuntu/xenial.
Checking for curl...
Detected curl...
Checking for gpg...
Detected gpg...
Running apt-get update... done.
Installing apt-transport-https... done.
Installing /etc/apt/sources.list.d/github_git-lfs.list...done.
Importing packagecloud gpg key... done.
Running apt-get update... done.

The repository is setup! You can now install packages.

$ sudo apt-get install git-lfs
[sudo] password for hyper: 
패키지 목록을 읽는 중입니다... 완료
의존성 트리를 만드는 중입니다       
상태 정보를 읽는 중입니다... 완료
다음 패키지가 자동으로 설치되었지만 더 이상 필요하지 않습니다:
  conntrack cri-tools ebtables jsonlint kubernetes-cni libappindicator1 libgtkmm-2.4-1v5 libindicator7 libllvm5.0 php-cli php-cli-prompt php-common php-composer-semver php-composer-spdx-licenses
  php-json-schema php-symfony-console php-symfony-filesystem php-symfony-finder php-symfony-process php7.0-cli php7.0-common php7.0-json php7.0-opcache php7.0-readline snapd-login-service socat
Use 'sudo apt autoremove' to remove them.
다음 새 패키지를 설치할 것입니다:
  git-lfs
0개 업그레이드, 1개 새로 설치, 0개 제거 및 27개 업그레이드 안 함.
6,877 k바이트 아카이브를 받아야 합니다.
이 작업 후 16.4 M바이트의 디스크 공간을 더 사용하게 됩니다.
받기:1 https://packagecloud.io/github/git-lfs/ubuntu xenial/main amd64 git-lfs amd64 2.11.0 [6,877 kB]
내려받기 6,877 k바이트, 소요시간 1초 (3,874 k바이트/초)
Selecting previously unselected package git-lfs.
(데이터베이스 읽는중 ...현재 245692개의 파일과 디렉터리가 설치되어 있습니다.)
Preparing to unpack .../git-lfs_2.11.0_amd64.deb ...
Unpacking git-lfs (2.11.0) ...
Processing triggers for man-db (2.7.5-1) ...
git-lfs (2.11.0) 설정하는 중입니다 ...
Git LFS initialized.

 

Git LFS 사용 방법

설치가 완료되면 Git LFS를 사용하려는 프로젝트의 root 디렉터리로 이동한 다음 Git LFS를 사용할 수 있게끔 따로 설치해준다.
그리고 lfs로 관리할 파일을 지정한 다음, .gitattributes 파일을 추가해주어야 한다.
여기에서는 .png, .jpg, .svg 파일을 LFS로 관리하도록 설정했다. 만약 특정 파일을 LFS로 관리하도록 설정하고싶은 경우에는 해당 파일의 경로를 넣어주면 된다.

# Git LFS를 사용하려는 프로젝트의 root 디렉터리에서 실행
$ git lfs install
Updated git hooks.
Git LFS initialized.

# LFS로 관리할 파일 추가
# git lfs track "파일 경로"
$ git lfs track "*.png" "*.jpg" "*.svg"
Tracking "*.png"
Tracking "*.jpg"
Tracking "*.svg"

# .gitattributes 추가
$ git add .gitattributes
$ cat .gitattributes
*.png filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.svg filter=lfs diff=lfs merge=lfs -text

# LFS로 관리하는 파일 목록 확인
$ git lfs ls-files
654c7a9468 - cmd/issuer-rest/static/img/issuer.png
697f283923 - cmd/issuer-rest/static/img/logo.png

그런 다음, 원래대로 GitLab에 push를 하면 된다!

# GitLab에 push
$ git add .
$ git commit -m "Initial commit"
$ git push -u origin master

 

Trouble Shooting

Locking support detected on remote "origin".

GitLab에서 push를 하려고 하니 다음과 같은 에러가 발생했다.

Locking support detected on remote "origin". Consider enabling it with:
  $ git config lfs.http://localhost:9010/honeybee/issuer-rest.git/info/lfs.locksverify true
LFS upload failed:cts:   0% (0/2), 0 B | 0 B/s
  (missing) cmd/issuer-rest/static/img/issuer.png (654c7a9468cd3a1c017b24a9eddb2ecb5a27c1fd69ecfc942ade9df9833d8791)
  (missing) cmd/issuer-rest/static/img/logo.png (697f2839230641037e9b882d75ec79d8bf829697f7324322f3e34309f0ed9be6)
hint: Your push was rejected due to missing or corrupt local objects.
hint: You can disable this check with: 'git config lfs.allowincompletepush true'
error: 레퍼런스를 'http://localhost:9010/honeybee/issuer-rest.git'에 푸시하는데 실패했습니다

이 경우, 사용자의 GitLab에서 LFS를 사용할 수 있도록 구성을 변경해주어야 한다.
에러 메세지에 함께 출력된 두 개의 git config 명령을 실행하면 된다.

$ git config lfs.http://localhost:9010/honeybee/issuer-rest.git/info/lfs.locksverify true
$ git config lfs.allowincompletepush true

 

Your push was rejected due to missing or corrupt local objects.

GitLab의 config를 수정했는데도 여전히 아래 에러가 발생했다.

LFS upload missing objects: (0/2), 0 B | 0 B/s
  (missing) cmd/issuer-rest/static/img/issuer.png (654c7a9468cd3a1c017b24a9eddb2ecb5a27c1fd69ecfc942ade9df9833d8791)
  (missing) cmd/issuer-rest/static/img/logo.png (697f2839230641037e9b882d75ec79d8bf829697f7324322f3e34309f0ed9be6)
Uploading LFS objects:   0% (0/2), 0 B | 0 B/s, done.
오브젝트 개수 세는 중: 91, 완료.
Delta compression using up to 4 threads.
오브젝트 압축하는 중: 100% (85/85), 완료.
오브젝트 쓰는 중: 100% (91/91), 98.91 KiB | 0 bytes/s, 완료.
Total 91 (delta 20), reused 0 (delta 0)
remote: GitLab: LFS objects are missing. Ensure LFS is properly set up or try a manual "git lfs push --all".
To http://localhost:9010/honeybee/issuer-rest.git
 ! [remote rejected] master -> master (pre-receive hook declined)
error: 레퍼런스를 'http://localhost:9010/honeybee/issuer-rest.git'에 푸시하는데 실패했습니다

GitHub에서 오픈소스를 git clone 해온 다음, 그 소스코드를 바탕으로 커스텀 프로젝트를 만들어 GitLab에 push하려고 했는데 Git LFS에 push할 오브젝트가 없어서 나는 에러이다.

Git LFS로 관리할 파일을 보면 크기가 131바이트, 129바이트 밖에 되지 않는데 실제 파일은 LFS에 저장하고, 해당 파일에는 텍스트 포인터만 저장되기 때문에 크기가 작게 나온다.
근데 LFS에 이 포인터로 연결되는 오브젝트가 저장되어있지 않기 때문에 위와 같은 오류가 발생한다.

합계 16
drwxrwxr-x 2 hyper hyper 4096  7월 17 14:29 ./
drwxrwxr-x 5 hyper hyper 4096  7월 17 14:29 ../
-rw-rw-r-- 1 hyper hyper  131  7월 17 14:41 issuer.png
-rw-rw-r-- 1 hyper hyper  129  7월 17 14:41 logo.png

이 경우에는 처음에 원본 오픈소스를 git clone할 때, LFS 파일까지 함께 다운로드한 다음 LFS에서 다운로드한 파일을 복사해 새로운 커스텀 프로젝트에 넣어줘야한다.
이를 위해서는 git clone 명령을 수행하기 전에 git lfs install 명령을 먼저 수행해줘야한다!!!
그러면 다음과 같이 LFS에 저장된 원본 파일들까지 정상적으로 다운로드가 된다.

$ git lfs install
$ git clone <원본 오픈소스 경로>
'edge-sandbox-lfs'에 복제합니다...
remote: Enumerating objects: 151, done.
remote: Counting objects: 100% (151/151), done.
remote: Compressing objects: 100% (100/100), done.
remote: Total 4150 (delta 78), reused 89 (delta 40), pack-reused 3999
오브젝트를 받는 중: 100% (4150/4150), 1.41 MiB | 386.00 KiB/s, 완료.
델타를 알아내는 중: 100% (2388/2388), 완료.
연결을 확인하는 중입니다... 완료.
Downloading cmd/issuer-rest/static/img/issuer.png (170 KB)
Downloading cmd/issuer-rest/static/img/logo.png (5.4 KB)
Downloading cmd/login-consent-server/templates/img/consent.png (54 KB)
Downloading cmd/rp-rest/static/img/icon-home-1.svg (3.1 KB)
Downloading cmd/rp-rest/static/img/icon-home-2.svg (4.1 KB)
Downloading cmd/rp-rest/static/img/icon-home-3.svg (4.2 KB)
Downloading cmd/rp-rest/static/img/icon-home-5.png (1.1 KB)
Downloading cmd/rp-rest/static/img/icon-home-6.png (3.5 KB)
Downloading cmd/rp-rest/static/img/icon-home-7.png (1.8 KB)
Downloading cmd/rp-rest/static/img/verifier.png (216 KB)
파일을 가져옵니다: 100% (163/163), 완료.

$ ls -al cmd/issuer-rest/static/img
합계 184
drwxrwxr-x 2 hyper hyper   4096  7월 17 16:34 .
drwxrwxr-x 5 hyper hyper   4096  7월 17 16:34 ..
-rw-rw-r-- 1 hyper hyper 169609  7월 17 16:34 issuer.png
-rw-rw-r-- 1 hyper hyper   5413  7월 17 16:34 logo.png

이제 다운로드받은 원본 파일들 중 필요한 파일을 새로운 커스텀 프로젝트에 복사해 넣어주고 GitLab에 push하면 된다.

 

Fatal error: Server error: 

모든 과정을 다 수행했는데, 저장소에 소스를 push할 때 별다른 에러 문구 없이 서버 에러가 발생했다.

...
Uploading LFS objects:   0% (0/79), 0 B | 20 KB/s, done.
Fatal error: Server error: http://<gitlab 주소>:<gitlab 포트>/miyoung35/sandbox-multi.git/gitlab-lfs/objects/039562e9ed329672e10fe8f7ac66863b6cea935941d27448f791261bcaf55cdd/1795
Fatal error: Server error: http://<gitlab 주소>:<gitlab 포트>/miyoung35/sandbox-multi.git/gitlab-lfs/objects/418afaf89853d3be152508ef95ef618f1bdc344921d4ac57e14057f24996d448/1698
Fatal error: Server error: http://<gitlab 주소>:<gitlab 포트>/miyoung35/sandbox-multi.git/gitlab-lfs/objects/19c642fe9ebb3d0592e47c3b52a422a820509254232a4613a6de4281495042eb/1202
Fatal error: Server error: http://<gitlab 주소>:<gitlab 포트>/miyoung35/sandbox-multi.git/gitlab-lfs/objects/311ce07b6cf39985c75f7fddb696a519c80a68f77c1616b32118dffb17e03398/2389
Fatal error: Server error: http://<gitlab 주소>:<gitlab 포트>/miyoung35/sandbox-multi.git/gitlab-lfs/objects/40eb65471b0d7ce4e2caace5944980337181378aca0d21ff7b65ae070b8fc9df/1128
...

이 문제는 다음 명령어를 실행하고 난 뒤 push 했더니 정상적으로 완료가 됐다.

$ git config lfs.contenttype false

 

 

참고 사이트

git-lfs Installation : github.com/git-lfs/git-lfs/wiki/Installation