gzh-cli

Gizzahub Manager (gzh-cli)

통합 개발 환경 CLI 도구

개요

gzh-cli (바이너리: gz)는 개발자를 위한 종합 CLI 도구로, Git 플랫폼 통합 관리, IDE 모니터링, 코드 품질 관리, 개발 환경 설정을 하나의 명령어로 통합합니다.

핵심 가치:

• 🔗 다중 플랫폼 통합: GitHub, GitLab, Gitea, Gogs를 하나의 인터페이스로
• 🛠️ 개발 워크플로우 자동화: IDE, 코드 품질, 패키지 매니저 통합 관리
• 📦 확장 가능한 아키텍처: Integration Libraries Pattern으로 모듈화
• 🔌 사용자 확장 시스템: 별칭, 워크플로우, 외부 명령어 통합 지원
• 🚦 라이프사이클 관리: 안정/베타/실험적 기능 단계별 제어

빠른 시작

설치

# Go로 설치 (권장)
go install github.com/Gizzahub/gzh-cli/cmd/gz@latest

# 소스에서 빌드
git clone https://github.com/Gizzahub/gzh-cli.git
cd gzh-cli
make bootstrap  # 빌드 의존성 설치
make build      # gz 바이너리 생성
make install    # $GOPATH/bin에 설치

첫 명령어

# 시스템 상태 진단
gz doctor

# IDE 스캔 및 관리
gz ide scan
gz ide status

# Git 리포지토리 관리
gz git repo clone-or-update https://github.com/user/repo.git
gz git repo pull-all ~/workspace --parallel 5

# 코드 품질 검사
gz quality run

다음 단계

• 📚 전체 문서
• 🚀 설치 가이드
• ⚙️ 설정 가이드

주요 기능

명령어 구조

gz [command] [subcommand] [flags]

# 주요 명령어
git         # Git 플랫폼 통합 (repo, webhook, event)
ide         # IDE 모니터링 및 관리
quality     # 코드 품질 도구 (포매팅 + 린팅)
profile     # 성능 프로파일링
pm          # 패키지 매니저 관리
shellforge  # 쉘 설정 빌더
synclone    # 대량 리포지토리 클론
dev-env     # 개발 환경 관리
net-env     # 네트워크 환경 관리
repo-config # GitHub 리포지토리 설정
doctor      # 시스템 진단

전체 명령어: gz --help

🧩 하위 프로젝트 (Subprojects)

gzh-cli는 핵심 기능을 독립 라이브러리로 분리하여 개발합니다. 각 라이브러리는 독립적으로 사용 가능합니다.

통합 아키텍처: Integration Libraries Pattern

코드 감소 효과: 6,702줄 (92.0% 감소율)

사용 예제

Git 리포지토리 관리

# 스마트 클론/업데이트 (6가지 전략)
gz git repo clone-or-update https://github.com/user/repo.git
gz git repo clone-or-update https://github.com/user/repo.git --strategy rebase --branch develop

# 재귀적 일괄 업데이트 (하위 디렉토리 모든 Git 리포지토리)
gz git repo pull-all ~/workspace --parallel 10 --verbose

# 크로스 플랫폼 동기화
gz git repo sync --from github:org/repo --to gitlab:group/repo

IDE 관리

# IDE 스캔 및 감지
gz ide scan                  # 24시간 캐시
gz ide scan --refresh        # 캐시 무시

# IDE 상태 확인
gz ide status
gz ide status --running      # 실행 중인 IDE만

# IDE로 프로젝트 열기
gz ide open /path/to/project
gz ide open . --ide goland

코드 품질

# 전체 품질 검사 및 수정
gz quality run

# 변경된 파일만 처리
gz quality run --changed

# 린팅만 (수정 없이 검사)
gz quality check

대량 리포지토리 클론

# GitHub 조직 전체 클론
gz synclone github --orgName myorg --targetPath ~/repos --token $GITHUB_TOKEN

# GitLab 그룹 클론
gz synclone gitlab --groupName mygroup --targetPath ~/repos --token $GITLAB_TOKEN

# 설정 파일로 실행
gz synclone --config synclone.yaml

문서

사용자 가이드

• 📚 문서 전체 인덱스
• 🚀 설치 가이드
• 📖 빠른 시작
• ⚙️ 설정 가이드
• 📋 명령어 레퍼런스

개발자 가이드

• 🏗️ 아키텍처
• 💻 개발 환경 설정
• 🧪 테스트 가이드
• 🔧 기여 가이드

추가 리소스

• 🔍 문제 해결
• 📈 성능 모니터링
• 🔐 보안 가이드

설정

기본 설정 파일

설정 파일 위치 (우선순위 순):

1. $GZH_CONFIG_PATH (환경 변수)
2. ./gzh.yaml (현재 디렉토리)
3. ~/.config/gzh-manager/gzh.yaml (사용자 설정)
4. /etc/gzh-manager/gzh.yaml (시스템 설정)

설정 예제

global:
  clone_base_dir: "$HOME/repos"
  default_strategy: reset

providers:
  github:
    token: "${GITHUB_TOKEN}"
    organizations:
      - name: "myorg"
        clone_dir: "$HOME/repos/github/myorg"

  gitlab:
    token: "${GITLAB_TOKEN}"
    groups:
      - name: "mygroup"
        clone_dir: "$HOME/repos/gitlab/mygroup"

상세 설정: Configuration Guide

🔌 확장 시스템 (Extensions)

gz는 소스 코드 수정 없이 사용자 정의 별칭, 워크플로우, 외부 명령어를 추가할 수 있는 강력한 확장 시스템을 제공합니다.

확장 설정 파일

위치: ~/.config/gzh-manager/extensions.yaml

간단한 별칭 (Simple Aliases)

자주 사용하는 명령어에 짧은 이름을 부여:

aliases:
  update-all:
    command: "pm update --all"
    description: "Update all package managers"

사용: gz update-all

다단계 워크플로우 (Multi-Step Workflows)

여러 명령어를 순차적으로 실행:

aliases:
  full-sync:
    description: "Full synchronization workflow"
    steps:
      - "synclone run"
      - "pm update --all"
      - "git repo pull-all"

실행 시 각 단계의 진행 상황이 표시됩니다:

🔄 Step 1/3: synclone run
✅ Step 1/3 completed

🔄 Step 2/3: pm update --all
✅ Step 2/3 completed

🔄 Step 3/3: git repo pull-all
✅ Step 3/3 completed

🎉 All steps completed successfully!

파라미터화된 별칭 (Parameterized Aliases)

변수를 사용하는 재사용 가능한 명령어:

aliases:
  clone-and-setup:
    command: "git repo clone-or-update ${url} && dev-env bootstrap"
    description: "Clone repository and setup environment"
    params:
      - name: url
        description: "Repository URL to clone"
        required: true

사용: gz clone-and-setup https://github.com/user/repo.git

외부 명령어 통합 (External Commands)

외부 도구를 gz 서브커맨드로 통합:

external:
  - name: terraform
    command: /usr/local/bin/terraform
    description: "Terraform infrastructure management"
    passthrough: true

사용: gz terraform plan

실험적 기능 활성화

일부 명령어는 실험적 기능으로 표시되며 기본적으로 비활성화됩니다:

# 환경 변수로 활성화
export GZ_EXPERIMENTAL=1
gz experimental-command

# 또는 플래그로 활성화
gz --experimental experimental-command

상세 예제: examples/extensions.yaml

아키텍처

Integration Libraries Pattern

gzh-cli는 공통 기능을 외부 라이브러리로 분리하여 **단일 정보 소스(Single Source of Truth)**를 확립합니다.

gzh-cli (통합 CLI)
├── cmd/*_wrapper.go (45-473줄) - 얇은 래퍼
└── 외부 라이브러리 통합
    ├── gzh-cli-git (로컬 Git 작업)
    ├── gzh-cli-quality (코드 품질)
    ├── gzh-cli-package-manager (패키지 관리)
    └── gzh-cli-shellforge (쉘 설정)

이점:

• ✅ 코드 중복 제거 (92% 감소)
• ✅ 독립 사용 가능
• ✅ 단일 정보 소스
• ✅ 유지보수 간소화

상세 아키텍처: Integration Documentation

개발

빌드 및 테스트

# 개발 환경 설정
make bootstrap      # 빌드 의존성 설치 (최초 1회)

# 빌드
make build          # gz 바이너리 생성

# 코드 품질 (커밋 전 필수)
make fmt            # 코드 포매팅
make lint           # 린팅 검사
make test           # 테스트 실행

# 전체 품질 검사
make lint-all       # 포맷 + 린트 + pre-commit

Pre-commit 훅

# 설치 (최초 1회)
make pre-commit-install

# 수동 실행
make pre-commit
make pre-push

모듈별 테스트

# 특정 패키지 테스트
go test ./cmd/git/repo -v
go test ./cmd/ide -v
go test ./pkg/github -v

# 특정 테스트 함수
go test ./cmd/git -run "TestCloneOrUpdate" -v

기여하기

기여 프로세스

1. 이슈 확인: Issues
2. Fork & 브랜치: feature/your-feature or fix/issue-number
3. 구현: 코드 작성 + 테스트
4. 품질 검사: make lint-all 통과
5. PR 제출: 상세 설명 포함

품질 기준

• ✅ make test 통과
• ✅ make lint 통과
• ✅ make fmt 적용
• ✅ 문서 업데이트 (필요시)
• ✅ 커밋 메시지 규칙 준수

자세한 내용: Contributing Guide

시스템 요구사항

• Go: 1.23.0+
• Git: 2.0+
• OS: Linux, macOS, Windows (WSL 권장)

라이선스

MIT License - LICENSE 파일 참조

링크

• GitHub: Gizzahub/gzh-cli
• 문서: docs/
• 이슈: Issues
• 기술 스택: TECH_STACK.md
• 변경 이력: CHANGELOG.md

Made with ❤️ by the Gizzahub Team