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

Made-with: Cursor

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`를 반복하면 된다.