git:config:ko [Command Line Interface Helper]

이 문서는 읽기 전용입니다. 원본을 볼 수는 있지만 바꿀 수는 없습니다. 문제가 있다고 생각하면 관리자에게 문의하세요.
{{tag>[git config credential authentication ssh https oauth]}}

====== Git config와 인증 ======
Git configuration의 scope와 우선순위, ''credential.helper'', HTTPS token/OAuth, SSH key 인증을 안전하게 구성하는 방법.

===== Summary =====
Git remote 인증은 remote URL scheme에 따라 크게 HTTPS와 SSH로 나뉜다.

  * HTTPS: username과 password 형식의 credential을 사용한다. Hosting service에 따라 password 자리에 personal access token을 입력하거나 OAuth credential helper로 browser login을 수행한다.
  * SSH: private key로 서명하고 server가 등록된 public key를 확인한다. ''credential.helper''는 SSH key를 저장하거나 관리하지 않는다.
  * ''git config user.name''과 ''user.email''은 commit 작성자 정보이며 remote login 계정이나 인증 credential이 아니다.

===== Usage =====
<code bash>
git config [<options>]
git config [--system|--global|--local|--worktree] KEY VALUE
git config --list --show-origin --show-scope
</code>

  * ''<color #c3c3c3>**git**</color> <color #ff7f27>config</color> <color #22b14c>--global</color> <color #7092be>KEY VALUE</color>'': 사용자 전역 설정을 기록한다.
  * ''<color #c3c3c3>**git**</color> <color #ff7f27>config</color> <color #22b14c>--local</color> <color #7092be>KEY VALUE</color>'': 현재 repository의 ''.git/config''에 기록한다.
  * ''<color #c3c3c3>**git**</color> <color #ff7f27>config</color> <color #22b14c>--get-all</color> <color #7092be>credential.helper</color>'': 여러 scope에서 적용되는 helper 값을 모두 확인한다.

===== Config files and precedence =====
일반적인 낮은 우선순위에서 높은 우선순위 순서는 system, global, local, worktree, command scope다. 같은 key가 여러 scope에 있으면 더 구체적인 scope가 우선하지만, ''credential.helper''처럼 여러 값을 허용하는 key는 값이 누적될 수 있다.

  * System: ''/etc/gitconfig'' 또는 platform의 system config
  * Global: ''~/.gitconfig'', ''$XDG_CONFIG_HOME/git/config''
  * Local: repository의 ''.git/config''
  * Worktree: ''extensions.worktreeConfig''를 활성화한 repository의 ''config.worktree''
  * Command: ''git -c KEY=VALUE ...'' 또는 관련 environment

<code bash>
# 실제 값, file 위치, scope를 함께 확인
git config --list --show-origin --show-scope

# 특정 key의 모든 값 확인
git config --show-origin --show-scope --get-all credential.helper

# 사용자 설정 편집
git config --global --edit
</code>

<note tip>
인증 문제가 발생하면 ''git config credential.helper'' 한 줄만 보지 말고 ''--get-all'', ''--show-origin'', ''--show-scope''를 함께 사용한다. system helper와 global helper가 동시에 등록된 경우가 있다.
</note>

===== Common settings =====
<code bash>
git config --global user.name "NAME"
git config --global user.email "EMAIL@example.com"
git config --global core.editor "code --wait"

# 현재 repository에만 다른 identity 적용
git config --local user.name "WORK NAME"
git config --local user.email "WORK-EMAIL@example.com"

# 값 읽기와 삭제
git config --get user.name
git config --global --unset user.name
</code>

==== Line endings ====
기존 기록의 ''core.autocrlf'' 설정은 platform과 repository 정책에 맞게 사용한다.

<code bash>
# Windows checkout에서 CRLF, commit에서는 LF
git config --global core.autocrlf true

# macOS/Linux에서 checkout 변환 없이 commit 시 CRLF를 LF로 정규화
git config --global core.autocrlf input
</code>

Repository가 ''.gitattributes''로 line ending을 고정한다면 그 정책을 우선한다. 설정 변경 후 기존 file 전체가 수정된 것처럼 보일 수 있으므로 clean worktree에서 적용하고 ''git diff --check''로 확인한다.

==== Alias ====
<code bash>
git config --global alias.lg "log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"
git lg
</code>

  * ''<color #c3c3c3>**git**</color> <color #ff7f27>config</color> <color #22b14c>--global</color> <color #7092be>alias.NAME "COMMAND"</color>'': alias를 설정한다.
  * ''<color #c3c3c3>**git**</color> <color #ff7f27>NAME</color>'': 등록한 alias를 실행한다.

===== HTTPS authentication =====
HTTPS remote에서는 Git이 credential helper에 ''get'', ''store'', ''erase'' 요청을 전달한다. Helper가 credential을 제공하지 못하면 ''GIT_ASKPASS'', ''core.askPass'', ''SSH_ASKPASS'', terminal prompt 순서로 입력을 요청할 수 있다.

<code bash>
git remote -v
git config --global --get-all credential.helper
git help -a
</code>

Hosting service가 account password 기반 Git 인증을 허용하지 않으면 personal access token을 password 입력란에 사용하거나 OAuth helper로 로그인한다. Token scope와 만료 기간은 필요한 repository 작업에 필요한 최소 범위로 제한한다.

<note warning>
Token, password, private key를 remote URL, shell history, tracked ''.gitconfig'', wiki, script에 넣지 않는다. ''https://USER:TOKEN@example.com/repo.git'' 형식은 process 목록, log, config와 history에 노출될 수 있다.
</note>

==== credential.helper 선택 ====
안전한 persistent storage가 필요하면 OS keychain 또는 OAuth helper를 우선한다.

^ Environment ^ Helper 예 ^ 특성 ^
| Git Credential Manager | ''manager'' | Windows, macOS, Linux에서 HTTPS와 OAuth/MFA를 지원한다. Git for Windows에 포함된다. |
| Linux desktop | ''libsecret'' | Secret Service를 사용하는 secure persistent storage. Helper가 별도로 설치되어 있어야 한다. |
| macOS | ''osxkeychain'' | macOS Keychain에 persistent storage. |
| Windows legacy | ''wincred'' | Windows Credential Manager 사용. 새 구성은 Git Credential Manager를 우선 검토한다. |
| Unix-like temporary | ''cache'' | memory에 임시 저장하며 기본 timeout은 900초다. Reboot 또는 daemon 종료 시 사라진다. |
| 모든 platform | ''store'' | disk에 무기한 평문 저장. 보안 tradeoff를 이해한 제한된 환경 외에는 권장하지 않는다. |

Helper가 실제로 설치되어 있는지 먼저 확인하고 구성한다.

<code bash>
# 설치된 credential helper 탐색
git help -a

# Git Credential Manager
git config --global credential.helper manager

# macOS Keychain
git config --global credential.helper osxkeychain

# Linux Secret Service
git config --global credential.helper libsecret

# Unix-like system에서 1시간 memory cache
git config --global credential.helper 'cache --timeout=3600'
</code>

<note important>
''cache''는 long-lived personal access token의 persistent storage에 적합하지 않다. ''store''는 ''~/.git-credentials'' 또는 ''$XDG_CONFIG_HOME/git/credentials''에 credential을 암호화하지 않고 기록한다.
</note>

기존 환경과의 호환 때문에 ''store''를 사용해야 한다면 다음 설정의 위험과 file permission을 먼저 검토한다.

<code bash>
git config credential.helper store
</code>

==== Host별 설정 ====
같은 host의 여러 repository가 서로 다른 credential을 사용한다면 URL context를 좁힌다.

<code bash>
git config --global credential.https://example.com.username USERNAME
git config --global credential.useHttpPath true
</code>

''credential.useHttpPath=true''는 HTTPS credential을 host뿐 아니라 URL path까지 구분한다. 같은 host의 모든 repository가 같은 계정을 사용하는 환경에서는 불필요할 수 있다.

==== Helper 변경과 credential 삭제 ====
먼저 모든 scope의 helper를 확인한 후 변경한다.

<code bash>
git config --show-origin --show-scope --get-all credential.helper
git config --global --unset-all credential.helper
</code>

저장된 HTTPS credential을 지울 때 secret을 command line에 쓰지 않는다.

<code bash>
printf 'protocol=https\nhost=example.com\n\n' | git credential reject

# memory cache 전체를 즉시 종료하고 삭제
git credential-cache exit
</code>

OS keychain 또는 Git Credential Manager에 남은 항목은 해당 helper나 OS credential UI에서도 확인한다. ''credential.helper'' 설정을 지우는 것과 이미 저장된 credential을 삭제하는 것은 별도 작업이다.

===== SSH authentication =====
SSH remote는 ''git@example.com:OWNER/REPOSITORY.git'' 또는 ''ssh://git@example.com/OWNER/REPOSITORY.git'' 형식을 사용한다.

<code bash>
git remote -v
git remote set-url origin git@example.com:OWNER/REPOSITORY.git

# agent 시작과 private key 등록
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# host key와 계정 인증 확인
ssh -T git@example.com
</code>

  * Public key만 hosting service나 Git server 계정에 등록한다.
  * Private key는 공유하거나 repository에 commit하지 않고 permission을 제한한다.
  * 처음 접속할 때 표시되는 host key fingerprint는 hosting service의 공식 문서나 관리자가 제공한 값과 대조한다.
  * 여러 계정이나 key를 사용하면 ''~/.ssh/config''의 ''Host'', ''HostName'', ''User'', ''IdentityFile'', ''IdentitiesOnly''를 이용해 alias별로 분리한다.

<note important>
SSH private key passphrase와 remote account password는 서로 다르다. ''ssh-agent''는 복호화된 private key 사용 권한을 session 동안 중개하며 ''credential.helper''와 독립적으로 동작한다.
</note>

===== Troubleshooting =====
==== 계속 credential을 묻는 경우 ====
  - ''git remote -v''로 HTTPS인지 SSH인지 확인한다.
  - ''git config --show-origin --show-scope --get-all credential.helper''로 helper 중복과 source를 확인한다.
  - 선택한 helper executable이 설치되어 있고 현재 Git에서 보이는지 확인한다.
  - 잘못 저장된 credential을 ''git credential reject''와 OS keychain에서 삭제하고 다시 인증한다.
  - Host의 token 만료, scope, SSO 승인, account 정책을 확인한다.

==== 잘못된 계정이 선택되는 경우 ====
  * HTTPS: host별 username, ''credential.useHttpPath'', OAuth helper의 account binding을 확인한다.
  * SSH: ''ssh -vT git@example.com''으로 제시되는 key를 확인하고 ''~/.ssh/config''에서 account별 host alias를 사용한다.

==== Automation / CI ====
Interactive prompt가 없어야 하는 환경에서는 credential helper UI를 기대하지 않는다.

<code bash>
git -c credential.interactive=false fetch
</code>

CI provider의 secret store와 short-lived token을 사용하고 log redaction을 확인한다. Token을 tracked Git config나 remote URL에 영구 저장하지 않는다.

===== Help =====
++++ git config -h |
<code text>
usage: git config [<options>]

Config file location
    --[no-]global         use global config file
    --[no-]system         use system config file
    --[no-]local          use repository config file
    --[no-]worktree       use per-worktree config file
    -f, --[no-]file <file>
                          use given config file
    --[no-]blob <blob-id> read config from given blob object

Action
    --[no-]get            get value: name [value-pattern]
    --[no-]get-all        get all values: key [value-pattern]
    --[no-]get-regexp     get values for regexp: name-regex [value-pattern]
    --[no-]get-urlmatch   get value specific for the URL: section[.var] URL
    --[no-]replace-all    replace all matching variables: name value [value-pattern]
    --[no-]add            add a new variable: name value
    --[no-]unset          remove a variable: name [value-pattern]
    --[no-]unset-all      remove all matches: name [value-pattern]
    --[no-]rename-section rename section: old-name new-name
    --[no-]remove-section remove a section: name
    -l, --[no-]list       list all
    --[no-]fixed-value    use string equality when comparing values to 'value-pattern'
    -e, --[no-]edit       open an editor
    --[no-]get-color      find the color configured: slot [default]
    --[no-]get-colorbool  find the color setting: slot [stdout-is-tty]

Type
    -t, --[no-]type <type>
                          value is given this type
    --bool                value is "true" or "false"
    --int                 value is decimal number
    --bool-or-int         value is --bool or --int
    --bool-or-str         value is --bool or string
    --path                value is a path (file or directory name)
    --expiry-date         value is an expiry date

Other
    -z, --[no-]null       terminate values with NUL byte
    --[no-]name-only      show variable names only
    --[no-]includes       respect include directives on lookup
    --[no-]show-origin    show origin of config
    --[no-]show-scope     show scope of config
    --[no-]default <value>
                          with --get, use default value when missing entry
</code>
++++

===== See Also =====
  * [[git:ko|Git]]
  * [[https://git-scm.com/docs/git-config|git-config Documentation]]
  * [[https://git-scm.com/docs/gitcredentials|gitcredentials Documentation]]
  * [[https://git-scm.com/docs/git-credential-cache|git-credential-cache Documentation]]
  * [[https://git-scm.com/docs/git-credential-store|git-credential-store Documentation]]
  * [[https://git-scm.com/doc/credential-helpers|Git credential helpers]]
  * [[https://github.com/git-ecosystem/git-credential-manager|Git Credential Manager]]

===== History =====
  * codex:: 2026-07-26 Added Git configuration scopes, credential helper selection, HTTPS token/OAuth, SSH authentication, credential removal, and troubleshooting guidance.

{{indexmenu>.#1|js}}