docs: apps에서 git 실행 오류 방지 안내

Made-with: Cursor

docs/deploy.md

@@ -2,7 +2,7 @@
 
 ## 현재 버전
 
-- `v0.0.4`
+- `v0.0.6`
 
 NAS에 SSH로 올리는 **전체 순서**는 `docs/nas-deploy-guide.md`에 따로 정리했다.
 

docs/history.md

@@ -1,5 +1,13 @@
 # 의사결정 이력
 
+## 2026-04-13 · v0.0.6 — Git 작업 디렉터리 오해 방지
+
+NAS에서 `apps` 상위 폴더에 `.git`이 없어 `git pull`이 실패하는 사례가 있어, `docs/nas-deploy-guide.md`에 **반드시 `todo`(클론 루트)로 `cd`한 뒤** Git을 실행한다는 안내와 `ls -a .git` 확인·13절 표 항목을 추가했다.
+
+## 2026-04-13 · v0.0.5 — NAS 갱신 절차에 Git 단계 보강
+
+NAS에서 `git pull`만으로 갱신이 안 되는 경우(브랜치 불일치, 로컬 수정, fetch 누락, 비공개 저장소 자격)를 줄이기 위해 `docs/nas-deploy-guide.md` 10절에 `git fetch`·`checkout main`·`pull --ff-only origin main`·`docker compose pull`(선택) 순서를 명시했다.
+
 ## 2026-04-13 · v0.0.4 — Compose 호스트 포트 분리
 
 NAS에 동시에 띄우는 서비스가 많아 **8080/8090 고정 매핑이 충돌**할 수 있어, `docker-compose.yml`에서 호스트 포트를 **42881(웹)·42917(PocketBase)** 로 바꿨다. 컨테이너 내부 포트(웹 80, PocketBase 8090)는 그대로 두어 이미지·설정 호환을 유지한다. 기본 `VITE_POCKETBASE_URL`은 `http://127.0.0.1:42917`으로 맞춘다.

docs/map.md

@@ -2,7 +2,7 @@
 
 ## 현재 버전
 
-- `v0.0.4`
+- `v0.0.6`
 
 | 경로                      | 역할                                      |
 | ------------------------- | ----------------------------------------- |

docs/nas-deploy-guide.md

@@ -212,15 +212,50 @@ docker compose up -d --build
 
 ## 10. 코드를 최신으로 갱신할 때(이미 클론해 둔 경우)
 
+**주의:** `apps` 폴더 자체(`/volume1/docker/projects/apps`)에는 `.git`이 없다. 여기서 `git pull`을 하면 `fatal: not a git repository`가 난다. **항상 클론해 둔 프로젝트 디렉터리 안으로 들어간 뒤** Git 명령을 실행한다.
+
+`git pull` 한 줄만으로는 **원격에 없는 브랜치에 붙어 있거나**, **로컬 수정이 있어 병합이 막히거나**, **처음 한 번도 `fetch`를 안 한 상태**면 기대한 대로 안 받아질 수 있다. 아래 순서를 권장한다.
+
 ```bash
 cd /volume1/docker/projects/apps/todo
-git pull
+ls -a .git
+```
+
+`.git`이 보이면 이 경로가 저장소 루트가 맞다. 없다면 상위 `apps`에 있지 않은지, 폴더 이름이 `todo`가 맞는지 확인한다.
+
+```bash
+cd /volume1/docker/projects/apps/todo
+
+# 1) 작업 트리 확인(로컬에서 고친 파일이 있으면 pull이 거부되거나 충돌한다)
+git status
+
+# 2) 원격 정보를 가져온 뒤, 추적 브랜치(보통 main)를 최신으로 맞춘다
+git fetch origin
+git checkout main
+git pull --ff-only origin main
+```
+
+- `git pull`만 쓰고 싶다면 **이미 `main`을 추적 중**이어야 한다. 첫 클론 후 한 번도 브랜치를 안 바꿨다면 `git branch -vv`로 `origin/main`을 따라가는지 본다.
+- **로컬에서 수정한 파일이 있으면** `git pull`이 실패한다. NAS에서 직접 고친 내용을 버려도 된다면 `git restore .` 등으로 되돌린 뒤 다시 2)를 실행한다. 유지해야 하면 `git stash` 후 pull하고 `git stash pop`(충돌 가능)을 쓴다.
+- **비공개 저장소**면 NAS에 SSH 키·자격 증명(credential helper)이 등록돼 있어야 `fetch`/`pull`이 된다.
+
+이후 **이미지·번들**을 갱신한다.
+
+```bash
+cd /volume1/docker/projects/apps/todo
+
+# 3) .env로 주소를 두었다면 export는 생략해도 된다. 없으면 6-1과 같이 export 한다.
 export VITE_PUBLIC_APP_URL="http://192.168.0.50:42881"
 export VITE_POCKETBASE_URL="http://192.168.0.50:42917"
+
+# 4) compose에서 image로 받는 서비스(PocketBase 등) 최신화가 필요하면(선택)
+docker compose pull
+
+# 5) 웹 이미지는 저장소 코드로 다시 빌드해야 반영된다
 docker compose up -d --build
 ```
 
-`VITE_POCKETBASE_URL`이 이전과 같아도, 프런트 변경이 있으면 `--build`로 다시 빌드하는 편이 안전하다.
+`VITE_*` 값이 이전과 같아도, 프런트나 `Dockerfile`이 바뀌었으면 **`--build`로 다시 빌드**하는 편이 안전하다.
 
 ---
 
@@ -247,6 +282,8 @@ docker compose up -d --build
 | 폰에서만 안 됨 | `VITE_POCKETBASE_URL`이 `127.0.0.1`이 아닌지, 폰이 같은 Wi‑Fi인지, NAS IP가 맞는지 |
 | 빌드 후에도 주소가 이상함 | `docker compose build --no-cache` 후 다시 `up`, 또는 `export`를 잊지 않았는지 |
 | ARM NAS에서 이미지 오류 | 사용 중인 이미지가 해당 CPU 아키텍처를 지원하는지 로그로 확인한다. |
+| `fatal: not a git repository` | `apps`가 아니라 **`cd todo`(클론한 폴더)** 안에서 실행했는지 확인한다. |
+| `git pull`이 안 되거나 안 받아짐 | 10절 순서대로 `git status`·`fetch`·`checkout main`·`pull --ff-only`, 로컬 수정·비공개 저장소 자격 확인 |
 
 ---
 
@@ -261,4 +298,4 @@ docker compose up -d --build
 7. 브라우저: `:42881` 앱, `:42917/_/` 관리자  
 8. `todos` 컬렉션·CORS·API 규칙 설정  
 
-이후 작업은 `git pull` → `export` → `docker compose up -d --build`를 반복하면 된다.
+이후 작업은 **`cd …/apps/todo`** → `git fetch` → `git pull --ff-only origin main`(또는 추적 브랜치) → 필요 시 `export` 또는 `.env` 확인 → `docker compose pull`(선택) → `docker compose up -d --build`를 반복하면 된다.

docs/spec.md

@@ -2,7 +2,7 @@
 
 ## 현재 버전
 
-- `v0.0.4`
+- `v0.0.6`
 
 ## 스택
 

docs/update.md

@@ -1,5 +1,13 @@
 # 업데이트 로그
 
+## v0.0.6
+
+- ~수정. `docs/nas-deploy-guide.md`: `apps`에서 `git pull` 시 `not a git repository`가 나는 이유와 `cd todo`·`.git` 확인 절차, 13절 표 보강.
+
+## v0.0.5
+
+- ~수정. `docs/nas-deploy-guide.md` 10절: `git fetch`·브랜치 확인·`pull --ff-only`, 로컬 변경 처리, `docker compose pull` 안내.
+
 ## v0.0.4
 
 - ~수정. Docker Compose 호스트 포트: 웹 `42881`, PocketBase `42917`(충돌 시 `docker-compose.yml`만 조정).