From 78e9493b8f4a48a853f7a0e4504b0b94c62223f2 Mon Sep 17 00:00:00 2001 From: rupy1014 Date: Sat, 13 Dec 2025 15:53:02 +0900 Subject: [PATCH] Split git auth guide into Mac and Windows versions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - git-auth-guide-mac.md: Mac 전용 가이드 (Keychain 포함) - git-auth-guide-windows.md: Windows 전용 가이드 (Credential Manager, PowerShell 포함) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/git-auth-guide-mac.md | 252 ++++++++++++++++++ ...uth-guide.md => git-auth-guide-windows.md} | 165 ++++++------ 2 files changed, 336 insertions(+), 81 deletions(-) create mode 100644 docs/git-auth-guide-mac.md rename docs/{git-auth-guide.md => git-auth-guide-windows.md} (62%) diff --git a/docs/git-auth-guide-mac.md b/docs/git-auth-guide-mac.md new file mode 100644 index 0000000..f412fd5 --- /dev/null +++ b/docs/git-auth-guide-mac.md @@ -0,0 +1,252 @@ +# Git 인증 설정 가이드 (Mac) + +이 가이드는 `git.nnotion.kr` Gitea 서버에서 Personal Access Token(PAT)을 발급받고, Mac에서 설정하는 방법을 안내합니다. + +--- + +## 목차 + +1. [Personal Access Token 발급](#1-personal-access-token-발급) +2. [인증 설정](#2-인증-설정) +3. [설정 확인](#3-설정-확인) +4. [문제 해결](#4-문제-해결) + +--- + +## 1. Personal Access Token 발급 + +### 1.1 토큰 생성 페이지 접속 + +브라우저에서 아래 주소로 이동: + +``` +https://git.nnotion.kr/user/settings/applications +``` + +또는 웹에서 수동으로 이동: + +``` +우측 상단 프로필 아이콘 → Settings → Applications +``` + +### 1.2 토큰 생성 + +1. **Token Name** 입력: `my-blog-token` (원하는 이름) +2. **Select permissions** 설정: + - ✅ `repository` → `Read and Write` 체크 +3. **Generate Token** 버튼 클릭 + +### 1.3 토큰 복사 (중요!) + +> ⚠️ **주의**: 토큰은 생성 직후 한 번만 표시됩니다! + +- 생성된 토큰을 **즉시 복사**하여 안전한 곳에 저장 +- 예시: `d262946c36480d23f57736dfe76b845706f513b0` + +--- + +## 2. 인증 설정 + +### 방법 A: 터미널 사용 (권장) + +#### 2.1 터미널 열기 + +- `Cmd + Space` → `터미널` 검색 → 실행 + +#### 2.2 호스트별 인증 설정 + +```bash +# git.nnotion.kr 전용 credential 설정 +git config --global credential.https://git.nnotion.kr.helper store + +# 인증정보 저장 +echo "https://사용자명:토큰@git.nnotion.kr" >> ~/.git-credentials +``` + +**예시** (사용자명: `jobdori`, 토큰: `abc123...`): + +```bash +echo "https://jobdori:abc123token@git.nnotion.kr" >> ~/.git-credentials +``` + +### 방법 B: macOS Keychain 사용 + +#### 2.1 Keychain 설정 + +```bash +# Keychain helper 설정 +git config --global credential.helper osxkeychain +``` + +#### 2.2 첫 Push 시 인증 + +```bash +git push -u origin main +``` + +프롬프트가 나타나면: + +``` +Username: 사용자명 +Password: 토큰 (비밀번호 아님!) +``` + +> Keychain에 자동 저장되어 이후 입력 불필요 + +### 방법 C: 프로젝트 폴더에서 직접 설정 + +```bash +# 프로젝트 폴더로 이동 +cd ~/Desktop/my-blog + +# 원격 URL에 인증정보 포함 +git remote set-url origin https://사용자명:토큰@git.nnotion.kr/Clauders/Ex1-my-blog.git +``` + +--- + +## 3. 설정 확인 + +### 3.1 원격 저장소 확인 + +```bash +git remote -v +``` + +**정상 출력:** + +``` +origin https://git.nnotion.kr/Clauders/Ex1-my-blog.git (fetch) +origin https://git.nnotion.kr/Clauders/Ex1-my-blog.git (push) +``` + +### 3.2 Push 테스트 + +```bash +git push +``` + +**성공 메시지:** + +``` +Everything up-to-date +``` + +또는 + +``` +To https://git.nnotion.kr/Clauders/Ex1-my-blog.git + abc1234..def5678 main -> main +``` + +### 3.3 Credential 설정 확인 + +```bash +# 저장된 credential 확인 +cat ~/.git-credentials +``` + +### 3.4 Keychain 확인 + +1. `Cmd + Space` → `키체인 접근` 검색 → 실행 +2. `git.nnotion.kr` 검색 +3. 저장된 인증정보 확인/수정 가능 + +--- + +## 4. 문제 해결 + +### 문제: `Authentication failed` + +**원인**: 토큰이 잘못되었거나 만료됨 + +**해결**: + +```bash +# 기존 credential 삭제 +git config --global --unset credential.helper + +# Keychain Access에서 git.nnotion.kr 항목 삭제 +# 1. Cmd + Space → 키체인 접근 +# 2. git.nnotion.kr 검색 +# 3. 해당 항목 삭제 + +# 다시 설정 +git config --global credential.https://git.nnotion.kr.helper store +``` + +### 문제: 다른 Git 서버와 충돌 + +**원인**: 전역 credential이 모든 서버에 적용됨 + +**해결**: 호스트별 credential 분리 + +```bash +# git.nnotion.kr 전용 +git config --global credential.https://git.nnotion.kr.helper store + +# github.com 전용 (필요시) +git config --global credential.https://github.com.helper osxkeychain +``` + +### 문제: `remote: Repository not found` + +**원인**: 저장소 접근 권한 없음 + +**해결**: + +1. 토큰 권한 확인 (`repository: Read and Write`) +2. 저장소 URL 확인 +3. 조직 멤버 권한 확인 + +### 문제: 토큰을 잊어버림 + +**해결**: 새 토큰 발급 + +1. https://git.nnotion.kr/user/settings/applications 접속 +2. 기존 토큰 삭제 (Revoke) +3. 새 토큰 생성 +4. `~/.git-credentials` 파일 수정 또는 재설정 + +--- + +## 부록: 유용한 명령어 + +```bash +# Git 설정 전체 확인 +git config --list + +# 특정 설정 확인 +git config --global credential.helper + +# credential 파일 위치 +# ~/.git-credentials + +# 원격 URL 변경 +git remote set-url origin [새URL] + +# 현재 브랜치 확인 +git branch + +# 푸시 +git push -u origin main + +# Keychain에서 특정 호스트 인증정보 찾기 +security find-internet-password -s git.nnotion.kr +``` + +--- + +## 요약 + +| 단계 | 명령어/작업 | +|------|-------------| +| 1. 토큰 발급 | Gitea 웹에서 생성 | +| 2. 터미널 열기 | `Cmd + Space` → 터미널 | +| 3. Credential 설정 | `git config --global credential.https://git.nnotion.kr.helper store` | +| 4. 인증정보 저장 | `echo "https://user:token@git.nnotion.kr" >> ~/.git-credentials` | +| 5. Push 테스트 | `git push` | + +--- + +*문제가 있으면 이슈를 등록해주세요: https://git.nnotion.kr/Clauders/Ex1-my-blog/issues* diff --git a/docs/git-auth-guide.md b/docs/git-auth-guide-windows.md similarity index 62% rename from docs/git-auth-guide.md rename to docs/git-auth-guide-windows.md index fcaaea0..a435297 100644 --- a/docs/git-auth-guide.md +++ b/docs/git-auth-guide-windows.md @@ -1,16 +1,15 @@ -# Git 인증 설정 가이드 +# Git 인증 설정 가이드 (Windows) -이 가이드는 `git.nnotion.kr` Gitea 서버에서 Personal Access Token(PAT)을 발급받고, Windows/Mac에서 설정하는 방법을 안내합니다. +이 가이드는 `git.nnotion.kr` Gitea 서버에서 Personal Access Token(PAT)을 발급받고, Windows에서 설정하는 방법을 안내합니다. --- ## 목차 1. [Personal Access Token 발급](#1-personal-access-token-발급) -2. [Windows 설정](#2-windows-설정) -3. [Mac 설정](#3-mac-설정) -4. [설정 확인](#4-설정-확인) -5. [문제 해결](#5-문제-해결) +2. [인증 설정](#2-인증-설정) +3. [설정 확인](#3-설정-확인) +4. [문제 해결](#4-문제-해결) --- @@ -46,7 +45,7 @@ https://git.nnotion.kr/user/settings/applications --- -## 2. Windows 설정 +## 2. 인증 설정 ### 방법 A: Git Bash 사용 (권장) @@ -67,7 +66,7 @@ echo "https://사용자명:토큰@git.nnotion.kr" >> ~/.git-credentials **예시** (사용자명: `jobdori`, 토큰: `abc123...`): ```bash -echo "https://jobdori:d262946c36480d23f57736dfe76b845706f513b0@git.nnotion.kr" >> ~/.git-credentials +echo "https://jobdori:abc123token@git.nnotion.kr" >> ~/.git-credentials ``` ### 방법 B: Windows Credential Manager 사용 @@ -87,71 +86,27 @@ echo "https://jobdori:d262946c36480d23f57736dfe76b845706f513b0@git.nnotion.kr" > - **암호**: `발급받은 토큰` 3. `확인` 클릭 -### 방법 C: 프로젝트 폴더에서 직접 설정 +### 방법 C: PowerShell 사용 -```bash -# 프로젝트 폴더로 이동 -cd 프로젝트경로 +#### 2.1 PowerShell 열기 -# 원격 URL에 인증정보 포함 -git remote set-url origin https://사용자명:토큰@git.nnotion.kr/Clauders/Ex1-my-blog.git -``` +- 시작 메뉴 → `PowerShell` 검색 → 실행 ---- +#### 2.2 인증 설정 -## 3. Mac 설정 - -### 방법 A: 터미널 사용 (권장) - -#### 3.1 터미널 열기 - -- `Cmd + Space` → `터미널` 검색 → 실행 - -#### 3.2 호스트별 인증 설정 - -```bash -# git.nnotion.kr 전용 credential 설정 +```powershell +# credential helper 설정 git config --global credential.https://git.nnotion.kr.helper store # 인증정보 저장 -echo "https://사용자명:토큰@git.nnotion.kr" >> ~/.git-credentials +Add-Content -Path "$env:USERPROFILE\.git-credentials" -Value "https://사용자명:토큰@git.nnotion.kr" ``` -**예시** (사용자명: `jobdori`, 토큰: `abc123...`): - -```bash -echo "https://jobdori:d262946c36480d23f57736dfe76b845706f513b0@git.nnotion.kr" >> ~/.git-credentials -``` - -### 방법 B: macOS Keychain 사용 - -#### 3.1 Keychain 설정 - -```bash -# Keychain helper 설정 -git config --global credential.helper osxkeychain -``` - -#### 3.2 첫 Push 시 인증 - -```bash -git push -u origin main -``` - -프롬프트가 나타나면: - -``` -Username: 사용자명 -Password: 토큰 (비밀번호 아님!) -``` - -> Keychain에 자동 저장되어 이후 입력 불필요 - -### 방법 C: 프로젝트 폴더에서 직접 설정 +### 방법 D: 프로젝트 폴더에서 직접 설정 ```bash # 프로젝트 폴더로 이동 -cd ~/Desktop/my-blog +cd C:\Users\사용자명\Desktop\my-blog # 원격 URL에 인증정보 포함 git remote set-url origin https://사용자명:토큰@git.nnotion.kr/Clauders/Ex1-my-blog.git @@ -159,9 +114,9 @@ git remote set-url origin https://사용자명:토큰@git.nnotion.kr/Clauders/Ex --- -## 4. 설정 확인 +## 3. 설정 확인 -### 4.1 원격 저장소 확인 +### 3.1 원격 저장소 확인 ```bash git remote -v @@ -174,7 +129,7 @@ origin https://git.nnotion.kr/Clauders/Ex1-my-blog.git (fetch) origin https://git.nnotion.kr/Clauders/Ex1-my-blog.git (push) ``` -### 4.2 Push 테스트 +### 3.2 Push 테스트 ```bash git push @@ -193,16 +148,35 @@ To https://git.nnotion.kr/Clauders/Ex1-my-blog.git abc1234..def5678 main -> main ``` -### 4.3 Credential 설정 확인 +### 3.3 Credential 설정 확인 + +**Git Bash:** ```bash -# 저장된 credential 확인 cat ~/.git-credentials ``` +**PowerShell:** + +```powershell +Get-Content "$env:USERPROFILE\.git-credentials" +``` + +**파일 위치:** + +``` +C:\Users\사용자명\.git-credentials +``` + +### 3.4 Credential Manager 확인 + +1. `Win + R` → `control` → `사용자 계정` → `자격 증명 관리자` +2. `Windows 자격 증명` 탭 +3. `git:https://git.nnotion.kr` 항목 확인 + --- -## 5. 문제 해결 +## 4. 문제 해결 ### 문제: `Authentication failed` @@ -213,11 +187,18 @@ cat ~/.git-credentials ```bash # 기존 credential 삭제 git config --global --unset credential.helper +``` -# Windows: Credential Manager에서 해당 항목 삭제 -# Mac: Keychain Access에서 git.nnotion.kr 항목 삭제 +그리고 Credential Manager에서 삭제: -# 다시 설정 +1. `Win + R` → `control` → `사용자 계정` → `자격 증명 관리자` +2. `Windows 자격 증명` 탭 +3. `git:https://git.nnotion.kr` 항목 찾기 +4. `제거` 클릭 + +다시 설정: + +```bash git config --global credential.https://git.nnotion.kr.helper store ``` @@ -232,7 +213,7 @@ git config --global credential.https://git.nnotion.kr.helper store git config --global credential.https://git.nnotion.kr.helper store # github.com 전용 (필요시) -git config --global credential.https://github.com.helper store +git config --global credential.https://github.com.helper manager ``` ### 문제: `remote: Repository not found` @@ -252,12 +233,22 @@ git config --global credential.https://github.com.helper store 1. https://git.nnotion.kr/user/settings/applications 접속 2. 기존 토큰 삭제 (Revoke) 3. 새 토큰 생성 -4. `~/.git-credentials` 파일 수정 또는 재설정 +4. `.git-credentials` 파일 수정 또는 재설정 + +### 문제: Git Bash가 설치되어 있지 않음 + +**해결**: Git for Windows 설치 + +1. https://git-scm.com/download/win 접속 +2. 다운로드 및 설치 +3. 설치 시 "Git Bash Here" 옵션 체크 --- ## 부록: 유용한 명령어 +**Git Bash:** + ```bash # Git 설정 전체 확인 git config --list @@ -266,8 +257,7 @@ git config --list git config --global credential.helper # credential 파일 위치 -# Windows: C:\Users\사용자명\.git-credentials -# Mac: ~/.git-credentials +# C:\Users\사용자명\.git-credentials # 원격 URL 변경 git remote set-url origin [새URL] @@ -279,17 +269,30 @@ git branch git push -u origin main ``` +**PowerShell:** + +```powershell +# Git 설정 확인 +git config --list + +# credential 파일 확인 +Get-Content "$env:USERPROFILE\.git-credentials" + +# credential 파일 열기 (메모장) +notepad "$env:USERPROFILE\.git-credentials" +``` + --- ## 요약 -| 단계 | Windows | Mac | -|------|---------|-----| -| 1. 토큰 발급 | Gitea 웹에서 생성 | 동일 | -| 2. 터미널 열기 | Git Bash | 터미널 | -| 3. Credential 설정 | `credential.helper store` | 동일 또는 `osxkeychain` | -| 4. 인증정보 저장 | `~/.git-credentials` | 동일 | -| 5. Push 테스트 | `git push` | 동일 | +| 단계 | 명령어/작업 | +|------|-------------| +| 1. 토큰 발급 | Gitea 웹에서 생성 | +| 2. Git Bash 열기 | 시작 메뉴 → Git Bash | +| 3. Credential 설정 | `git config --global credential.https://git.nnotion.kr.helper store` | +| 4. 인증정보 저장 | `echo "https://user:token@git.nnotion.kr" >> ~/.git-credentials` | +| 5. Push 테스트 | `git push` | ---