Gitでブランチの上流(upstream)を設定する方法

​​Git​コマンドライン

ブランチの上流(upstream)は、そのブランチが追いかけるリモートのブランチです。上流を設定すると、git push や git pull を引数なしで実行できるようになり、git status にリモートとの差が出ます。新しいブランチで git push が「has no upstream branch」と言って止まったとき、git pull が「There is no tracking information」と言ったときに設定するものです。設定する方法と外す方法を、前と後の出力で確かめました。

補足

検証環境は Ubuntu 24.04、Git 2.43.0 です。作者の名前とメールアドレスには例示用の値(Neko <neko@example.com>)を設定しました。リモートには、同じ環境に作ったベアリポジトリ(../remote.git)を使いました。GitHub などのホスティングサービスへのプッシュ、Windows と macOS での動作は試していません。

上流がないブランチで起きること

git init で作ったリポジトリにコミットを1つ作り、git remote add origin ../remote.git でリモートを登録しました。この時点の main には上流がありません。git status にはリモートとの関係が出ず、git branch -vv にも角かっこの部分がありません。

console
$ git status
On branch main
nothing to commit, working tree clean

$ git branch -vv
* main 6b9961f 最初のコミット

引数なしの git push は、上流がないと言って止まります。メッセージの中に、上流を設定しながらプッシュするコマンドが書かれています。

console
$ git push
fatal: The current branch main has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin main

To have this happen automatically for branches without a tracking
upstream, see 'push.autoSetupRemote' in 'git help config'.

引数なしの git pull も、どこから取り込むか決まっていないため止まります。

console
$ git pull
There is no tracking information for the current branch.
Please specify which branch you want to merge with.
See git-pull(1) for details.

    git pull <remote> <branch>

If you wish to set tracking information for this branch you can do so with:

    git branch --set-upstream-to=origin/<branch> main

git push -u で、プッシュと同時に上流を設定する

初めてプッシュするブランチなら、git push -u origin main がいちばん手軽です。-u は --set-upstream の短い書き方で、プッシュに成功したブランチに上流を設定します(git push の公式リファレンス)。出力の最後の行で、origin/main を追いかけるようになったことが分かります。

console
$ git push -u origin main
To ../remote.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

設定したあとは、git branch -vv の角かっこに上流の名前が出て、git status にリモートとの関係が出るようになりました。

console
$ git branch -vv
* main 6b9961f [origin/main] 最初のコミット

$ git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

上流は、リポジトリの設定ファイルに branch.<ブランチ名>.remote と branch.<ブランチ名>.merge の2つの値として書かれます。リモートの名前と、リモート側のブランチの名前です(git config の公式リファレンス)。

console
$ git config --get-regexp '^branch\.'
branch.main.remote origin
branch.main.merge refs/heads/main

プッシュ済みのブランチに、git branch -u で上流だけを設定する

-u を付けずにプッシュすると、リモートにブランチはできますが、上流は設定されません。feature/login を作って git push origin feature/login でプッシュしたところ、git branch -vv の feature/login には角かっこが出ず、git pull は先ほどと同じメッセージで止まりました。

console
$ git push origin feature/login
To ../remote.git
 * [new branch]      feature/login -> feature/login

$ git branch -vv
* feature/login 8729925 ログイン画面を追加
  main          6b9961f [origin/main] 最初のコミット

$ git pull
There is no tracking information for the current branch.
Please specify which branch you want to merge with.
See git-pull(1) for details.

    git pull <remote> <branch>

If you wish to set tracking information for this branch you can do so with:

    git branch --set-upstream-to=origin/<branch> feature/login

すでにプッシュしてあるなら、もう一度プッシュしなくても、git branch -u で上流だけを設定できます。-u は --set-upstream-to の短い書き方で、ブランチ名を省くといまいるブランチが対象になります(git branch の公式リファレンス)。

console
$ git branch -u origin/feature/login
branch 'feature/login' set up to track 'origin/feature/login'.

$ git branch -vv
* feature/login 8729925 [origin/feature/login] ログイン画面を追加
  main          6b9961f [origin/main] 最初のコミット

$ git config --get-regexp '^branch\.'
branch.main.remote origin
branch.main.merge refs/heads/main
branch.feature/login.remote origin
branch.feature/login.merge refs/heads/feature/login

リモートのブランチを上流にするときは、手元にある追跡用のブランチ(origin/...)を指定します。手元に追跡用のブランチがない名前を指定すると、存在しないと言って止まります。ヒントには、リモートにあるなら git fetch で取ってくること、新しいブランチなら git push -u を使うことが書かれています。

console
$ git branch -u origin/feature/signup
fatal: the requested upstream branch 'origin/feature/signup' does not exist
hint: 
hint: If you are planning on basing your work on an upstream
hint: branch that already exists at the remote, you may need to
hint: run "git fetch" to retrieve it.
hint: 
hint: If you are planning to push out a new local branch that
hint: will track its remote counterpart, you may want to use
hint: "git push -u" to set the upstream config as you push.
hint: Disable this message with "git config advice.setUpstreamFailure false"

上流があると、進みと遅れが表示される

上流を設定したブランチでは、上流と比べて何コミット進んでいるか、遅れているかが出ます。feature/login でコミットを1つ足すと、git status は1コミット進んでいると言い、git branch -vv には ahead 1 が付きました。

console
$ git status
On branch feature/login
Your branch is ahead of 'origin/feature/login' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

$ git branch -vv
* feature/login 7bcf752 [origin/feature/login: ahead 1] パスワード欄を追加
  main          6b9961f [origin/main] 最初のコミット

上流は、コマンドの中で @{u}(@{upstream} の短い書き方)と書いて指せます(リビジョンの書き方を説明した公式リファレンス)。git log --oneline @{u}.. で、まだプッシュしていないコミットだけを一覧にできます。

console
$ git rev-parse --abbrev-ref @{u}
origin/feature/login

$ git log --oneline @{u}..
7bcf752 パスワード欄を追加

上流があるので、引数なしの git push でそのままプッシュでき、ahead 1 は消えました。

console
$ git push
To ../remote.git
   8729925..7bcf752  feature/login -> feature/login

$ git branch -vv
* feature/login 7bcf752 [origin/feature/login] パスワード欄を追加
  main          6b9961f [origin/main] 最初のコミット

遅れのほうも試しました。別のクローンから feature/login に1コミットをプッシュしたあと、もとのリポジトリで git status を見ても、まだ「up to date」のままです。git status が比べる相手は手元にある origin/feature/login なので、git fetch で取ってきてから比べます。取ってきたあとは、1コミット遅れていると出ました。

console
$ git status
On branch feature/login
Your branch is up to date with 'origin/feature/login'.

nothing to commit, working tree clean

$ git fetch -q

$ git status
On branch feature/login
Your branch is behind 'origin/feature/login' by 1 commit, and can be fast-forwarded.
  (use "git pull" to update your local branch)

nothing to commit, working tree clean

$ git branch -vv
* feature/login 7bcf752 [origin/feature/login: behind 1] パスワード欄を追加
  main          6b9961f [origin/main] 最初のコミット

リモートのブランチから作ったブランチには、上流が自動で付く

リモートにあるブランチを手元に持ってくるときは、自分で上流を設定しなくても付きます。別の場所に git clone したリポジトリで、手元にまだない feature/login に git switch すると、origin/feature/login を上流にしたブランチが作られました。

console
$ git branch -vv
* main 6b9961f [origin/main] 最初のコミット

$ git switch feature/login
Switched to a new branch 'feature/login'
branch 'feature/login' set up to track 'origin/feature/login'.

git switch の公式リファレンスによると、指定したブランチが手元になく、同じ名前の追跡用のブランチが1つのリモートにだけあるときは、git switch -c <ブランチ名> --track <リモート>/<ブランチ名> と同じように扱われます。

名前を変えて git switch -c login-copy origin/feature/login のように作った場合も、上流が付きました。設定の branch.autoSetupMerge が初期値の true のとき、Git は追跡用のブランチを起点に作ったブランチに上流を設定するためです(git branch の公式リファレンス)。手元のブランチから作った local-only には、上流は付きませんでした。

console
$ git switch -c login-copy origin/feature/login
Switched to a new branch 'login-copy'
branch 'login-copy' set up to track 'origin/feature/login'.

$ git switch -c local-only
Switched to a new branch 'local-only'

$ git branch -vv
  feature/login 7bcf752 [origin/feature/login] パスワード欄を追加
* local-only    7bcf752 パスワード欄を追加
  login-copy    7bcf752 [origin/feature/login] パスワード欄を追加
  main          6b9961f [origin/main] 最初のコミット

push.autoSetupRemote で、毎回の -u を省く

新しいブランチを作るたびに -u origin ブランチ名 を打つのが手間なら、push.autoSetupRemote を true にします。上流がないブランチで引数なしの git push をしたときに、--set-upstream を付けたものとして扱う設定です。push.default が simple、upstream、current のときに効きます(git config の公式リファレンス)。この検証では push.default を設定せず、Git 2.0 からの初期値の simple のまま試しました。

新しく作った feature/cart で、設定の前と後に git push を実行しました。設定の前は上流がないと言って止まり、設定の後はリモートにブランチを作って上流も設定しました。

console
$ git push
fatal: The current branch feature/cart has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin feature/cart

To have this happen automatically for branches without a tracking
upstream, see 'push.autoSetupRemote' in 'git help config'.

$ git config --global push.autoSetupRemote true

$ git push
To ../remote.git
 * [new branch]      feature/cart -> feature/cart
branch 'feature/cart' set up to track 'origin/feature/cart'.

--global を付けると、設定はリポジトリの .git/config ではなく、ホームフォルダーの ~/.gitconfig に書かれます。オプションを付けなければ、そのリポジトリの .git/config に書かれます(git config の公式リファレンス)。

git branch –unset-upstream で上流を外す

上流の設定は git branch --unset-upstream で外せます。ブランチ名を省くと、いまいるブランチが対象です(git branch の公式リファレンス)。feature/cart で実行すると、git branch -vv の角かっこが消え、設定ファイルからも branch.feature/cart の値がなくなりました。git status にもリモートとの関係が出なくなりました。feature/login の behind 1 は、前の節で取ってきた変更をまだ取り込んでいないためです。

console
$ git branch --unset-upstream

$ git branch -vv
* feature/cart  7915430 カートを追加
  feature/login 7bcf752 [origin/feature/login: behind 1] パスワード欄を追加
  main          6b9961f [origin/main] 最初のコミット

$ git config --get-regexp '^branch\.feature/cart'

$ git status
On branch feature/cart
nothing to commit, working tree clean

外したのは手元の設定だけです。git branch -r で見ると、追跡用のブランチの origin/feature/cart は残っていて、git branch -u でもう一度上流にできました。

console
$ git branch -r
  origin/feature/cart
  origin/feature/login
  origin/main

$ git branch -u origin/feature/cart
branch 'feature/cart' set up to track 'origin/feature/cart'.
ポイント

初めてプッシュするブランチは git push -u origin ブランチ名、すでにプッシュしてあるブランチは git branch -u origin/ブランチ名 で上流を設定します。設定できたかどうかは、git branch -vv の角かっこで確かめられます。

​Posted by 86