논문 지식체계를 만들면서 논문 원본 PDF를 git에 올리지 않도록 막았어요. 막은 뒤에 “정말 막혔나” 확인했고, 통과했다고 판단했어요.
그런데 그 확인이 아무것도 확인하지 못한 확인이었어요.
누구에게 도움이 될까요 — git으로 파일을 관리하는데 .gitignore를 써본 적 있는 분,
그리고 “확인했다”와 “봤다”가 다르다는 걸 아직 겪어보지 않은 분이요.
왜 PDF를 막으려 했나
논문 원본 PDF를 저장소에 담으면 두 가지가 걸려요.
저작권. 논문 PDF는 대개 출판사에 권리가 있어요. 지금 제 저장소는 비공개지만, 나중에 공개로 바꿀지 검토할 때 발목을 잡아요.
용량. PDF는 무거워요. 그리고 git은 한번 담은 파일을 히스토리에서 지우기가 아주 번거로워요. 잘못 담고 나서 고치는 비용이 처음에 막는 비용보다 훨씬 커요.
그래서 원본은 제 컴퓨터 폴더에 두고, git에는 그걸 옮긴 마크다운만 올리기로 했어요. 어느 논문이었는지는 노트에 적은 서지정보와 DOI로 되짚을 수 있으니 잃는 게 아니에요.
어떻게 했나
1. 학습메이트한테 이렇게 부탁했어요
knowledge/raw/ 안의 PDF 파일은 git에 올라가지 않게 .gitignore에 추가해줘.
그리고 실제로 무시되는지 확인까지 해줘.
“확인까지 해줘”를 일부러 붙였어요. .gitignore에 한 줄 적는 건 쉬운데,
패턴이 틀리면 에러 없이 조용히 안 먹어요. 아무 일도 안 일어나니까 잘 된 줄
알고 넘어가게 돼요. 그러다 나중에 PDF가 커밋에 섞여 들어가요.
2. .gitignore에 한 줄이 들어갔어요
knowledge/raw/*.pdf
여기서 *는 “아무 글자나”라는 뜻이에요. 그래서 이름이 무엇이든 pdf 파일 전부를
가리켜요. 앞으로 넣을 논문까지 미리 덮어주니까 논문을 추가할 때마다 고칠 필요가 없어요.
3. 확인했어요 — 그런데 여기가 문제였어요
가짜 PDF와 가짜 마크다운을 하나씩 만들어놓고, git이 뭘 보는지 물었어요.
git status --short knowledge/raw/
돌아온 답이 이거였어요.
?? knowledge/raw/
한 줄이에요. 저는 이걸 보고 “PDF가 안 보이니 잘 막혔네”라고 생각했어요.
아니었어요. 저 한 줄은 “이 폴더 안에 아직 기록 안 된 게 있다”는 말이지, 그 안에 무엇이 있는지는 아무것도 알려주지 않아요. PDF가 걸러졌는지, 마크다운은 통과했는지. 저 출력으로는 둘 다 알 수가 없어요.
💡 여기에
?? knowledge/raw/한 줄만 나온 터미널 화면 스크린샷을 넣으면 좋아요.
막힘 → 어떻게 뚫었나
학습메이트가 먼저 짚어줬어요. “이건 확인한 게 아니다”라고요.
git은 폴더 전체가 아직 기록 안 된 상태면 폴더 하나로 뭉쳐서 보여줘요. 안에 파일이 1개든 100개든 한 줄이에요. 목록을 짧게 유지하려는 친절인데, 확인하려는 사람에게는 오히려 눈을 가려요.
파일 단위로 보려면 옵션을 붙여야 해요.
git status --short -uall knowledge/raw/
-uall은 “기록 안 된 파일을 전부 보여줘”라는 뜻이에요. 이번엔 이렇게 나왔어요.
?? knowledge/raw/.gitkeep
?? knowledge/raw/_test.md
이제 보여요. 마크다운(_test.md)은 git에 보이고, PDF(_test.pdf)는 목록에 없어요.
막힌 게 맞아요. 같은 상태를 두 번째 명령으로 봤을 때 처음 알게 된 거예요.
한 걸음 더 — 반대 방향도 확인해야 해요
여기서 하나 더 배웠어요. “PDF가 막혔나”만 보면 반쪽이에요.
과하게 막혔을 수도 있으니까요. 패턴을 잘못 쓰면 마크다운까지 같이 막혀요. 그러면 정작 올려야 할 논문 노트가 git에 안 올라가는데, 이건 에러가 안 나서 훨씬 늦게 발견돼요. 그래서 양쪽을 다 물어봤어요.
# ① 막아야 할 것이 막혔나
git check-ignore -v knowledge/raw/some-paper.pdf
# → .gitignore:24:knowledge/raw/*.pdf knowledge/raw/some-paper.pdf
# ② 통과해야 할 것이 통과하나
git check-ignore -q knowledge/raw/some-paper.md
# → 아무것도 안 나오면 통과 (막히지 않았다는 뜻)
git check-ignore는 파일이 실제로 없어도 패턴을 확인해줘요. 그래서 앞으로 넣을
파일 이름을 미리 넣어보고 물어봐도 돼요. -v를 붙이면 .gitignore의 몇째 줄이
그 파일을 잡았는지까지 알려줘서, 여러 규칙이 섞여 있을 때 어느 게 범인인지 보여요.
결과
논문 원본 PDF는 git에서 안 보이고, 옮긴 마크다운은 올라가요. 폴더째 담아도 안전해요.
실제로 커밋할 때 git add knowledge/로 폴더를 통째로 담았는데 PDF는 들어가지
않았어요. .gitignore가 add 단계에서 먼저 걸러주기 때문이에요. 다만 그건 패턴이
맞을 때만이라, 먼저 확인한 게 이 안전의 근거였어요. 확인 안 하고 담았으면
지금 PDF가 들어가 있었을지도 몰라요.
| 확인 전 | 확인 후 | |
|---|---|---|
| 본 것 | ?? knowledge/raw/ 한 줄 | 파일 이름 목록 |
| 알 수 있던 것 | 없음 | PDF 제외 · 마크다운 통과 |
| 판단 | ”잘 막혔네” (근거 없음) | “막혔다” (근거 있음) |
가져가서 쓰세요
확인 체크리스트
.gitignore에 무언가를 추가했다면 세 가지를 확인하세요.
- 막아야 할 것이 막혔나 —
git check-ignore -v <막을파일> - 통과해야 할 것이 통과하나 —
git check-ignore -q <올릴파일>(출력 없으면 통과) - git이 파일 단위로 뭘 보나 —
git status --short -uall <폴더>
세 번째를 빼면 안 돼요. 앞의 둘은 패턴을 묻는 것이고, 세 번째는 지금 실제 상태를
묻는 거예요. 패턴이 맞아도 이미 커밋된 파일은 .gitignore가 못 막으니까 둘 다 필요해요.
붙여넣어 쓰는 프롬프트
[파일 종류]를 git에 올라가지 않게 .gitignore에 추가해줘.
추가한 다음 세 가지를 확인해줘 —
① 막아야 할 파일이 정말 막혔는지
② 올려야 할 파일이 실수로 같이 막히지 않았는지
③ git이 파일 단위로 뭘 보고 있는지 (폴더로 뭉쳐서 보여주지 말고)
③번을 빼면 소용없어요. 안 적으면 폴더로 뭉친 출력을 받고 확인했다고 착각하게 되니까요.
배운 것
“봤다”와 “확인했다”는 달라요. 저는 출력을 눈으로 봤어요. 그런데 그 출력에는 제가 알고 싶었던 정보가 담겨 있지 않았어요. 화면에 뭔가 떴다는 것이 확인의 근거가 되지 않아요.
확인하는 방법을 모르면 확인한 줄 알고 지나가요. 이게 제일 무서웠어요. 틀린 걸 봤다면 다시 봤을 거예요. 그런데 아무것도 안 보여주는 출력을 받았을 때는 문제가 없다고 읽혀요. 빈 결과와 아무것도 안 물어본 결과는 다르다는 걸 알아야 해요.
도구의 친절이 눈을 가릴 수 있어요. git이 폴더를 뭉쳐 보여주는 건 목록을 짧게 하려는 배려예요. 평소에는 고마운데, 확인하려는 순간에는 방해가 돼요. 도구가 기본으로 뭘 숨기는지 알아둘 필요가 있어요.
양방향으로 물어야 해요. 막혔나만 묻지 말고 통과하나도 물어야 해요. 과하게 막힌 실수는 에러를 내지 않아서 훨씬 늦게 발견돼요.