install troubleshooting_ko

Troubleshooting

언어: 🇺🇸 English | 🇰🇷 한국어

이 문서는 Ghost-ALICE를 설치하거나 업데이트하는 중 최신 repository 문서를 pull하지 못하는 상황을 빠르게 복구하기 위한 playbook이다. repository 업데이트가 막힌 사용자도 읽을 수 있도록 GitHub Wiki에 게시한다.

• Wiki: https://github.com/AidALL/ghost-alice/wiki/install-troubleshooting_ko
• Repo copy: docs/ko/getting-started/troubleshooting.md

Contents

• Git Update Recovery
• Target Symptoms
• 1. Fix Identity Errors First
• 2. Inspect Current State
• 3. When Local Changes Are Not Needed
• 4. When Local Changes Must Be Preserved
• 5. Run The Installer After Git Is Clean
• 6. Operating Principles

Git Update Recovery

Target Symptoms

다음 중 하나가 보이면 첫 번째 문제는 installer가 아니다. local checkout이 동기화되지 못한 상태이므로 먼저 Git 상태를 고쳐야 한다.

• Committer identity unknown
• CONFLICT (content)
• CONFLICT (add/add)
• Automatic merge failed; fix conflicts and then commit the result.
• error: Your local changes to the following files would be overwritten by merge
• localized equivalent of error: Your local changes to the following files would be overwritten by merge
• ## main...origin/main [ahead N, behind M]
• git status --short에 UU 또는 AA가 보임

이 상태에서는 install.ps1, install.sh, install.cmd를 반복 실행하지 않는다. Git 상태를 깨끗하게 정리한 뒤 installer를 다시 실행한다.

일반적인 macOS/Linux 소스 업데이트에서는 raw git pull보다 안전한 installer 경로를 우선한다.

cd ~/ghost-alice
bash install.sh --update-source

이 명령은 source-local tracked/untracked 변경사항을 git stash에 저장하고 checkout을 fast-forward한 뒤, stash는 명시적인 review 대상으로 남긴다.

raw git pull이 이미 막혀 checkout이 --update-source를 받지 못하면 bootstrap one-command 업데이트를 사용한다.

cd ~/ghost-alice && git fetch origin main && git show FETCH_HEAD:scripts/bootstrap-source-update.sh | /bin/bash -s --

bootstrap updater는 오래된 local installer가 아니라 새로 fetch한 remote blob에서 실행된다. source-local tracked/untracked 변경사항을 git stash에 저장하고 ~/ghost-alice를 fast-forward한 뒤 업데이트된 installer를 실행한다. 기본 위치가 아닌 checkout은 명령 전에 GHOST_ALICE_SOURCE_DIR=/path/to/ghost-alice를 설정한다.

1. Fix Identity Errors First

Committer identity unknown은 Git이 merge commit을 만들 author identity를 모른다는 뜻이다. 사용자 본인의 account 값으로 한 번 설정한다.

git config --global user.email "you@example.com"
git config --global user.name "your-name"

conflict가 이미 시작된 상태라면 identity 설정 직후 git pull을 반복하지 않는다. step 3 conflict recovery로 이동한다.

2. Inspect Current State

git status --short --branch
git diff --name-only --diff-filter=U

UU 또는 AA가 보이면 checkout은 이미 merge conflict 상태다. local 변경사항을 보존해야 하는지 버려도 되는지 먼저 결정한다.

3. When Local Changes Are Not Needed

deployment clone, installer 전용 clone, 개인 편집이 없는 checkout처럼 local 변경사항을 버려도 될 때만 이 경로를 쓴다.

git status --short에 이미 UU 또는 AA가 있으면 먼저 merge를 abort한다.

git merge --abort

그 다음 upstream을 다시 fetch하고 local checkout을 public main에 맞춘다.

git fetch origin
git reset --hard origin/main
git clean -nd
git clean -fd
git pull --ff-only

Cautions:

• git reset --hard origin/main은 tracked 파일 내용과 local commit 위치를 origin/main으로 옮긴다.
• git clean -nd는 삭제 미리보기다.
• git clean -fd는 untracked 파일과 디렉터리를 실제로 삭제한다. 미리보기에 보존해야 할 항목이 있으면 실행하지 않는다.

4. When Local Changes Must Be Preserved

local 문서, skill, script를 편집했다면 destructive reset을 먼저 실행하지 않는다. 안전한 source 업데이트 경로를 쓰거나 backup branch와 diff를 만든다.

preferred path:

cd ~/ghost-alice
bash install.sh --update-source
git stash list
git stash show -p stash@{0}

checkout이 새 installer를 pull하지 못해 이 옵션을 아직 쓸 수 없다면 one-command bootstrap updater를 사용한다.

cd ~/ghost-alice && git fetch origin main && git show FETCH_HEAD:scripts/bootstrap-source-update.sh | /bin/bash -s --

source-local 변경사항이 여전히 필요한 경우에만 stash를 다시 적용한다.

git stash pop stash@{0}

manual backup path:

git status --short --branch
git branch backup/before-update-YYYYMMDD-HHMM
git diff > ghost-alice-local.diff
git diff --staged > ghost-alice-local-staged.diff

그 다음 git status --short --branch, conflict 파일 목록, 두 diff 파일을 maintainer에게 공유한다. 직접 해결하려면 conflict marker를 제거하고 tests를 실행한 뒤 commit한다.

5. Run The Installer After Git Is Clean

Windows PowerShell:

.\install.ps1
.\install.ps1 -Doctor
.\install.ps1 -Status

macOS / Linux / WSL / Git Bash:

bash install.sh
bash install.sh --doctor
bash install.sh --status

Doctor 또는 Status가 pending merge 경고를 보고하면 installer가 설치 중 protective backup을 만든 것이다. 새 Claude 또는 Codex session을 열고 backup된 변경사항 review를 요청해, merge-companion flow가 무엇을 유지할지 결정하게 한다.

6. Operating Principles

• 업데이트 명령은 기본적으로 git pull --ff-only를 사용한다.
• git pull이 merge conflict를 만들면 installer는 그 conflict를 대신 해결할 수 없다.
• 막힌 사용자를 위한 안내는 repository 안에만 있어서는 충분하지 않다. Wiki나 release notes처럼 pull 없이 읽을 수 있는 위치에도 같은 recovery playbook을 둔다.
• Git 상태에 UU 또는 AA가 남아 있으면 installer를 실행하지 않는다.