git-onboarding-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git 초기 설정 가이드

Git初始配置指南

Git과 GitHub를 처음 사용하기 위한 설정을 단계별로 진행합니다. 이미 완료된 단계는 자동으로 건너뜁니다.

本指南将分步介绍首次使用Git和GitHub所需的配置流程，已完成的步骤会自动跳过。

상태 수집

状态采集

아래 9개 명령어를 모두 병렬로 실행하세요:

```
which git
```
— Git 설치 여부
```
git config --global user.name
```
— 사용자 이름
```
git config --global user.email
```
— 이메일

which gh 2>/dev/null && echo "installed" || echo "none"

— GitHub CLI 설치 여부

```
gh auth status 2>&1
```
— GitHub 인증 상태 (출력에 "Logged in"이 포함되면 성공)

git rev-parse --git-dir 2>/dev/null && echo "repo" || echo "no-repo"

— Git 저장소 여부

git remote get-url origin 2>/dev/null || echo "no-remote"

— 원격 저장소 연결 여부

git ls-remote --heads origin main 2>/dev/null | grep -q main && echo "remote-branch: exists" || echo "remote-branch: none"

— 원격 main 브랜치 여부

for hook in pre-commit commit-msg pre-push; do test -x .git/hooks/$hook && echo "$hook: exists" || echo "$hook: none"; done

— git hooks 설치 여부

请并行执行以下全部9条命令：

```
which git
```
— 检查Git是否安装
```
git config --global user.name
```
— 获取全局用户名
```
git config --global user.email
```
— 获取全局邮箱

which gh 2>/dev/null && echo "installed" || echo "none"

— 检查GitHub CLI是否安装

```
gh auth status 2>&1
```
— 检查GitHub认证状态（输出包含"Logged in"即为认证成功）

git rev-parse --git-dir 2>/dev/null && echo "repo" || echo "no-repo"

— 检查当前目录是否为Git仓库

git remote get-url origin 2>/dev/null || echo "no-remote"

— 检查是否已关联远程仓库

git ls-remote --heads origin main 2>/dev/null | grep -q main && echo "remote-branch: exists" || echo "remote-branch: none"

— 检查远程是否存在main分支

for hook in pre-commit commit-msg pre-push; do test -x .git/hooks/$hook && echo "$hook: exists" || echo "$hook: none"; done

— 检查git hooks是否安装

진행 규칙

执行规则

결과를 분석하여 이미 완료된 단계는 건너뛰세요.
첫 번째 미완료 단계부터 순서대로 진행하세요.
각 단계를 하나씩 완료한 후 다음 단계로 넘어가세요.
사용자 입력이 필요한 단계에서는 반드시 AskUserQuestion을 사용하세요.
모든 설명은 한국어로, Git을 처음 쓰는 사용자 눈높이에 맞추세요.

分析命令结果，自动跳过已完成的步骤
从第一个未完成的步骤开始按顺序执行
每完成一个步骤再进入下一个步骤
需要用户输入的步骤必须使用AskUserQuestion
所有说明适配首次使用Git的用户理解水平

단계 1: Git 설치 확인

步骤1：检查Git安装

완료 조건:

which git

이 경로를 반환함

미설치인 경우 안내하세요:

Git이 설치되어 있지 않습니다.

터미널에서 아래 명령어를 직접 실행하세요:
  xcode-select --install

설치 팝업이 나타나면 "설치" 버튼을 클릭하세요.
설치가 완료되면 다시 /git-onboarding-setup 을 실행해주세요.

xcode-select는 GUI 팝업이 필요하므로 Claude가 직접 실행하지 마세요. 안내만 제공하고 이 단계에서 멈추세요.

完成条件：

which git

返回可执行文件路径

如果未安装，请向用户提示：

Git尚未安装

请在终端中手动执行以下命令：
  xcode-select --install

安装弹窗出现后点击「安装」按钮，安装完成后请重新执行/git-onboarding-setup

xcode-select需要GUI弹窗操作，Claude不要直接执行，仅提供提示后停在当前步骤即可。

단계 2: 사용자 이름 설정

步骤2：设置全局用户名

완료 조건:

git config --global user.name

이 비어있지 않음

AskUserQuestion으로 이름을 물어보세요:

question: "Git에서 사용할 이름을 입력하세요. 커밋 기록에 남는 이름입니다."
header: "이름"
options:
- 현재 시스템 사용자 이름을 기본 옵션으로 제안

이름을 받으면 실행하세요:

git config --global user.name "<입력받은 이름>"

完成条件：

git config --global user.name

返回非空值

使用AskUserQuestion询问用户用户名：

question: "请输入Git使用的用户名，该名称会显示在提交记录中。"
header: "用户名"
options:
- 默认选项建议使用当前系统用户名

获取用户名后执行以下命令：

git config --global user.name "<用户输入的用户名>"

단계 3: 이메일 설정

步骤3：设置全局邮箱

완료 조건:

git config --global user.email

이 비어있지 않음

AskUserQuestion으로 이메일을 물어보세요:

question: "Git에서 사용할 이메일을 입력하세요. GitHub 계정과 같은 이메일을 권장합니다. 이메일을 공개하고 싶지 않다면 GitHub의 noreply 이메일을 사용할 수 있습니다 (GitHub > Settings > Emails에서 확인)."
header: "이메일"
options:
- "noreply 이메일 사용" — GitHub Settings > Emails에서 제공하는 비공개 이메일 (username@users.noreply.github.com)
- "직접 입력" — 본인 이메일 주소를 직접 입력

이메일을 받으면 실행하세요:

git config --global user.email "<입력받은 이메일>"

完成条件：

git config --global user.email

返回非空值

使用AskUserQuestion询问用户邮箱：

question: "请输入Git使用的邮箱，建议和GitHub账号邮箱保持一致。如果不想公开邮箱，可以使用GitHub提供的noreply邮箱（可在GitHub > 设置 > 邮箱页面查看）。"
header: "邮箱"
options:
- "使用noreply邮箱" — GitHub设置>邮箱页面提供的隐私邮箱（格式为username@users.noreply.github.com）
- "手动输入" — 自行输入本人邮箱地址

获取邮箱后执行以下命令：

git config --global user.email "<用户输入的邮箱>"

단계 4: GitHub CLI 설치 확인

步骤4：检查GitHub CLI安装

완료 조건:

which gh

가 경로를 반환함

미설치인 경우, AskUserQuestion으로 설치 방법을 안내하세요:

question: "GitHub CLI(gh)가 설치되어 있지 않습니다. 어떤 방법으로 설치하시겠습니까?"
header: "gh 설치"
options:
- "Homebrew로 설치 (Recommended)" — Mac 사용자에게 권장.
```
brew install gh
```
- "직접 설치" — https://cli.github.com 에서 다운로드

Homebrew를 선택한 경우:

bash

brew install gh

직접 설치를 선택한 경우, 사용자에게 안내하세요:

아래 링크에서 GitHub CLI를 다운로드하여 설치하세요:
  https://cli.github.com

설치가 완료되면 다시 /git-onboarding-setup 을 실행해주세요.

직접 설치는 Claude가 실행할 수 없으므로 안내만 제공하고 이 단계에서 멈추세요.

完成条件：

which gh

返回可执行文件路径

如果未安装，使用AskUserQuestion告知用户安装方式：

question: "GitHub CLI(gh)尚未安装，请问你想要通过哪种方式安装？"
header: "安装gh"
options:
- "通过Homebrew安装（推荐）" — 适合Mac用户，执行命令
```
brew install gh
```
- "手动安装" — 从https://cli.github.com下载安装包

如果选择Homebrew安装，执行：

bash

brew install gh

如果选择手动安装，向用户提示：

请从以下链接下载GitHub CLI并安装：
  https://cli.github.com

安装完成后请重新执行/git-onboarding-setup

手动安装Claude无法执行，仅提供提示后停在当前步骤即可。

단계 5: GitHub 로그인

步骤5：GitHub登录

완료 조건:

gh auth status 2>&1

출력에 "Logged in"이 포함됨

GitHub에 로그인되어 있지 않은 경우, 사용자에게 안내하세요:

GitHub에 로그인해야 합니다.

터미널에서 아래 명령어를 직접 실행하세요:
  gh auth login --hostname github.com --git-protocol https --web

브라우저가 자동으로 열리고 인증 코드가 표시됩니다:
  1. 터미널에 나오는 코드를 확인
  2. 브라우저에서 코드를 입력하고 인증 완료

완료되면 다시 /git-onboarding-setup 을 실행해주세요.

gh auth login

은 브라우저 인터랙션이 필요하므로 Claude가 직접 실행하지 마세요. 안내만 제공하고 이 단계에서 멈추세요.

사용자가 완료를 알리면 인증 상태를 확인하세요:

bash

gh auth status 2>&1

"Logged in" 메시지가 나오면 성공입니다. 실패하면 로그인 과정을 다시 안내하세요.

完成条件：

gh auth status 2>&1

输出包含"Logged in"

如果未登录GitHub，向用户提示：

需要登录GitHub账号

请在终端中手动执行以下命令：
  gh auth login --hostname github.com --git-protocol https --web

执行后浏览器会自动打开并显示认证码：
  1. 确认终端显示的认证码
  2. 在浏览器中输入认证码完成授权

完成后请重新执行/git-onboarding-setup

gh auth login

需要浏览器交互操作，Claude不要直接执行，仅提供提示后停在当前步骤即可。

用户告知完成后，执行命令检查认证状态：

bash

gh auth status 2>&1

返回"Logged in"即为成功，失败则重新引导用户完成登录流程。

단계 6: 저장소 준비

步骤6：仓库准备

완료 조건:

git rev-parse --git-dir

이 성공 (현재 디렉토리가 Git 저장소)

Git 저장소가 아닌 경우, AskUserQuestion으로 방법을 물어보세요:

question: "현재 디렉토리는 Git 저장소가 아닙니다. 어떻게 시작하시겠습니까?"
header: "저장소"
options:
- "기존 저장소 clone" — GitHub에 이미 있는 저장소를 가져옴
- "새 저장소 만들기" — 현재 폴더를 Git 저장소로 초기화

clone을 선택한 경우: 저장소 URL을 물어본 후 실행하세요:

bash

git clone <URL>

새 저장소를 선택한 경우:

bash

git init

完成条件：

git rev-parse --git-dir

执行成功（当前目录为Git仓库）

如果当前目录不是Git仓库，使用AskUserQuestion询问初始化方式：

question: "当前目录不是Git仓库，请问你想要如何初始化？"
header: "仓库初始化"
options:
- "克隆现有仓库" — 拉取GitHub上已有的仓库
- "创建新仓库" — 将当前文件夹初始化为Git仓库

如果选择克隆仓库，询问仓库URL后执行：

bash

git clone <URL>

如果选择创建新仓库，执行：

bash

git init

단계 7: GitHub 원격 저장소 연결

步骤7：关联GitHub远程仓库

완료 조건:

git remote get-url origin

이 GitHub URL을 반환함

원격 저장소가 없는 경우 (

no-remote

), AskUserQuestion으로 방법을 물어보세요:

question: "GitHub에 원격 저장소를 만들겠습니까?"
header: "원격 저장소"
options:
- "새 저장소 만들기 (Recommended)" — GitHub에 저장소를 생성하고 자동으로 연결합니다
- "기존 저장소 연결" — 이미 GitHub에 있는 저장소 URL을 직접 입력

完成条件：

git remote get-url origin

返回GitHub仓库URL

如果没有关联远程仓库（返回

no-remote

），使用AskUserQuestion询问关联方式：

question: "是否需要创建GitHub远程仓库？"
header: "远程仓库关联"
options:
- "创建新仓库（推荐）" — 在GitHub创建新仓库并自动关联
- "关联现有仓库" — 手动输入GitHub上已有的仓库URL

새 저장소 만들기

创建新仓库

AskUserQuestion으로 공개 여부를 물어보세요:

question: "저장소를 공개(public)로 만들까요, 비공개(private)로 만들까요?"
header: "공개 여부"
options:
- "Public" — 누구나 볼 수 있음
- "Private (Recommended)" — 나만 볼 수 있음 (나중에 변경 가능)

현재 디렉토리 이름을 저장소 이름으로 사용합니다:

bash

gh repo create $(basename "$PWD") --source=. --remote=origin --<public|private>

--source=.

는 현재 디렉토리를 소스로 사용하고,

--remote=origin

은 자동으로 remote를 추가합니다.

使用AskUserQuestion询问仓库公开权限：

question: "仓库要设置为公开（public）还是私有（private）？"
header: "仓库权限"
options:
- "Public" — 所有人可见
- "Private（推荐）" — 仅自己可见（后续可修改权限）

使用当前目录名作为仓库名称，执行：

bash

gh repo create $(basename "$PWD") --source=. --remote=origin --<public|private>

--source=.

--remote=origin

表示自动添加origin远程关联。

기존 저장소 연결

关联现有仓库

저장소 URL을 물어본 후 실행하세요:

bash

git remote add origin <URL>

询问仓库URL后执行：

bash

git remote add origin <URL>

확인

验证

연결 후 확인하세요:

bash

git remote -v

origin의 fetch/push URL이 출력되면 성공입니다.

关联完成后执行命令验证：

bash

git remote -v

输出origin的fetch/push URL即为关联成功。

단계 8: 원격 브랜치 초기화 (첫 push)

步骤8：初始化远程分支（首次推送）

완료 조건:

git ls-remote --heads origin main 2>/dev/null

이 결과를 반환함 (원격에 main 브랜치가 존재)

아래 명령어로 확인하세요:

bash

git ls-remote --heads origin main 2>/dev/null | grep -q main && echo "remote-branch: exists" || echo "remote-branch: none"

원격에 main 브랜치가 없는 경우 (새로 만든 저장소), 초기 커밋을 만들고 push하세요:

bash

git log --oneline -1 2>/dev/null

커밋이 하나도 없으면 초기 커밋을 만드세요:

bash

git add -A
git commit -m "chore: initial commit"

원격에 push하세요:

bash

git push -u origin main

사용자에게 설명하세요:

GitHub에 main 브랜치를 생성했습니다.
이제 원격 저장소와 로컬이 연결되었습니다.

完成条件：

git ls-remote --heads origin main 2>/dev/null

返回结果（远程存在main分支）

执行以下命令检查：

bash

git ls-remote --heads origin main 2>/dev/null | grep -q main && echo "remote-branch: exists" || echo "remote-branch: none"

如果远程没有main分支（针对新创建的仓库），需要创建初始提交并推送：

bash

git log --oneline -1 2>/dev/null

如果没有任何提交，创建初始提交：

bash

git add -A
git commit -m "chore: initial commit"

推送到远程仓库：

bash

git push -u origin main

向用户说明：

已在GitHub创建main分支，现在本地仓库和远程仓库已成功关联。

단계 9: 작업 환경 선택

步骤9：选择工作场景

AskUserQuestion으로 작업 환경을 물어보세요:

question: "이 저장소는 혼자 사용하나요, 팀으로 사용하나요?"
header: "작업 환경"
options:
- "개인 프로젝트" — 혼자 작업하는 저장소 (git hooks 설치 생략)
- "팀 프로젝트 (Recommended)" — 여러 명이 함께 작업 (git hooks로 브랜치 보호)

使用AskUserQuestion询问用户工作场景：

question: "这个仓库是个人使用还是团队协作使用？"
header: "工作场景"
options:
- "个人项目" — 单人使用的仓库，跳过git hooks安装
- "团队项目（推荐）" — 多人协作的仓库，通过git hooks实现分支保护

팀 프로젝트를 선택한 경우

选择团队项目

완료 조건:

.git/hooks/pre-commit

.git/hooks/commit-msg

.git/hooks/pre-push

파일이 모두 존재하고 실행 권한이 있음

아래 명령어로 확인하세요:

bash

for hook in pre-commit commit-msg pre-push; do test -x .git/hooks/$hook && echo "$hook: exists" || echo "$hook: none"; done

없는 hook이 있으면, 플러그인의 템플릿 파일을 복사하여 설치하세요.

PLUGIN_ROOT

는 이 플러그인의

git-hooks/

디렉토리 경로입니다:

${CLAUDE_PLUGIN_ROOT}/git-hooks

bash

cp ${CLAUDE_PLUGIN_ROOT}/git-hooks/pre-commit .git/hooks/pre-commit
cp ${CLAUDE_PLUGIN_ROOT}/git-hooks/commit-msg .git/hooks/commit-msg
cp ${CLAUDE_PLUGIN_ROOT}/git-hooks/pre-push .git/hooks/pre-push
chmod +x .git/hooks/pre-commit .git/hooks/commit-msg .git/hooks/pre-push

이미 존재하는 hook은 덮어쓰지 마세요. 없는 것만 복사하세요.

각 hook의 역할을 사용자에게 설명하세요:

Git hook을 설치했습니다.

  pre-commit:  main/master에서 commit 차단 → 새 브랜치로 안내
  commit-msg:  conventional commits 형식 검증 (feat:, fix:, docs: 등)
  pre-push:    main/master로 push 차단 → 새 브랜치로 안내

터미널에서 직접 git을 사용할 때도 동일하게 보호됩니다.

完成条件：

.git/hooks/pre-commit

、

.git/hooks/commit-msg

、

.git/hooks/pre-push

文件均存在且有可执行权限

执行以下命令检查：

bash

for hook in pre-commit commit-msg pre-push; do test -x .git/hooks/$hook && echo "$hook: exists" || echo "$hook: none"; done

如果有缺失的hook，从插件模板目录复制安装，

PLUGIN_ROOT

为当前插件的

git-hooks/

目录路径：

${CLAUDE_PLUGIN_ROOT}/git-hooks

bash

cp ${CLAUDE_PLUGIN_ROOT}/git-hooks/pre-commit .git/hooks/pre-commit
cp ${CLAUDE_PLUGIN_ROOT}/git-hooks/commit-msg .git/hooks/commit-msg
cp ${CLAUDE_PLUGIN_ROOT}/git-hooks/pre-push .git/hooks/pre-push
chmod +x .git/hooks/pre-commit .git/hooks/commit-msg .git/hooks/pre-push

已存在的hook不要覆盖，仅复制缺失的文件即可。

向用户说明各个hook的作用：

已安装Git hook，功能如下：

  pre-commit:  禁止直接在main/master分支提交 → 引导使用新分支开发
  commit-msg:  校验提交信息是否符合conventional commits规范（如feat:, fix:, docs:等格式）
  pre-push:    禁止直接推送到main/master分支 → 引导使用新分支提交PR

在终端直接使用Git时也会触发以上保护规则。

개인 프로젝트를 선택한 경우

选择个人项目

Git hooks 설치를 건너뛰고 바로 완료 메시지로 넘어가세요.

跳过Git hooks安装，直接进入完成提示环节。

완료 메시지

完成提示

모든 단계가 완료되면 설정 요약을 출력하세요:

Git 초기 설정이 완료되었습니다.

  이름:    <user.name>
  이메일:  <user.email>
  GitHub:  로그인됨
  저장소:  <현재 디렉토리>
  원격:    <origin URL>
  보호:    <"팀 — main 보호 + conventional commits (git hooks)" 또는 "개인 — 없음">

다음 단계: /git-onboarding-workflow 를 실행하면 브랜치 생성부터 PR까지 안내합니다.

所有步骤完成后输出配置汇总：

Git初始配置已完成

  用户名:  <user.name>
  邮箱:    <user.email>
  GitHub:  已登录
  本地仓库: <当前目录路径>
  远程仓库: <origin URL>
  保护规则: <"团队模式 — main分支保护 + conventional commits校验（git hooks）" 或 "个人模式 — 无保护规则">

下一步：执行/git-onboarding-workflow可获取从分支创建到PR提交的全流程引导。