프로젝트와 Git

뷰어는 소스 식별과 읽기 전용 검토를 지원하며 Git 쓰기와 게시는 에이전트가 담당합니다. UI에는 Uncommitted·Merge·PR·Fetch 제어가 없습니다. 에이전트는 승인된 범위에서 호스트 Git·gh 도구를 사용하며 아래의 기존 백엔드 HTTP workflow는 유지합니다. UI 제거는 API 제거 또는 쓰기 승인을 의미하지 않습니다. 제품 범위를 참고하세요.

식별과 발견

프로젝트는 저장소와 그 안의 상대 프로젝트 경로, 또는 연결된 일반 디렉터리입니다. 워크트리는 실제 체크아웃 하나를 식별합니다. 기본 체크아웃과 연결된 체크아웃은 프로젝트 규칙을 공유합니다. Native Git 등록에서 현재 가용성을 확인하며 브랜치 변경이 과거 실행 식별자를 바꾸지는 않습니다. 일반 디렉터리가 Git 저장소가 되면 관찰로 인식합니다.

폴더 열기는 native 디렉터리 선택기를 사용합니다. 폴더 선택과 Git 발견은 브랜치 생성, 프로젝트 코드 실행, 컨테이너 준비를 하지 않습니다. 인스턴스의 관찰 루트가 발견 범위를 정합니다. 삭제된 폴더의 결과는 남지만 실행할 수 없습니다. 체크아웃 없는 브랜치 항목은 체크아웃 생성이나 실행 제어 없이 커밋된 변경만 보여 줍니다.

tracking.json은 비교 메인 브랜치와 표시 설정을 소유합니다. 메인과 변경된 워크트리의 표시는 tracking 서비스 규칙을 따릅니다. 로컬 브랜치 포함은 선택 사항이며 실제 워크트리 항목을 중복하지 않고 보충합니다.

병합된 항목 숨김을 켜면 HEAD가 설정된 로컬 메인 브랜치의 조상인 깨끗한 워크트리를 숨깁니다. origin이 github.com이면 인증된 gh로 병합된 PR도 확인합니다. 전역 설정의 github.cliPath가 있으면 해당 실행 파일을 사용합니다. PR의 소스 저장소·브랜치·정확한 head SHA가 현재 소스와 같고, 대상이 설정된 메인 브랜치이며, 병합 결과 커밋이 이미 해당 로컬 브랜치의 조상인 경우에만 병합으로 인정합니다. Git 이력을 바꾸거나 자동으로 fetch하지 않고 squash·rebase PR 병합을 인식합니다. GitHub에서 PR이 병합됐다는 사실만으로 로컬 반영을 인정하지 않습니다.

체크아웃 없는 브랜치의 병합 상태에도 같은 판정을 사용합니다. 새 커밋·미커밋 변경이 있는 작업, 병합을 확인하지 못한 detached 체크아웃, 메인 체크아웃은 계속 표시합니다. 지원하지 않는 origin, GitHub 인증 부재, 잘못된 응답과 조회 실패가 있으면 확인되지 않은 작업을 숨기지 않으며 로컬 조상 관계 판정은 오프라인에서도 유지합니다. 원격 조회 결과는 크기가 제한된 메모리 캐시에서 최대 30초간 공유하며, 숨기기 전에 로컬 head·대상 조상 관계·변경 상태를 다시 확인합니다. PR 데이터베이스나 새 영속 설정은 추가하지 않습니다. fork와 github.com 이외 호스트의 PR 근거는 이 보완 판정의 범위에 포함하지 않습니다. 기존 병합된 항목 숨김 설정이 표시 여부를 계속 제어하며 브랜치나 체크아웃을 삭제하지 않습니다.

프로젝트 관리

프로젝트 선택 메뉴나 프로젝트가 없는 시작 화면에서 프로젝트 관리를 엽니다. 연결된 프로젝트와 연결 해제된 프로젝트를 이름 또는 기본 폴더 경로로 검색할 수 있습니다. 각 항목은 폴더, Git/일반 폴더 구분과 폴더 가용성을 보여 줍니다. 프로젝트 연결은 native 폴더 선택기로 위치를 고르고 표시 이름을 지정합니다. 같은 canonical 프로젝트를 다시 연결하면 기존 식별자를 사용하고 기존 표시 이름을 보존합니다.

이름 변경은 프로젝트 탐색에 사용하는 인스턴스의 표시 이름만 바꿉니다. 실행 구성은 기존 프로젝트 설정에서 관리합니다. 폴더 이동, 저장소 생성, Clone, 기록 영구 삭제는 프로젝트 관리 기능에 포함되지 않습니다.

연결 해제는 확인을 거치며 소스 파일, 설정, 워크트리, 자격 증명과 실행 기록을 보존합니다. 프로젝트 선택 목록에서 제외하고 자동 관찰과 새 실행을 중단합니다. 선택된 프로젝트였다면 다른 연결된 프로젝트로 이동합니다. 마지막 프로젝트를 해제하면 관리 기능에 접근할 수 있는 시작 화면으로 돌아갑니다. 해제 상태는 재시작 후에도 유지되며 관찰 루트 설정이 자동으로 재연결하지 않습니다. 실행 중인 Unit/Integration/Playwright와 Git 작업을 마치고, 미완료 워크트리 생성을 해결하고, 소유한 환경과 자원 정리를 끝낸 뒤 해제해야 합니다.

연결 해제됨 목록에서 기록 보기와 다시 연결을 제공합니다. 재연결은 원래 디렉터리를 검증하고 프로젝트·워크트리 ID와 이름을 그대로 사용합니다. 폴더에 접근할 수 없는 상태와 의도적으로 연결을 해제한 상태는 별개입니다. 폴더를 원래 위치에 복구한 뒤 재연결해야 하며 기록은 삭제하지 않고 유지합니다.

HTTP는 표시 이름 수정에 PATCH /api/projects/:id, 연결 해제에 DELETE /api/projects/:id, 재연결에 POST /api/projects/:id/reconnect를 사용합니다. GET /api/projects는 연결된 프로젝트를 조회하고 includeDisconnected=true는 보존된 프로젝트와 폴더 가용성을 포함합니다. 변경과 실행 수락은 워크트리 수명주기 경계를 공유합니다. 요청·응답 스키마는 생성된 API 문서를 참고하세요.

읽기 전용 비교

Native Git이 모든 index 형식의 상태와 중첩·전역·공유 제외 규칙을 담당합니다. 추적 파일은 ignore 규칙에 맞아도 변경이 보입니다. 지원되는 HEAD/index blob 읽기는 isomorphic-git과 native fallback을 유지합니다. 검사 시 외부 diff, textconv, hook, optional lock, fsmonitor를 비활성화하며 저장소 상대 경로를 검증합니다.

워크트리 검토는 사용 가능한 브랜치 생성 reflog commit을 기준으로, 없으면 설정한 메인 브랜치 merge base를 기준으로 비교합니다. 커밋·staged·unstaged·untracked 변경을 포함합니다. 비교 상태가 없거나 모호하면 빈 diff 대신 진단을 반환합니다. 브랜치 전용 비교는 커밋된 변경만 포함합니다. 소스·diff 줄바꿈은 전역 표시 설정이며 원문, 줄 번호와 통계를 보존합니다.

이미지 비교는 공통 파일 미리보기 규약을 따르며, 명시적인 커밋 리비전과 이름 변경 경로를 사용하고 staged/unstaged 바이트를 구분합니다.

Git 조회 및 작업 트리·브랜치·커밋 diff의 호출별 stdout/stderr 출력 상한은 기본 128 MiB입니다. 서버 프로세스의 REDPACT_GIT_MAX_BUFFER_MIB 환경 변수로 1–2048 범위의 정수 MiB를 설정할 수 있습니다. 예: REDPACT_GIT_MAX_BUFFER_MIB=256 redpact serve --port 54322. 변경 후 서버를 다시 시작하세요. 출력에 따라 메모리를 사용하며 미리 전부 할당하지 않습니다. 동시 호출과 diff 렌더링은 추가 메모리를 사용합니다. 이미지·개별 미추적 파일 미리보기 및 제한된 메타데이터 조회의 별도 제한은 유지됩니다. 아래 커밋 패치와 파일 목록의 128 MiB 제한도 이 설정을 따릅니다.

Git Graph와 Fetch

Git Graph는 제한된 커밋 목록, 브랜치 필터, 원격 표시, 로드된 커밋 검색과 선택한 커밋의 파일 diff를 제공합니다. 열기와 탐색은 읽기 전용입니다. 헤더의 Refresh는 로컬 이력을 다시 읽으며 원격에서 가져오지 않습니다. 뷰어에는 Fetch·Pull·Push 버튼이 없습니다.

일반적인 Git 그래프처럼 실제 커밋의 부모 관계를 표시합니다. 병합 커밋은 부모들의 이력을 연결하지만, squash PR은 단일 부모 커밋을 만들고 rebase PR은 다시 작성된 커밋을 선형 이력에 추가합니다. 둘 다 원래 브랜치로 이어지는 병합 선을 만들지 않습니다. 커밋 제목에 이미 있는 (#29) 같은 PR 번호는 그대로 표시하며, 호스팅 서비스에 PR 메타데이터를 조회하지 않습니다. 따라서 squash 병합 뒤에도 보존된 원본 브랜치는 별도 레인에 남을 수 있습니다.

검색 대상은 로드된 커밋뿐입니다. 오래된 커밋을 검색하려면 이력을 더 로드하거나 브랜치 필터로 불러올 이력을 좁힙니다. Refresh는 기존 로컬 ref를 다시 읽으므로, 원격에만 있는 이력은 먼저 호스트 Git에서 명시적으로 fetch해야 합니다.

유지된 백엔드 Fetch 작업은 설정된 원격의 destination refspec으로 remote-tracking branch를 명시적으로 갱신합니다. 머지·push·prune· tag fetch나 로컬 브랜치·index·파일 변경은 하지 않습니다. common Git 디렉터리별로 직렬화하고 원격 누락, 사용 중 상태, 부분 실패를 보고합니다. 성공·실패 뒤 모두 목록을 갱신합니다.

커밋 패치는 128 MiB로 제한됩니다. 이를 초과하면 HTTP 200과 함께 patchOmitted: "size_limit", 빈 patch, changedPaths 목록과 명시적인 omitted 진단을 반환합니다. Git Graph는 커밋 메타데이터를 유지하며 크기 제한 안내와 파일 경로를 표시합니다. 잘린 내용을 완전한 diff로 표시하지 않습니다. 파일 이름 응답에도 별도의 128 MiB Git 출력 제한이 적용됩니다. 이 제한도 초과하면 HTTP 200 응답은 커밋 식별 정보와 changedPathsOmitted: "size_limit", 별도 진단을 유지하며 부분 파일 목록을 반환하거나 표시하지 않습니다.

기존 체크아웃과 보존된 생성 기록

Git worktree는 호스트 에이전트가 네이티브 Git으로 생성합니다. Redpact는 기존 체크아웃을 발견·검증·연결하며, 연결 과정에서 브랜치나 체크아웃을 만들지 않습니다. POST /api/projects/:id/worktrees는 해당 프로젝트에 속한 기존 체크아웃을 연결합니다. 개발 worktree는 프로젝트 소유의 영구 디렉터리에 두고, /tmp는 폐기 가능한 테스트 fixture에만 사용합니다.

POST /api/work-starts는 제거되어 404를 반환합니다. 클라이언트는 호스트 Git 도구로 체크아웃을 만든 뒤 그 경로를 연결해야 합니다. CLI와 MCP에도 생성 또는 재개 명령이 없습니다.

GET /api/work-starts/:id는 과거 생성 기록을 읽기 전용으로 제공합니다. 원래 입력, 계획된 ID와 prepared, attempted, created, completed 상태는 변경하지 않습니다. 이 값은 과거 관찰 기록이며 현재의 경로 예약이 아닙니다. 미완료 기록은 발견된 체크아웃을 숨기거나 프로젝트 연결 해제를 막지 않습니다. 실행 중인 작업과 소유 환경에 대한 기존 진입 제한은 유지합니다.

결과가 불확실한 과거 생성은 git worktree list와 기록된 경로로 확인하세요. 유효한 체크아웃은 정상 연결 절차를 사용하며 Redpact에 생성을 재요청하지 않습니다. 연결은 기존 체크아웃 식별자와 증거를 보존합니다. 새로 발견한 체크아웃에는 과거 요청의 미사용 ID를 재사용하지 않고 별도 식별자를 부여합니다. Redpact는 과거 기록·브랜치· 체크아웃 파일을 삭제하거나 불확실한 생성을 완료 상태로 바꾸지 않습니다. 런타임 데이터를 참고하세요.

로컬 커밋과 머지

뷰어에는 Uncommitted·Commit·Discard·Merge 제어가 없습니다. 에이전트는 승인된 쓰기 작업 전에 호스트 도구로 변경을 검사합니다. 유지된 백엔드 Commit은 검사한 staged·unstaged·untracked 변경을 포함합니다. Discard에는 명시적 승인이 필요하며 목록의 untracked 파일을 지울 수 있습니다. 백엔드는 검사 후 변경을 최신성 검사에서 거부하고 두 작업 뒤 자동으로 머지하지 않습니다.

Merge는 설정한 메인 브랜치의 실제 체크아웃을 대상으로 합니다. 소스·대상의 미커밋 변경, 오래된 revision, 미해결 상태는 수락을 막습니다. 후보 충돌을 소스·대상 파일과 분리합니다. 영속 attempt는 입력 HEAD와 결과를 보존하며 동일 요청의 재시도는 멱등적입니다. 중단·충돌은 상태 확인과 복구가 필요하며 맹목적 반복이나 브랜치 삭제로 처리하지 않습니다.

충돌을 해결하는 에이전트는 소스 체크아웃에서 대상을 다시 확인하고, 테스트와 커밋 후 다음 승인된 머지를 진행합니다. 테스트 승인은 Git 머지 승인이 아닙니다. 모든 워크트리는 설정 소유권에 설명된 고정 공유 설정을 사용하며, 의존성 overlay 승격 단계는 없습니다.

GitHub pull request

뷰어에는 PR 폼이나 게시 버튼이 없습니다. 에이전트는 호스트 도구로 승인된 게시를 수행하기 전에 소스·origin·대상 브랜치를 검사합니다. 유지된 백엔드 게시 workflow에는 깨끗한 named non-default 브랜치와 지원되는 동일 저장소 주소의 github.com origin이 필요합니다. 인증된 gh와 Git 자격 증명을 재사용하며 토큰을 저장하거나 별도 인증 체계를 번들하지 않습니다. 전역 Settings에서 절대 github.cliPath를 지정하고 연결을 확인할 수 있습니다.

백엔드 게시 작업은 검사한 SHA를 같은 origin 브랜치로 force·tag 없이 push한 다음 PR을 만듭니다. 같은 head/base의 열린 PR은 재사용합니다. Push to PR은 제목·본문을 바꾸지 않습니다. 소스, revision, 목적지를 다시 검사합니다. push 성공 후 PR 생성 여부가 불명확하면 별도로 보고하고 재시도는 기존 PR을 먼저 찾습니다.

게시가 머지·자동 커밋·fork·브랜치 삭제를 하지는 않습니다. Enterprise host, SSH 별칭, fork target, 모호한 origin URL은 현재 adapter 범위 밖입니다. GitHub 기본 PR base와 로컬 Merge 대상은 독립적입니다. GitHub가 PR 식별자를 소유하며 로컬 PR DB는 없습니다. 종료 시 진행 중인 게시를 기다립니다.

구현: Git adapters, Merge workflow, PR workflow, GitHub adapter.