git ls-remote

git ls-remote は、ローカルに git fetch を実行しなくてもリモートリポジトリのブランチ・タグ・コミット SHA 一覧を取得できるコマンドです。ネットワーク接続だけで情報を確認できるため、CI/CD スクリプトやフェッチ前の事前確認に役立ちます。

基本的な使い方

# リモート origin の全 ref を表示
git ls-remote origin

出力例：

a1b2c3d4e5f6789012345678901234567890abcd	HEAD
a1b2c3d4e5f6789012345678901234567890abcd	refs/heads/main
f4e5d6c7b8a9012345678901234567890abcdef1	refs/heads/feature/login
9g8h7i0j1k2l345678901234567890abcdef0123	refs/tags/v1.0.0

各行は <SHA>\t<ref名> の形式で表示されます。

ブランチ一覧を確認する

# リモートのブランチ（refs/heads/）のみ表示
git ls-remote --heads origin

# 特定のブランチが存在するか確認
git ls-remote --heads origin main

出力例：

a1b2c3d4e5f6789012345678901234567890abcd	refs/heads/main
f4e5d6c7b8a9012345678901234567890abcdef1	refs/heads/feature/login

タグ一覧を確認する

# リモートのタグのみ表示
git ls-remote --tags origin

# 実際の ref だけ（シンボリック ref を除外）
git ls-remote --tags --refs origin

出力例（--refs あり）：

9g8h7i0j1k2l345678901234567890abcdef0123	refs/tags/v1.0.0
c3d4e5f6a7b8901234567890abcdef0123456789	refs/tags/v1.1.0

--refs なしの場合、注釈付きタグには refs/tags/v1.0.0^{} という行（タグが指すコミット SHA）も表示されます。

フェッチ前の事前確認

# clone・fetch の前に目的のブランチが存在するか確認
git ls-remote --heads https://github.com/user/repo.git feature/new-api

# 出力が空の場合 = ブランチが存在しない

git fetch や git clone の前に対象ブランチやタグの存在を確認することで、不要なネットワーク転送を避けられます。

スクリプトでの活用

# 特定のタグが存在するかチェック（CI/CD 活用例）
TAG="v2.0.0"
if git ls-remote --exit-code --tags origin "$TAG" > /dev/null 2>&1; then
  echo "タグ $TAG は存在します"
else
  echo "タグ $TAG は存在しません（終了コード: $?）"
fi

--exit-code を使うと、マッチする ref がない場合に終了コード 2 が返るため、シェルスクリプトの条件分岐に組み込めます。

git remote show との使い分け

コマンド	用途	情報量
git ls-remote	SHA 付き ref 一覧を軽量に取得	シンプル
git remote show <name>	トラッキングブランチや push/fetch URL の詳細	詳細

スクリプトで特定 ref の存在チェックや SHA 取得をする場合は git ls-remote が適しています。リモートとの同期状態を人間が読む形で確認したい場合は git remote show が便利です。