aos-git 0.4.2

AI-powered Git merge conflict resolver — let AI merge both sides intelligently

aos — AI-powered Git Helper

aos는 git을 잘 모르는 팀원도 쉽게 사용할 수 있도록 만든 AI 기반 CLI 도구입니다. 브랜치 병합 중 충돌이 발생하면 AI가 양쪽 변경사항을 분석하여 둘 다 살리는 방향으로 자동 통합합니다.

---

목차

1. 설치
2. 최초 설정
3. 팀 워크플로우 개요
4. 명령어 전체 목록
5. 시나리오별 사용법
6. GitLab 이메일 알림 설정
7. 설정 변경
8. AI 제공자
9. 요구사항

---

설치

pip install aos-git

---

최초 설정

프로젝트 루트 디렉토리에서 1회 실행합니다.

aos setup

순서대로 아래 항목을 입력합니다.

항목	설명
AI 제공자	databricks 또는 anthropic
Databricks Host / Token	Databricks 사용 시 입력
Anthropic API Key	Anthropic 사용 시 입력
안내 메시지 언어	ko (한국어) 또는 en (영어)
GitLab 이메일 알림	알림 받을 브랜치 이름 + 수신자 이메일 목록

설정값은 ~/.aos/config.toml에 저장됩니다. 알림 설정 시 프로젝트 루트에 .gitlab-ci.yml과 scripts/notify_config.toml이 자동 생성됩니다.

git merge.conflictstyle=diff3 도 자동으로 전역 설정됩니다. AI가 BASE(공통 조상) 코드까지 참고하여 더 정확한 병합을 수행합니다.

---

팀 워크플로우 개요

[병합 관리자]                     [팀원 A, B, C ...]
     │                                   │
  각자 feature 브랜치에서 작업           │
     │                                   │
  aos merge feature/xxx  ──────────────  │
  (충돌 시 AI 자동 해결 + 커밋)          │
     │                                   │
  aos push (main 업데이트)               │
     │                                   │
  GitLab CI 자동 실행                    │
     │                                   │
  이메일 알림 발송 ─────────────→  aos sync 실행
                                  (최신 main 반영 + 충돌 시 AI 자동 해결 + 커밋)

---

명령어 전체 목록

aos setup

AI 및 알림 설정을 초기화합니다.

aos setup             # 전체 설정 (최초 1회 또는 AI 설정 변경 시)
aos setup --notify    # 알림 설정만 변경 (수신자 추가/제거, 브랜치 변경 등)

---

aos branch

브랜치 목록을 보기 좋게 출력합니다.

aos branch        # 로컬 브랜치 목록
aos branch -a     # 원격 브랜치 포함 전체 목록 (자동 fetch)
aos branch -d feature/xxx   # 브랜치 삭제

---

aos checkout

브랜치를 이동하거나 새로 만듭니다.

aos checkout main              # 브랜치 이동 (없으면 원격에서 자동 가져옴)
aos checkout feature/my-work   # 원격 브랜치도 자동으로 로컬에 생성 후 이동
aos checkout -b feature/new    # 새 브랜치 생성
aos checkout -b feature/new --push   # 새 브랜치 생성 + 원격에 즉시 push

---

aos add

변경된 파일을 스테이징합니다.

aos add                  # 변경된 파일 전체 스테이징
aos add src/main.py      # 특정 파일만 스테이징
aos add src/ tests/      # 여러 경로 지정

---

aos commit

스테이징된 파일을 커밋합니다.

aos commit -m "feat: 기능 설명"

---

aos push

현재 브랜치를 원격에 push합니다.

aos push

---

aos pull

현재 브랜치에 원격 변경사항을 가져옵니다. 충돌 시 AI가 자동 해결합니다.

aos pull

---

aos status

현재 작업 상태를 보여줍니다.

aos status

---

aos merge

다른 브랜치를 현재 브랜치에 병합합니다. 충돌 발생 시 AI가 자동으로 해결하고 커밋까지 완료합니다.

aos merge feature/my-work          # 로컬 브랜치 병합
aos merge origin/feature/my-work   # 원격 브랜치 병합 (자동 fetch)
aos merge feature/my-work --no-fetch   # fetch 없이 바로 병합

충돌 해결 흐름:

충돌 감지
  └─→ AI가 BASE / OURS / THEIRS + 타임스탬프 분석
        └─→ 통합 결과 미리보기 출력
              └─→ [y] 적용  [N] 건너뜀  [e] 직접 편집
                    └─→ 모든 충돌 해결 완료 → 자동 커밋

---

aos sync

최신 main(또는 지정 브랜치)을 현재 브랜치에 반영합니다. 병합 관리자가 main을 업데이트한 후 팀원이 실행합니다. 충돌 발생 시 AI가 자동으로 해결하고 커밋까지 완료합니다.

aos sync              # origin/main → 현재 브랜치에 반영
aos sync --base dev   # origin/dev 기준으로 반영

---

시나리오별 사용법

A. 팀원 — 일상적인 작업

# 1. 작업 브랜치로 이동 (없으면 자동으로 원격에서 가져옴)
aos checkout feature/my-work

# 2. 파일 수정 후 저장
aos add
aos commit -m "feat: 기능 추가"
aos push

# 3. 병합 관리자로부터 이메일 알림 수신 후 → 최신 main 반영
aos sync
aos push

---

B. 팀원 — 새 작업 시작

# 최신 main 기준으로 새 브랜치 생성
aos checkout main
aos pull
aos checkout -b feature/new-feature --push

---

C. 병합 관리자 — main 업데이트

# 팀원 브랜치를 main에 병합
aos checkout main
aos merge feature/team-member-work
# 충돌이 있으면 AI가 자동 해결 후 커밋까지 완료

# main에 push → GitLab CI 실행 → 팀원에게 이메일 자동 발송
aos push

---

D. 원격 브랜치 목록 확인 후 이동

aos branch -a
# ┌──────────────────────────────────┐
# │  * main                          │
# │    feature/data-pipeline         │
# │    origin/feature/report-ui      │
# └──────────────────────────────────┘

aos checkout feature/report-ui   # 원격 브랜치도 자동으로 로컬 생성 후 이동

---

GitLab 이메일 알림 설정

aos setup 실행 시 알림 설정을 함께 완료하면 아래 파일이 자동 생성됩니다.

파일	역할
.gitlab-ci.yml	지정 브랜치 push 시 알림 스크립트 실행
scripts/notify_config.toml	수신자 이메일 목록 저장
scripts/notify_main_update.py	이메일 발송 스크립트 (자동 포함)

생성 후 한 번만 커밋하면 이후 자동 동작합니다.

git add .gitlab-ci.yml scripts/notify_config.toml
aos commit -m "chore: add gitlab notify config"
aos push

알림 이메일 예시

제목: [aos-git] main 브랜치가 업데이트됐습니다 (a1b2c3d4)

main 브랜치에 새로운 변경사항이 병합됐습니다.
각자 브랜치에서 아래 명령어를 실행하여 최신 버전을 반영해주세요.

  aos sync
  aos commit -m "sync with main"
  aos push

──────────────────────────────
업데이트 정보
  작업자  : 이과장
  커밋    : a1b2c3d4 — merge: feature/data-pipeline
  프로젝트: https://gitlab.example.com/project
──────────────────────────────

---

설정 변경

AI 설정 전체 변경

aos setup

이전 설정값이 기본값으로 표시되므로 변경이 필요한 항목만 입력하고 나머지는 Enter로 유지할 수 있습니다.

알림 설정만 변경 (수신자 추가/제거, 브랜치 변경)

aos setup --notify

[aos] GitLab 알림 설정
  현재 브랜치  : main
  현재 수신자  : [e-mail], [e-mail]

알림을 받을 브랜치 이름 [main]:
수신자 이메일 [[e-mail], [e-mail]]: [e-mail],[e-mail],[e-mail]

[aos] .gitlab-ci.yml 생성됨 (브랜치: main)
[aos] scripts/notify_config.toml 생성됨

변경 후 커밋·push 하면 즉시 반영됩니다.

git add .gitlab-ci.yml scripts/notify_config.toml
aos commit -m "chore: update notify recipients"
aos push

---

AI 제공자

Databricks Model Serving (기본)

사내 Databricks 환경을 사용합니다.

# ~/.aos/config.toml
[ai]
provider = "databricks"
model = "databricks-claude-sonnet-4-6"

[databricks]
host = "https://adb-xxxx.azuredatabricks.net"
token = "dapi..."

Anthropic API

[ai]
provider = "anthropic"
model = "claude-sonnet-4-6"

[anthropic]
api_key = "sk-ant-..."

---

새 버전 릴리스 (관리자용)

GitLab CI가 v* 형식의 태그를 감지하면 자동으로 PyPI에 배포합니다.

1회 사전 준비 — PyPI 토큰 등록

GitLab 프로젝트 → Settings → CI/CD → Variables 에서 추가:

Key	Value	Options
PYPI_API_TOKEN	PyPI에서 발급한 API 토큰 (pypi-...)	Masked 체크

배포 방법

# 방법 1: 스크립트 사용 (권장)
./scripts/release.sh 0.4.0
# pyproject.toml 버전 수정 → 커밋 → 태그 생성 → push 까지 자동 처리

# 방법 2: 수동
# 1) pyproject.toml의 version = "0.4.0" 으로 수정
# 2) git add pyproject.toml && git commit -m "chore: release v0.4.0"
# 3) git tag v0.4.0
# 4) git push origin HEAD && git push origin v0.4.0

push 후 GitLab CI/CD → Pipelines 에서 배포 진행 상황을 확인할 수 있습니다.

---

요구사항

• Python 3.11+
• git
• Databricks Model Serving 접근 권한 또는 Anthropic API 키