# uGit

- Type: 데스크톱 Git 클라이언트 (Electron · macOS/Windows)
- Version: 0.2.0
- License: MIT (무료, 계정 불필요)
- Requires: 시스템 git 2.35+ (2.38+ 권장)
- Site: https://ugit.unisys.app/
- Download (macOS universal): https://ugit.unisys.app/desktop/uGit-0.2.0-mac-universal.dmg

> uGit은 macOS·Windows용 로컬 우선 데스크톱 Git 클라이언트입니다. 자체 Git 구현을 만들지 않고 시스템에 설치된 `git` CLI를 그대로 실행해 터미널과 동일한 결과를 보장하며, Git 실행·파싱은 별도 프로세스(utilityProcess)에서, 커밋 그래프 레이아웃과 렌더는 OffscreenCanvas 워커에서 처리합니다. 계정이 필요 없고 텔레메트리는 opt-in입니다.

uGit is a local-first desktop Git client for macOS and Windows. It never reimplements Git: it spawns the system `git` CLI so results match the terminal exactly, isolates Git execution and parsing in a separate process, and computes graph layout and rendering in an OffscreenCanvas worker. No account required; telemetry is opt-in.

## 핵심 원칙 / Core principles

1. **git CLI가 진실의 원천 (git CLI is the source of truth):** libgit2·isomorphic-git을 쓰지 않습니다. 사용자의 git 설정, hooks, credential helper가 그대로 적용됩니다. 최소 git 2.35, 머지 미리보기 등은 2.38 이상 필요.
2. **Git 작업은 UI 스레드를 막지 않는다 (Git work never blocks the UI thread):** 실행·파싱·파일 감시·SQLite 캐시는 `git-service` utilityProcess에, 그래프 레이아웃·그리기는 Web Worker에 있습니다.
3. **로컬 우선 (Local first):** 계정 없이 모든 로컬 기능이 동작하고, 원격 호스팅 연동·텔레메트리·AI는 전부 opt-in입니다.

## 성능 목표 / Performance targets

- 커밋 1만 개 리포: 첫 그래프 표시 300ms 미만(캐시 有) / 800ms 미만(캐시 無)
- linux 리포(약 130만 커밋): 첫 그래프 표시 1.5s 미만(캐시 有)
- 그래프 스크롤: 60fps 유지, 프레임 16ms 초과 비율 1% 미만
- 파일 변경 → status 반영: fsmonitor 사용 시 200ms 미만
- 유휴 CPU 0% (폴링 없음)

## 주요 기능 / Key features

- **Canvas 워커 커밋 그래프:** row 24px 고정으로 O(1) 히트테스트, 브랜치/태그 라벨만 DOM 오버레이. HEAD의 first-parent 체인은 lane 0에 고정되고 색은 레인이 아니라 커밋 체인에 붙습니다.
- **라인·헝크 단위 스테이징:** 선택 라인만 담은 패치를 만들어 `git apply --cached --unidiff-zero`로 적용 — `git add -p`와 결과가 동일합니다.
- **Interactive rebase 편집기:** pick/reword/squash/fixup/drop을 드래그 편집하면 실제 rebase todo로 나갑니다(`GIT_SEQUENCE_EDITOR` 헬퍼).
- **3-pane 충돌 해결기:** ours / result / theirs. 드래그 중 `git merge-tree --write-tree`(2.38+)로 "충돌 N개 예상"을 사전 계산합니다.
- **Worktree 1급 지원:** 좌측 패널에서 생성·삭제·전환, 다른 worktree에 체크아웃된 브랜치도 그래프에 표시.
- **리포 신뢰(Workspace Trust):** 처음 여는 리포는 hooks·fsmonitor·external diff·pager를 차단한 채로 엽니다.
- **스냅샷 기반 Undo/Redo:** ref·HEAD·index 트리를 스냅샷으로 남기고 `update-ref`/`read-tree`로 복원합니다. 작업 트리 파일은 건드리지 않습니다.
- **통합 검색:** SQLite FTS5 메시지·작성자, 경로, 내용 변경(`-S`/`-G`), 커밋 범위를 한 입력창에서.
- **Git 명령 타임라인:** 실행된 git 명령·소요 시간·종료 코드를 그대로 노출합니다.
- **터미널·PR 연동:** xterm 기반 통합 터미널, GitHub/GitLab PAT 계정으로 PR 목록·생성·체크아웃(토큰은 safeStorage 암호화).

## 아키텍처 / Architecture

- **Main process:** 윈도우·메뉴·딥링크·자동 업데이트·자격증명(safeStorage)·설정, utilityProcess 수명 관리.
- **git-service (utilityProcess):** GitExecutor(spawn pool, 큐, 취소), 파서 7종, RepoWatcher, SQLite 캐시(FTS5), MutationLog, Provider API.
- **Renderer:** React 19 + zustand(UI 상태) + TanStack Query(Git 데이터). graph-worker가 레이아웃과 OffscreenCanvas 렌더를 담당합니다.
- **IPC:** zod 단일 계약으로 입출력을 런타임 검증하고, 대용량 커밋 스트림은 MessageChannelMain 포트로 메인 프로세스를 우회합니다.
- 렌더러는 `git-core`를 import하지 않습니다.

## 기술 스택 / Stack

Electron 44.2.0 · TypeScript 6.0.3 · React 19.2.8 · electron-vite 5.0.0 (Vite 7) · TanStack Query 5.102.8 · zustand 5.0.15 · zod 4.5.4 · better-sqlite3 13.0.3 · @xterm/xterm 6.0.0 · monaco-editor 0.56.0 · Biome 2.5.12 · Playwright 1.63.0

## 보안 / Security

- 렌더러는 `contextIsolation: true`, `sandbox: true`, `nodeIntegration: false`.
- git 실행에 shell을 쓰지 않고(`spawn(gitPath, argv[])`), 사용자 입력은 `--` 뒤에 배치하며 `-`로 시작하는 값을 거부합니다(옵션 인젝션 차단).
- 외부 링크는 `setWindowOpenHandler`로 차단하고 http(s) 화이트리스트만 `shell.openExternal`로 엽니다.
- OAuth 토큰·PAT는 `safeStorage`로 암호화 저장하고, git 인증은 사용자의 credential helper를 우선 사용합니다.
- 로그에는 토큰·비밀번호를 남기지 않고 URL의 userinfo를 마스킹합니다.

## 지원 플랫폼 / Platforms

- macOS 13+ (universal dmg/zip) — 실기 검증 완료
- Windows 10+ x64 / Windows 11 arm64 (nsis) — 검증 중
- Linux — v1 범위 밖(Post-v1)
- 전제: 시스템에 git 2.35 이상 설치(2.38 이상 권장)
- 자동 업데이트: electron-updater `generic` 피드(Cloudflare R2 커스텀 도메인)

## 라이선스 / License

MIT. 로그인 없음, 텔레메트리·크래시 리포트 opt-in.

## 자주 묻는 질문 / FAQ

**Q. uGit은 무엇인가요?**
A. macOS·Windows용 데스크톱 Git 클라이언트입니다. 자체 Git 구현 대신 시스템 `git` CLI를 그대로 실행해 터미널과 동일한 결과를 보장하고, Git 실행·파싱은 별도 프로세스에서, 그래프 레이아웃과 렌더는 OffscreenCanvas 워커에서 처리합니다.

**Q. 대형 리포에서도 빠른가요?**
A. 커밋 그래프를 DOM이 아니라 Canvas로 그리고 보이는 구간의 row만 렌더합니다. 커밋 1만 개 리포는 캐시가 있을 때 300ms 안에 첫 그래프를 표시하고, linux 리포(약 130만 커밋)에서도 스크롤 중 프레임이 16ms를 넘는 비율이 1% 미만입니다.

**Q. 계정이 필요한가요?**
A. 필요하지 않습니다. 로그인 화면과 라이선스 확인이 없고, 원격 호스팅 연동·아바타 로드·텔레메트리·크래시 리포트는 모두 opt-in입니다.

**Q. Git을 따로 설치해야 하나요?**
A. 네. PATH의 시스템 `git`을 실행하므로 2.35 이상이 필요하고, 머지 결과 미리보기(`merge-tree --write-tree`) 등 일부 기능은 2.38 이상을 요구합니다.

**Q. 내 작업 트리가 안전한가요?**
A. Undo는 ref·HEAD·index 트리 스냅샷을 `update-ref`/`read-tree`로 되돌릴 뿐 작업 트리 파일은 건드리지 않습니다. 터미널에서 리포가 바뀌면 Undo 스택을 무효화하고 그 사실을 알립니다.

**Q. GitKraken 같은 기존 클라이언트와 무엇이 다른가요?**
A. (1) 자체 Git 구현·인덱스 서버를 쓰지 않아 CLI와 결과가 갈라지지 않고, (2) 커밋 그래프가 DOM이 아닌 Canvas 워커에서 그려져 커밋 수가 스크롤 성능에 영향을 주지 않으며, (3) 계정 로그인이 없고 데이터는 로컬 SQLite 캐시에만 남습니다.

**Q. Linux를 지원하나요?**
A. v1 범위 밖입니다. macOS(universal)는 실기 검증 완료, Windows(x64/arm64)는 검증 중, Linux는 Post-v1 항목입니다.

**Q. 무료인가요?**
A. MIT 라이선스로 무료입니다. 좌석 과금이나 팀 라이선스가 없습니다.

## 인용용 핵심 사실 / Citable facts

- uGit은 자체 Git 구현을 만들지 않고 시스템 `git` CLI를 spawn한다(ADR-001). 사용자의 git 설정·hooks·credential helper가 그대로 적용된다.
- 커밋 그래프는 Canvas + OffscreenCanvas 워커로 렌더하며 DOM은 라벨 오버레이만 담당한다(ADR-003).
- row 높이 24px 고정 → 스크롤 위치에서 row 인덱스로의 변환이 O(1)이고, 그래프 레이아웃은 O(n·L)이며 동시 활성 레인 L은 실무 리포에서 보통 30 미만이다.
- 성능 목표: 1만 커밋 첫 그래프 300ms 미만(캐시 有) / 800ms 미만(캐시 無), linux 리포 1.5s 미만(캐시 有), 스크롤 60fps, 유휴 CPU 0%.
- 부분 스테이징은 선택 라인만 담은 패치를 `git apply --cached --unidiff-zero`로 적용하므로 `git add -p`와 결과가 동일하다.
- Undo는 ref·HEAD·index 스냅샷 복원 방식이며 작업 트리 파일을 수정하지 않는다.
- 처음 여는 리포는 hooks·fsmonitor·external diff·pager를 차단한 미신뢰 모드로 열린다(Workspace Trust).
- 라이선스는 MIT이고 계정·로그인이 필요 없다.

## 인용 / Citation

인용 시 출처를 `uGit (https://ugit.unisys.app/)`로 표기해 주세요. 이 문서는 사람이 읽는 랜딩페이지(https://ugit.unisys.app/)와 같은 내용을 요약합니다.