Git 설정 문제 해결: 일반적인 해결 방법과 모범 사례
설정 출처 추적, 신원, 별칭, 훅, 줄 끝, 풀, 자격 증명 문제를 해결하여 Git 설정 문제를 수정합니다.
Git 설정 문제 해결: 일반적인 해결 방법과 모범 사례
대부분의 Git 설정 문제는 생각보다 이상하지 않습니다. Git은 일반적으로 설정 파일 중 하나가 지시한 대로 정확히 동작합니다. 어려운 점은 어떤 파일인지 찾는 것입니다. 설정이 저장소, 사용자 설정, 시스템 설정, 포함된 파일, 또는 특정 디렉토리에서만 적용되는 조건부 포함에 있을 수 있기 때문입니다.
제가 가장 먼저 사용하는 명령어는 다음과 같습니다:
git config --list --show-origin --show-scope
Git 버전이 --show-scope를 지원하지 않는 경우 다음을 사용하세요:
git config --list --show-origin
출처는 각 값을 제공한 파일을 알려줍니다. 이는 값 자체보다 더 중요합니다. [email protected]을 보는 것만으로는 충분하지 않습니다. .git/config, ~/.gitconfig, /etc/gitconfig, 또는 포함된 작업 프로필에서 왔는지 알아야 합니다.
Git 설정에는 우선 순위가 있습니다. 로컬 저장소 설정은 일반적으로 전역 사용자 설정을 이기고, 전역 설정은 시스템 설정을 이깁니다. 명령줄 옵션과 환경 변수는 하나의 명령에 대해 이 모든 것을 재정의할 수 있습니다. 조건부 포함은 또 다른 계층을 추가합니다: 전역 파일이 "이 디렉토리 안에 있을 때, 이 다른 설정도 로드하라"고 말할 수 있습니다.
하나의 설정을 출처와 함께 검사할 수 있습니다:
git config --show-origin --get user.email
git config --show-origin --get core.autocrlf
git config --show-origin --get-regexp '^alias\.'
이 습관은 많은 불필요한 편집을 방지합니다. 저장소에 user.email이 로컬로 설정되어 있다면, git config --global user.email을 변경해도 해당 저장소의 커밋에 영향을 미치지 않습니다.
커밋에 잘못된 이름 또는 이메일
증상은 간단합니다: 커밋에 잘못된 작성자가 표시됩니다. 이는 동일한 노트북을 업무와 개인 프로젝트에 사용하거나, 회사 이메일을 설정하기 전에 회사 저장소를 클론할 때 자주 발생합니다.
현재 저장소에서 Git이 사용할 값을 확인하세요:
git config user.name
git config user.email
git config --show-origin --get user.email
기본 신원을 전역으로 설정하세요:
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
하나의 저장소에 대해 로컬로 설정하세요:
git config --local user.name "Your Name"
git config --local user.email "[email protected]"
신원이 명시적으로 설정되지 않은 경우 Git이 커밋을 거부하도록 하려면 다음을 사용하세요:
git config --global user.useConfigOnly true
이 설정은 신원을 전환하는 사람들에게 유용합니다. Git이 시스템 사용자 이름과 호스트 이름에서 추측하는 것을 중단하기 때문에 초보자에게는 불편할 수 있습니다. 잘못된 주소로 커밋을 생성하는 것보다 커밋을 실패시키는 것이 나은 경우에 사용하세요.
더 깔끔한 업무/개인 분리를 위해 조건부 포함을 사용하세요:
# ~/.gitconfig
[user]
name = Your Name
email = [email protected]
[includeIf "gitdir:~/work/"]
path = ~/.gitconfig-work
그런 다음 ~/.gitconfig-work에 다음을 넣으세요:
[user]
email = [email protected]
gitdir:~/work/의 후행 슬래시는 해당 디렉토리 아래의 저장소를 의미하므로 중요합니다. 작동하지 않으면 작업 저장소 내에서 git config --list --show-origin을 실행하고 포함된 파일이 나타나는지 확인하세요.
이미 잘못된 이메일로 커밋을 만든 경우, 설정을 변경해도 미래의 커밋만 수정됩니다. 게시되지 않은 커밋의 경우 수정 또는 리베이스할 수 있습니다. 공유 브랜치에 이미 푸시된 커밋의 경우 기록을 다시 쓰기 전에 물어보세요.
작동하지 않는 별칭
Git 별칭은 alias.* 아래에 저장됩니다. 다음과 같이 나열하세요:
git config --get-regexp '^alias\.'
일반 별칭은 Git 하위 명령으로 확장됩니다:
git config --global alias.st 'status -sb'
git st
별칭이 셸 파이프라인, 변수 확장, cd 또는 다른 Git 명령이 아닌 것을 필요로 하는 경우 !로 시작해야 합니다:
git config --global alias.recent '!git for-each-ref --sort=-committerdate --count=10 --format="%(refname:short)" refs/heads/'
!가 없으면 Git은 첫 번째 단어를 Git 명령으로 처리하려고 합니다. ls -la는 "ls라는 Git 명령 실행"이 되며, 이는 의도한 바가 아닙니다.
인용은 또 다른 일반적인 실패입니다. 셸에서 별칭을 정의하는 경우 가능하면 전체 별칭을 작은따옴표로 묶고, 필요에 따라 내부에 큰따옴표를 사용하세요. 다른 셸, 특히 PowerShell과 cmd.exe는 인용을 다르게 처리합니다. 복잡한 별칭이 계속 깨지면 설정 파일을 직접 편집하세요:
git config --global --edit
실용적인 디버그 팁은 Git 외부에서 명령을 시작하는 것입니다. 작동하면 별칭에 붙여넣으세요. 셸 별칭인 경우 !를 접두사로 추가하고 다시 테스트하세요.
또한 정신 모델을 가리는 별칭을 주의하세요. pull 또는 merge라는 별칭은 Git 동작을 예상치 못하게 만들 수 있습니다. Git은 별칭이 내장 명령을 직접 재정의하는 것을 허용하지 않지만, 셸 별칭과 래퍼 스크립트는 가능합니다. git pull이 이상하게 동작하면 셸 설정도 확인하세요:
type git
alias | grep git
실행되지 않는 훅
훅은 세 가지 지루한 이유로 실패합니다: Git이 다른 훅 디렉토리를 보고 있거나, 파일이 실행 가능하지 않거나, 스크립트가 없는 환경을 가정합니다.
설정된 훅 경로를 확인하세요:
git config --show-origin --get core.hooksPath
이것이 .githooks를 출력하면 Git은 .githooks/pre-commit을 사용하고, .git/hooks/pre-commit을 사용하지 않습니다. 아무것도 출력하지 않으면 Git은 .git/hooks를 사용합니다.
macOS 및 Linux에서 권한을 확인하세요:
ls -l .git/hooks/pre-commit .githooks/pre-commit 2>/dev/null
chmod +x .githooks/pre-commit
0이 아닌 상태로 종료되는 훅은 Git 작업을 차단합니다. 상단 근처에 임시 추적을 추가하세요:
#!/usr/bin/env bash
set -x
pwd
env | sort
공유 훅에 시끄러운 추적을 남기지 마세요. 빠르게 읽을 수 없게 됩니다.
GUI 클라이언트에서 경로 문제가 일반적입니다. 터미널에서 작동하는 훅이 IDE에서 실패할 수 있습니다. IDE가 셸 프로필을 로드하지 않았기 때문입니다. 가능하면 프로젝트 로컬 명령을 선호하세요:
./node_modules/.bin/eslint .
또는 명령을 확인하고 유용한 메시지를 출력하세요:
if ! command -v npm >/dev/null 2>&1; then
echo "npm is required for this hook but was not found in PATH."
exit 1
fi
줄 끝이 계속 변경됨
줄 끝 문제는 체크아웃 직후 수정된 것으로 보이는 파일, 모든 줄이 변경된 큰 diff, 또는 Windows에서 편집 후 Linux에서 실패하는 스크립트로 나타납니다.
설정을 확인하세요:
git config --show-origin --get core.autocrlf
git config --show-origin --get core.eol
일반적인 선택은 다음과 같습니다:
# Windows 친화적 체크아웃, 저장소에서는 LF
git config --global core.autocrlf true
# macOS/Linux 친화적: 커밋 시에만 CRLF를 LF로 변환
git config --global core.autocrlf input
# 자동 변환 없음
git config --global core.autocrlf false
팀의 경우 .gitattributes가 모든 개발자에게 전역 설정을 올바르게 지정하도록 하는 것보다 더 신뢰할 수 있습니다. 저장소에 프로젝트 규칙을 넣으세요:
* text=auto
*.sh text eol=lf
*.bat text eol=crlf
*.png binary
*.jpg binary
*.pdf binary
.gitattributes를 추가하거나 변경한 후 파일을 의도적으로 정규화하세요:
git add --renormalize .
git status
해당 diff를 주의 깊게 검토하세요. 많은 파일에 영향을 줄 수 있으며, 줄 끝 정규화를 기능 작업과 혼합하고 싶지 않을 것입니다.
풀, 푸시 또는 병합이 잘못된 기본값 사용
때로는 설정 문제가 신원이나 줄 끝이 아닙니다. Git이 예상하지 못한 풀 전략을 선택하는 것입니다.
풀 관련 설정을 확인하세요:
git config --show-origin --get pull.rebase
git config --show-origin --get pull.ff
git config --show-origin --get branch.main.rebase
git pull이 병합을 예상했는데 계속 리베이스하는 경우 pull.rebase 또는 브랜치별 설정이 활성화되어 있을 수 있습니다. 빨리 감기가 아닌 풀을 거부하는 경우 pull.ff=only가 설정되어 있을 수 있습니다. 이러한 설정은 그 자체로 잘못된 것이 아닙니다. 팀의 워크플로우와 일치해야 합니다.
경고와 놀라움을 견디는 대신 명시적 기본값을 설정하세요:
# 풀 시 병합
git config --global pull.rebase false
# 풀 시 리베이스
git config --global pull.rebase true
# 빨리 감기 풀만 허용
git config --global pull.ff only
하나의 브랜치에 대해:
git config branch.main.rebase true
자격 증명 도우미 혼동
인증 문제는 종종 원격 문제처럼 보이지만 로컬 설정에서 비롯됩니다. Git은 오래된 토큰이 캐시된 자격 증명 도우미를 사용할 수 있습니다.
도우미를 확인하세요:
git config --show-origin --get-all credential.helper
osxkeychain, manager, manager-core, store 또는 cache가 표시될 수 있습니다. 여러 도우미가 존재할 수 있습니다. Git이 계속 잘못된 자격 증명을 보내면 임의의 원격 URL을 변경하는 대신 OS 키체인 또는 자격 증명 관리자에서 제거하세요.
또한 원격을 확인하세요:
git remote -v
SSH와 HTTPS는 다른 인증 경로를 사용합니다. 하나의 저장소가 [email protected]:org/repo.git을 사용하고 다른 저장소가 https://github.com/org/repo.git을 사용하는 경우 동일한 자격 증명을 사용하지 않을 수 있습니다.
신뢰할 수 있는 디버깅 루틴
Git 설정이 일관되지 않게 느껴질 때 추측 대신 루틴을 사용하세요:
- 저장소 루트에서 실패하는 명령을 실행하세요.
git config --show-origin --get <name>으로 정확한 설정을 검사하세요.git config --list --show-origin --show-scope로 관련 설정을 나열하세요.- 전역 설정을 변경하기 전에
.git/config에서 로컬 설정을 확인하세요. - 문제가 하나의 디렉토리에서만 발생하는 경우 조건부 포함을 확인하세요.
- 가장 작은 설정 변경을 하고 원래 명령을 다시 실행하세요.
Git 설정은 계층화될 수 있기 때문에 강력합니다. 그것이 또한 혼란스러워지는 이유입니다. 해결책은 계층을 보이게 만든 다음 실제로 승리하는 계층을 변경하는 것입니다.
IDE 내에서 설정이 다른 경우
혼란스러운 Git 문제 클래스는 편집기 또는 GUI 내에서만 나타납니다. 터미널은 하나의 신원을 사용하지만 IDE는 다른 신원으로 커밋합니다. 훅은 셸에서 통과하지만 커밋 패널에서 실패합니다. 자격 증명 프롬프트가 터미널에 나타나는 반면 GUI는 이전 토큰으로 조용히 재시도합니다.
이유는 일반적으로 환경입니다. 대화형 셸은 .bashrc, .zshrc, SDK 관리자, 언어 버전 관리자 및 사용자 정의 PATH 항목을 로드할 수 있습니다. 데스크톱에서 실행된 GUI는 이 중 어떤 것도 로드하지 않을 수 있습니다. Git 자체는 동일한 설정 파일을 읽지만 훅과 자격 증명 도우미는 다른 세계를 볼 수 있습니다.
디버그하려면 환경을 로컬 파일에 출력하는 임시 훅을 만드세요:
#!/usr/bin/env bash
{
date
pwd
git --version
git config --list --show-origin
env | sort
} > /tmp/git-hook-debug.log
exit 1
IDE에서 Git 작업을 실행한 다음 /tmp/git-hook-debug.log를 검사하세요. 그 후 훅을 제거하세요. 이렇게 하면 터미널이 보는 것이 아니라 Git과 훅이 실제로 본 것을 알 수 있습니다.
GUI 클라이언트의 신원 문제의 경우 도구에 자체 Git 설정이 있는지 확인하세요. 일부 클라이언트는 시스템 Git을 사용하고, 다른 클라이언트는 Git을 번들로 제공하거나 사용자 신원을 애플리케이션 기본 설정에 저장합니다. 클라이언트가 Git을 통해 커밋하는 경우 git log --format=fuller -1은 결과 작성자와 커미터를 표시합니다. 이는 "Git 설정이 잘못되었음"과 "GUI가 자체 설정을 사용했음"을 구분하는 데 도움이 됩니다.
의심스러운 경우 중요한 프로젝트에 대해 저장소 로컬 설정을 명시적으로 만드세요:
git config --local user.email "[email protected]"
git config --local core.hooksPath .githooks
로컬 설정은 해당 머신의 저장소 메타데이터와 함께 이동하기 때문에 놀라움을 줄입니다. 여전히 커밋되지 않으므로 공유 규칙은 .gitattributes, .editorconfig, 훅 스크립트 및 프로젝트 문서와 같은 추적된 파일에 있어야 합니다.
알려진 양호 기준 유지
설정 문제가 계속 돌아오면 자신의 머신에 대한 작은 알려진 양호 기준을 저장하세요. 화려할 필요는 없습니다. 신원, 편집기, 기본 브랜치 동작, 자격 증명 도우미 및 포함이 포함된 주석 처리된 ~/.gitconfig면 충분합니다. 그런 다음 새 노트북이 다르게 동작할 때 모든 설정을 다시 발견하는 대신 비교할 수 있습니다.
유용한 기준 확인 사항:
git config --global --list --show-origin
git config --global --get core.editor
git config --global --get init.defaultBranch
git config --global --get-all credential.helper
인터넷이나 동료로부터 설정을 복사할 때 주의하세요. 별칭은 가지고 있지 않은 도구를 가정할 수 있습니다. 자격 증명 도우미는 플랫폼별입니다. 줄 끝 설정은 해당 OS에는 맞지만 사용자 OS에는 맞지 않을 수 있습니다. Git 설정을 셸 설정처럼 취급하세요: 아이디어를 빌리되 각 줄을 유지하기 전에 이해하세요.
프로젝트 유지 관리자의 경우 가장 좋은 해결책은 공유 기대치를 개인 설정에서 옮기는 것입니다. 줄 끝을 .gitattributes에, 서식을 포맷터 설정에, 무시된 파일을 .gitignore에, 필요한 검사를 CI에 넣으세요. 프로젝트가 보이지 않는 전역 설정에 덜 의존할수록 생성되는 설정 티켓이 줄어듭니다.
문제를 해결하기 위해 설정을 변경할 때 로컬인지 전역인지 기록하세요. 많은 미래의 Git 미스터리는 6개월 후에 아무도 기억하지 못하는 좋은 임시 로컬 수정으로 시작됩니다.