Git
PR

git configの使い方:–global・–localの違いと設定の確認方法

git configの使い方:--global・--localの違いと設定の確認方法
hr
記事内に商品プロモーションを含む場合があります

「--global を付けるのと付けないのとで何が違うの?」「設定したはずなのに効かない。どこの設定が使われているの?」――Git の設定コマンド git config は、こうした疑問が出やすいところです。この記事では、設定の 3 つの範囲と優先順位、設定の場所の調べ方、よく使う設定、仕事用と個人用のメールアドレスの自動切り替えまでを、実行結果つきで説明します。

コマンドと実行結果は、Windows 11 の Git Bash(git version 2.49.0.windows.1)で実際に実行して確かめたものです。自分の本物の設定を書き換えないよう、検証用のフォルダーを「ホーム」に見立てて試しています。仕様は Git の公式ドキュメント(git-config)の原文で確認しました。インストール直後の名前とメールアドレスの設定は「Git入門」で説明しているので、この記事ではその先を扱います。

この記事で分かること

  • system・global・local の 3 つの範囲と、どれが優先されるか
  • --show-origin・--show-scope で「どこの設定か」を調べる方法
  • 値の取り出し(--get)と終了コード、設定の削除(--unset)
  • alias・core.quotepath・core.editor などよく使う設定
  • includeIf でフォルダーごとにメールアドレスを切り替える方法

git config の 3 つの範囲と優先順位

Git の設定は、効く範囲の違う 3 つのファイルに書けます。どのファイルに書くかは、git config に付けるオプションで決まります。

範囲(scope)オプション効く範囲ファイル(Git for Windows の例)
system–systemパソコンのすべてのユーザーC:\Program Files\Git\etc\gitconfig
global–global自分のユーザーのすべてのリポジトリC:\Users\<ユーザー名>\.gitconfig
local–local(省略時)そのリポジトリだけリポジトリの .git\config

公式ドキュメントによると、Git はこれらを system → global → local の順に読み、同じ項目は後に読んだ値が優先されます(原文:last value found taking precedence)。つまり、範囲が狭いものほど強い、ということです。なお global には ~/.gitconfig のほかに ~/.config/git/config という置き場所もあり、両方あれば両方読まれます(~/.config/git/config が先)。ふだんは ~/.gitconfig だけを使えば十分です。

system、global、local の 3 つの設定ファイルを左から順に読む図。system は init.defaultBranch が master、global は init.defaultBranch が main と user.email が taro@example.com、local は user.email が taro@work.example.com。後に読んだ値が使われるので、結果は init.defaultBranch が main、user.email が taro@work.example.com になる。
図 1:system、global、local の順に読み、同じ項目は後の値で上書きされる

実際に、検証用の system ファイルに init.defaultBranch = master、global に init.defaultBranch = main を書いて git init すると、最初のブランチは main になりました。global の値が system に勝ったからです。

ちなみに、この PC の Git for Windows の system ファイルには、core.autocrlf=false・pull.rebase=false・init.defaultBranch=master などが入っていました。これはインストーラーで選んだ内容が書かれたもので、選び方によって違います。自分の PC の内容は、このあと説明する --show-origin で確認できます。

設定する・値を見る基本の書き方

「git config 範囲 項目名 値」で設定し、値を書かなければ今の値を表示します。項目名は「セクション.名前」の形(例:user.email)です。

git config --global user.email "taro@example.com"

リポジトリの中で --global を付けずに実行すると、そのリポジトリの .git/config(local)に書かれます。

git config user.email "taro@work.example.com"

このあと .git/config を開くと、最後に次の 2 行が増えていました。設定ファイルは「[セクション]」の下に「名前 = 値」を並べた、シンプルなテキストです。

[user]
	email = taro@work.example.com

値を見るときは、値を付けずに実行します。表示されるのは、3 つの範囲を合わせた結果、実際に使われる値です。

git config user.email

このリポジトリの中では taro@work.example.com、リポジトリの外では global の taro@example.com が表示されました。項目名の大文字・小文字は区別されず、git config USER.Name でも同じ値が出ます。

「どこの設定か」を調べる(–show-origin・–show-scope)

「設定したのに効かない」ときは、まず全部の設定を、書かれている場所つきで表示します。--show-scope は範囲の名前を、--show-origin はファイルの場所を、行の先頭に付けます。

git config --list --show-scope
system	core.autocrlf=true
system	init.defaultbranch=master
system	pull.rebase=false
global	user.name=Taro Yamada
global	user.email=taro@example.com
global	init.defaultbranch=main
local	core.repositoryformatversion=0
local	core.filemode=false
local	core.bare=false
local	core.logallrefupdates=true
local	core.symlinks=false
local	core.ignorecase=true
local	user.email=taro@work.example.com

(system の 3 行は、検証用に用意したファイルの内容です。)上から読まれた順に並び、user.email が global と local の 2 か所にあることが分かります。後に出てくる local の値が使われます。項目名は小文字にそろえて表示されます(init.defaultBranch → init.defaultbranch)。

1 つの項目について、全部の場所の値を見るには --get-all を付けます。--show-origin も付けるとファイルの場所が分かります。

git config --get-all --show-origin user.email
file:C:/…/home/.gitconfig	taro@example.com
file:.git/config	taro@work.example.com

(検証用フォルダーのパスは「…」で省略しています。ふだんの PC では file:C:/Users/<ユーザー名>/.gitconfig のように表示されます。)

もう 1 つ、コマンドを実行するときだけ一時的に設定を変える git -c 項目名=値 ... という書き方もあります。この値はどのファイルよりも優先され、--show-scope では command、--show-origin では command line: と表示されました。

値の取り出しと終了コード(–get)

git config user.email は git config --get user.email と同じ意味です。設定されていない項目では何も表示されず、終了コード(コマンドの成否を表す番号)が 1 になります。公式ドキュメントにも「キーがなければエラーコード 1 を返す」とあります。試した結果は次のとおりです(終了コードは直後に echo $? で確認)。

実行したコマンド表示終了コード
git config user.email(設定あり)taro@work.example.com0
git config user.phone(設定なし)何も出ない1
git config username(「.」がない)error: key does not contain a section: username1
git config –unset user.email(もう消してある)何も出ない5
git config –local user.email a@b(リポジトリの外)fatal: –local can only be used inside a git repository128

シェルスクリプトで「設定されているか」を確かめたいときは、この終了コードを使えます。次の 1 行は、メールアドレスがどこにも設定されていなければ「user.email が設定されていません」と表示し、設定されていれば何も表示しません。

git config user.email > /dev/null || echo "user.email が設定されていません"

終了コードと || の考え方は「シェルスクリプト入門」で説明しています。

設定を消す(–unset)

設定を消すには --unset を使います。範囲を付けないと local が対象です。

git config --unset user.email

local の user.email を消したあとに git config --show-origin user.email を実行すると、global の taro@example.com が表示されました。local を消すと、下にある global の値が見えるようになる、というわけです。global の設定を消すときは git config --global --unset 項目名 と書きます。

同じファイルに同じ項目が 2 回書かれていると(--add で追加したときなど)、--unset は「warning: user.email has multiple values」と表示して何もせず、終了コード 5 で終わりました。値を 1 つにしようとして上書きしたときも「error: cannot overwrite multiple values with a single value」で止まります。この場合は --unset-all ですべて消してから設定し直します。

Git 2.46 からの新しい書き方(git config get / set / unset)

Git 2.46 のリリースノートで、--get などのオプションによる書き方は非推奨になり、サブコマンドで書く形に置き換えられました。Git 2.49 では、どちらの書き方も同じように動きました。

これまでの書き方新しい書き方
git config –get user.emailgit config get user.email
git config user.email “…”git config set user.email “…”
git config –unset user.emailgit config unset user.email
git config –listgit config list
git config –global –editgit config edit –global

新しい書き方は古い Git では使えません。ネット上の記事や社内の手順書はほとんどがこれまでの書き方なので、この記事もこれまでの書き方で説明しています。

よく使う設定

項目何を決めるか設定の例
core.quotepath日本語のファイル名をそのまま表示するかfalse
alias.〇〇コマンドの短縮名alias.st “status –short”
core.editorコミットメッセージを書くエディター“code –wait”
init.defaultBranchgit init で作られる最初のブランチ名main
pull.rebasegit pull をマージで取り込むか rebase で取り込むかfalse / true
color.ui出力に色を付けるかauto(既定)
core.autocrlf改行コード(CRLF / LF)の自動変換false / true / input

このうち core.autocrlf は、リポジトリの .gitattributes と合わせて考える必要があります。値ごとの動きは「改行コードCRLFとLFの違いと確認・変換方法」、リポジトリで改行をそろえる方法は「.gitattributesの使い方」で説明しています。pull.rebase は「Gitのリモートの基本」と「git rebaseの使い方」で、init.defaultBranch は「Git入門」で扱っています。ここでは残りを説明します。

core.quotepath:日本語のファイル名を読めるようにする

「メモ.txt」というファイルを作って git status --short を実行すると、次のように表示されました。

?? "\343\203\241\343\203\242.txt"

文字化けではありません。公式ドキュメントによると、Git はパスに含まれる 0x80 より大きいバイトを「特別な文字」として扱い、8 進数で表示します(core.quotePath の既定値は true)。「メ」は UTF-8 で E3 83 A1 の 3 バイトなので、8 進数で \343\203\241 です。次のように設定すると、そのまま表示されるようになります。

git config --global core.quotepath false
?? メモ.txt

なお、ダブルクォートや「\」、制御文字は、この設定にかかわらず常にエスケープされます。バイトと文字の関係は「UTF-8とは?」で解説しています。

alias:よく使うコマンドに短い名前を付ける

alias.名前 に Git のコマンドの続きを書くと、git 名前 で呼び出せます。

git config --global alias.st "status --short"
git config --global alias.lg "log --oneline --graph --all"

これで git st が git status --short と同じ結果(?? メモ.txt)になり、git lg では * 6aabb97 メモを追加 のように 1 行ずつの履歴が表示されました。登録した alias の一覧は git config --get-regexp "^alias\." で見られます。

注意点が 2 つあります。1 つ目は、もとからある Git のコマンドと同じ名前の alias は無視されることです。試しに alias.status に log を登録しても、git status はふつうの status のままでした(公式ドキュメントにも、既存のコマンドを隠す alias は無視されるとあります)。2 つ目は、値の先頭を「!」にするとシェルのコマンドとして実行される点です。この場合はリポジトリの一番上のフォルダーで実行されるので、!pwd を登録してサブフォルダーで実行すると、一番上のフォルダーが表示されました。他人の設定ファイルをそのままコピーすると、知らないコマンドが動くこともあるので、中身を読んでから使いましょう。

どのコマンドを alias にするか迷ったら、「Git コマンド検索」で、やりたいことからコマンドを探してみてください。

core.editor と color.ui

core.editor は、git commit(-m なし)などで開くエディターです。VS Code にするなら次のように設定します(--wait は、ファイルを閉じるまで Git を待たせるためのオプション)。

git config --global core.editor "code --wait"

公式ドキュメントによると、環境変数 GIT_EDITOR が設定されているときは、そちらが core.editor より優先されます。設定したのにエディターが変わらないときは、この環境変数も確認してください。

color.ui は、出力に色を付けるかどうかの設定です。既定値は auto(画面に出すときだけ色を付ける。Git 1.8.4 から)なので、ふだんは設定不要です。色をなくしたいときは false にします。

includeIf で仕事用と個人用のメールアドレスを切り替える

会社のリポジトリでは会社のメール、個人のリポジトリでは個人のメールを使いたいとき、リポジトリごとに local の設定をするのは手間で、忘れがちです。includeIf を使うと、「このフォルダーの下にあるリポジトリでは、別の設定ファイルも読む」と書けます。

まず、仕事用の設定だけを書いたファイル ~/.gitconfig-work(~ はホームフォルダー)を作ります。

[user]
	email = taro@work.example.com

次に、global の設定に「~/work/ の下のリポジトリなら、このファイルを読む」と登録します。

git config --global includeIf.gitdir:~/work/.path "~/.gitconfig-work"

~/.gitconfig の最後には、次のように書き足されました。

[includeIf "gitdir:~/work/"]
	path = ~/.gitconfig-work

検証用のホームに work/app と private/blog の 2 つのリポジトリを作り、それぞれで git config --show-origin user.email を実行した結果です。

(~/work/app の中)
file:C:/…/home/.gitconfig-work	taro@work.example.com
(~/private/blog の中)
file:C:/…/home/.gitconfig	taro@example.com
~/.gitconfig に個人用の email と、gitdir が ~/work/ の下なら ~/.gitconfig-work を読む includeIf が書かれている。~/work/app のリポジトリは条件に合うので taro@work.example.com、~/private/blog のリポジトリは条件に合わないので taro@example.com が使われる。
図 2:includeIf の条件に合うリポジトリだけ、仕事用のファイルも読む

gitdir の条件は、リポジトリの .git フォルダーの場所と比べられます。公式ドキュメントにある決まりと、この PC で試して分かった注意点をまとめます。

  • 最後の「/」を忘れない:「/」で終わると、その下のすべてが対象になります(work/ は work/** と同じ)。gitdir:~/work と書いたら、~/work/app では一致せず、個人用のメールのままでした
  • Windows でも区切りは「/」:gitdir:C:/Users/…/work/ は一致しましたが、「\」区切りで書いたもの、Git Bash 流の /c/Users/… の形は一致しませんでした
  • 大文字・小文字は区別される:c:/users/… と小文字で書いたら一致しませんでした。区別しないときは gitdir/i: を使います(試したら一致しました)
  • includeIf は [user] より後ろに書く:ファイルは上から読まれ、後の値が勝ちます。includeIf を先頭に書いて [user] を後ろにしたら、仕事用のフォルダーでも個人用のメールになりました

また、gitdir はリポジトリの中でだけ判定されるので、~/work フォルダーそのもの(リポジトリでない場所)では個人用のメールが表示されました。切り替わったかどうかは、コミットする前に git config --show-origin user.email で確かめるのが確実です。

設定ファイルを直接開いて編集する

設定が増えてきたら、ファイルをエディターで開いて直接編集することもできます。次のコマンドは、global の設定ファイルを core.editor で設定したエディターで開きます(--global を外すと local のファイル)。

git config --global --edit

エディターで直すときは、[セクション] と 名前 = 値 の形を崩さないようにします。試しに ~/.gitconfig の最後に閉じ括弧のない [user を書き足すと、git status も git config --global --edit も「fatal: bad config line 13 in file …/.gitconfig」で止まりました。こうなったら、メモ帳などで表示された行番号の行を直します。不安なら、編集前にファイルをコピーしておきましょう。

local の設定は clone で共有されない

.git/config はリポジトリの中にありますが、コミットされるファイルではありません。local に user.email と core.hooksPath を設定したリポジトリを git clone して、クローン先で git config --list --local を実行すると、次のようになりました。

core.repositoryformatversion=0
core.filemode=false
core.bare=false
core.logallrefupdates=true
core.symlinks=false
core.ignorecase=true
remote.origin.url=C:/…/work/demo
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
branch.main.remote=origin
branch.main.merge=refs/heads/main

clone が自動で書いた remote・branch の設定だけで、元の user.email と core.hooksPath はありません。チームで設定をそろえたいときは、コミットできるファイル(改行コードなら .gitattributes、フックなら .githooks フォルダー)に書き、必要な git config を README に書いておく方法がとられます。フックの例は「Gitフック入門」で紹介しています。

よくある間違い・トラブル

項目名を打ち間違えても、エラーにならない

git config --global user.mail "x@example.com"(email の打ち間違い)は、エラーにならず終了コード 0 で保存されました。Git は知らない項目名でも受け付けるためです。設定が効かないときは git config --get-regexp "^user\." などで、つづりを確認してください。間違えた項目は --unset で消します。

値を打ち間違えて、Git のコマンドが動かなくなった

反対に、値は使うときに確かめられます。git config --global core.quotepath fals は保存できてしまいますが、そのあと git status が「fatal: bad boolean config value ‘fals’ for ‘core.quotepath’」で止まりました(終了コード 128)。正しい値で設定し直せば直ります。

「fatal: unable to read config file」と表示される

global の設定ファイル(~/.gitconfig)がまだない状態で git config --global --list を実行すると、「fatal: unable to read config file ‘…/.gitconfig’: No such file or directory」と表示されました。まだ一度も --global で設定していないだけなので、何か設定すればファイルが作られます。

–global で設定したのに、そのリポジトリでは効かない

そのリポジトリの local に同じ項目があると、local が優先されます。git config --get-all --show-origin 項目名 で、file:.git/config の行がないか確認してください。不要なら git config --unset 項目名 で local の方を消します。

よくある質問

–global と –system はどう使い分けますか?

自分の設定は --global を使います。system のファイルはパソコンの全員に効き、Git for Windows では C:\Program Files の下にあります。この PC で権限を確認すると、一般のユーザー(Users)には読み取りの権限しかなく、書き換えるには管理者の権限が必要でした。インストーラーが書いた設定を変えたいときも、system を書き換えずに global で上書きすれば済みます。

PowerShell でも同じコマンドで設定できますか?

できます。設定はファイルに保存されるので、Git Bash・PowerShell・VS Code のどこから Git を使っても同じ設定が使われます。ただし、値に「!」や「$」を含む alias は、シェルによって引用符の書き方が変わるので、git config --global --edit でファイルに直接書くと確実です。

まとめ

  • 設定は system → global → local の順に読まれ、後のもの(範囲が狭いもの)が優先される
  • 効かないときは git config --list --show-origin や --get-all --show-origin 項目名 で場所を調べる
  • 仕事用と個人用のメールは includeIf の gitdir:~/work/(最後に「/」)で自動で切り替えられる

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました