git

Why Do We Set Upstream Branch and What is it?

How to use git command 5/N

公開日: 2021-01-05
更新日: 2023-06-13

  Table of Contents

What are upstream branches?

Def: Upstream branch

  • Upstream branchとは, local branchが履歴を追跡するように設定したremote branchのこと
  • git fetch/git pullを引数なしで実行した際に, どのremote branchに対してpull/fetchを実行すべきかを認識させる効果がある
  • remote tracking branch(ローカル上でorigin/hogeのように表示されるbranch)とは別概念

Tracking branchesとは, remote branch と直接的な関係を持つlocal branchのこと. 例として, 新たにrepositoryをGitHub上で作成し, それをローカルへcloneした際, ローカル上にmain branchが作成されますが, そのmain branchはremote tracking branchとしてのorigin/masterをトラックしています.

Why Do We set upstream branches?

引数の省略

一度, local repositoryに対してupstream branchが設定されると, git push, git pull, git fetch のときにrepositoryとbranchの 引数を省略することが出来ます.

1
2
3
4
5
6
7
8

# Push the current branch to the branch upstream
% git push 

# Pull the branch upstream to the current branch
% git pull

# Fetch the branch upstream to the current branch
% git fetch

非同期commitの確認: git status

  • upstream branchが設定されていると, 現在のlocal branchがremote branchに対してどのくらいの非同期commitがあるかgit statusが表示してくれる
  • behindならばremoteの方が進んでいる
  • aheadならばlocalの方が進んでおり, pushしたほうが良い
1
2
3
4
5
6

% git status
On branch hoge
Your branch is behind 'origin/hoge' by 2 commits, and can be fast-forwarded.
  (use "git pull" to update your local branch)

nothing to commit, working tree clean

unpushed local commitの詳細確認: git log

  • upstreamへpushされていないlocal commitのhash値の確認が可能
  • --stat optionを付与することで, 変更ファイルもterminal上から確認することができる
  • .gitconfigにaliasとして登録することが推奨

syntax

1

% git log <tracking-remote>..<local branch>

upstreamとの差分を確認したい場合

以下のことも同時に知りたいので, --stat, --abbrev-comit optionを付与していつも実行しています

  • commit毎の差分ファイルを確認したい
  • 実行日を知りたい
  • commit hash idはshort versionにしたい
1

% git log --stat --abbrev-comit @{upstream}..HEAD

Check the Upstream Branch

What I Want

  • local repositoryとupstream branchの対応関係を知りたい

How

1
2
3
4
5
6
7
8

% git branch -vv
branch_A            214c991 [origin/branch_A: ahead 1, behind 3] FIX readme
  branch_B            a387619 [origin/non_existing_branch] add yml
  hoge                f5663c5 [origin/hoge] hoge test
* hoge2               4a1e30f Update hoge2.txt
  hoge3               376ef7c [origin/hoeg3: gone] add hoge
  main                16a340c [origin/main] a
  non_existing_branch a387619 [origin/non_existing_branch] add yml
  • 対応していないブランチ(上ではhoge2)では [origin/<remote branch name>]が出力されない

Set up/unset an upstream branch to a local branch

新しくremote branchを作成し, そのブランチをupstream branchとしたい場合

HEADをgit pushすることは, 現在のブランチと同じ名前を持つリモートブランチにプッシュすることなので, そのコマンドに-u または --set-upstream を実行するだけでOk

1

% git push -u origin HEAD

すでにremote branchが存在している場合

What I Want

  • upstream branchが設定されていないlocal branchに対して, upstream branchを指定したい

How

1
2

% git branch -u <remote branch>
% git branch <local branch> -u <remote branch>
  • <local branch>を省略した場合は, 現在のbranchに対してupstream branchを設定する

unset an upstream branch

リモートブランチの追跡を解除したい場合は以下のコマンドを実行すると, 現在のbranchに対してupstream branchが解除される:

1

% git branch --unset-upstream

Tips

Set up a shortcut command by ussing a git alias

What I Want

  • 毎回, git push -u origin HEADと入力するのが面倒なので git up-pushというコマンドで代替させたい.
  • git log --stat --abbrev-commit @{upstream}..HEADをgit ls-unpushというコマンドで代替させたい

How

~/.gitconfigに対して以下のように指定

1
2
3

[alias]
	up-push = "push -u origin HEAD"
	ls-unpush = "log --stat --abbrev-commit @{upstream}..HEAD"

Refernces

General

Share Buttons
 Share on:
Feature Tags
Leave a Comment
(注意：GitHub Accountが必要となります）
CONTENTS