Ghost-ALICE OS

Troubleshooting

언어: 🇺🇸 English 🇰🇷 한국어

이 문서는 Ghost-ALICE를 설치하거나 업데이트하는 중에 최신 repository docs를 pull하지 못할 때 빠르게 복구하는 playbook이다. repo update가 막힌 사용자도 읽을 수 있도록 같은 내용을 GitHub Wiki install-troubleshooting_ko page에도 올린다.

Contents

Git Update Recovery

Target Symptoms

아래 중 하나가 보이면 문제는 installer가 아니다. local checkout이 동기화되지 못한 상태이므로 Git state부터 고친다.

이 상태에서는 installer를 반복 실행하지 않는다. Git state를 먼저 깨끗하게 만든 뒤 installer를 다시 실행한다.

일반 source update에서는 raw git pull보다 안전한 installer 경로를 먼저 쓴다.

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

이 command는 source의 tracked/untracked 변경을 git stash에 저장하고, checkout을 fast-forward한 뒤, 그 stash를 직접 확인하도록 남긴다.

Windows에서는 같은 installer path에 .\install.cmd를 사용한다. PowerShell이 cannot be loaded because running scripts is disabled를 표시하면 wrapper가 -NoProfile -ExecutionPolicy Bypass로 PowerShell을 호출하고 사용자 또는 머신 execution policy를 변경하지 않는다.

raw git pull이 이미 막혀서 checkout이 --update-source를 받지 못하면 bootstrap one-command update를 쓴다.

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

bootstrap updater는 낡은 local installer가 아니라 새로 가져온 remote blob에서 실행된다. source의 tracked/untracked 변경을 git stash에 저장하고 ~/ghost-alice를 fast-forward한 뒤 updated installer를 실행한다. checkout 위치가 기본값이 아니면 command 앞에 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 changes를 보존할지 버릴지 먼저 정한다.

3. When Local Changes Are Not Needed

deployment clone, installer-only clone, 개인 edit이 없는 checkout처럼 local changes를 버려도 되는 경우에만 이 경로를 쓴다.

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:

4. When Local Changes Must Be Preserved

local docs, skills, scripts를 편집했다면 destructive reset을 먼저 실행하지 않는다. 안전한 source update 경로를 쓰거나 backup branch와 diff를 만든다.

일반 fast-forward update의 권장 경로:

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

checkout이 새 installer를 pull하지 못해 그 option이 아직 없으면 one-command bootstrap updater를 쓴다.

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

source의 변경이 여전히 필요할 때만 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

bash-first installer path를 사용한다.

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

Doctor 또는 Status가 pending merge warning을 내면, installer가 설치 중에 보호용 backup을 만들었다는 뜻이다. 새 Claude/Codex session을 열고 backup된 changes를 review해 달라고 요청하면, merge-companion flow가 무엇을 유지할지 정한다.

6. Operating Principles