upstream(アップストリーム)とは

upstreamは直訳すると「上流」です。川の流れをイメージしてもらうと分かりやすくて、水が流れてくる「元」の方向が上流、流れていく先が下流(downstream)。開発の世界でも、自分がいる場所より「元」にあたる側を指すときにこの言葉を使います。

正直、最初にこの単語を見たとき「上流工程のことか?」と勘違いしたんですが、そういう意味ではありません。文脈によって指すものが少し変わるので、代表的な使い方を順に見ていきます。

使い方1: Gitでの「元のリポジトリ」

いちばんよく出てくるのがGitの文脈です。GitHubで他人のリポジトリをフォーク(自分のアカウントにコピー)して作業するとき、コピー元のリポジトリのことをupstreamと呼びます。

川の例えで言えば、元のリポジトリが上流の水源で、自分のコピーはそこから水を引いてきた下流の田んぼ、というイメージです。上流で新しい変更が入ったら、それを自分の側に引き込んでくる(取り込む)必要があります。逆に、自分の田んぼで作った改良を上流に還元することを「upstreamに送る」「アップストリームする」と言ったりします。

Gitでは、リモートリポジトリに好きな名前を付けられます。慣習として、自分のフォークをorigin、フォーク元をupstreamという名前で登録することが多いです。

git remote add upstream https://github.com/例/元リポジトリ.git
git fetch upstream

使い方2: ブランチの「追跡先」

もう一つ、Gitでupstreamという言葉が出る場面があります。ローカルのブランチが「どのリモートブランチと対応しているか」という設定です。これを上流ブランチ(upstream branch)と呼びます。

新しくブランチを作って初めてpushしようとしたとき、「上流ブランチが設定されていない」といったメッセージを見たことがある人は多いはずです。あれは「このローカルブランチを、リモートのどのブランチに対応させるか決まっていませんよ」という意味。-uオプションを付けてpushすると、その対応付けが記録されます。

git push -u origin feature-branch

一度設定してしまえば、以降はgit pushやgit pullとだけ打てば、Gitが「あ、このブランチの上流はあれだな」と判断してくれます。地味ですが、これがあるかないかで日々のタイプ量がかなり変わります。

使い方3: ソフトウェア本体としての「上流」

OSSの話題では、そのソフトウェアの本家開発元を指して「upstream」と言うこともあります。たとえばあるツールをカスタマイズして社内で使っているとして、そのカスタマイズを本家に取り込んでもらうことを「upstreamにマージしてもらう」と表現します。

この使い方も川の比喩そのままです。本家が水源で、それを利用している各プロジェクトが下流。上流でバグが直れば下流にも恩恵が及びますし、逆に下流で見つけた問題を上流に報告して直してもらう、という関係になります。

upstreamとdownstreamの対応

視点	upstream(上流)	downstream(下流)
フォーク	フォーク元のリポジトリ	フォークした自分のリポジトリ
ブランチ	対応するリモートブランチ	手元のローカルブランチ
OSS	本家の開発プロジェクト	それを利用・改変する側

混乱しないためのコツ

「upstreamって結局どれ?」と迷ったら、今いる場所から見て、変更が生まれてくる元はどこかを考えるとだいたい当たります。自分が水を引いている側なら、水が来ている方向が上流。

もう一つ注意したいのが、upstreamという名前は「決まりきったキーワード」ではなくただの慣習だという点です。Gitのリモート名としてのupstreamは自分で好きに付けられる名前なので、チームによっては別の名前を使っていることもあります。設定を確認したいときはgit remote -vで登録されているリモートの一覧が見られます。

逆に「上流ブランチ」の方はGitの機能として組み込まれた概念で、こちらは名前ではなく設定です。この2つは同じ「upstream」という単語を使っていますが別物なので、慣れるまでは「リモートの名前の話か、ブランチの対応付けの話か」を意識して読むと混乱しにくくなります。