docker-git-bash-guide

Windows の Git Bash／MINGW での Docker：パス変換ガイド

このスキルでは、Windows の Git Bash（MINGW）で Docker コマンドを扱う方法を包括的に説明します。特に、ボリュームマウントのパス変換に関する問題と解決策に焦点を当てています。

パス変換の問題

Windows の Git Bash（MINGW）または MSYS2 で Docker コマンドを実行すると、自動パス変換によってボリュームマウントやその他の Docker コマンドで深刻な問題が発生することがあります。

自動変換が発生する条件

MSYS／MINGW シェルは、Windows 実行ファイル（docker.exe など）を呼び出す際、Unix のパスのように見える引数を自動的に変換します。

変換に問題がある例：

# What you type:
docker run -v /c/Users/project:/app myimage

# What Docker receives (BROKEN):
docker run -v C:\Program Files\Git\c\Users\project:/app myimage

パス変換が発生する条件：

• 引数の先頭がスラッシュ（/）
• コロンで区切られたパスリスト（/foo:/bar）
• - または , の後にパス要素が続く引数

変換の対象外：

• = を含む引数（変数の割り当て）
• ドライブ文字（C:）
• ; を含む引数（すでに Windows 形式）
• // で始まる引数（ネットワークパス／Windows スイッチ）

Docker コマンドのシェル検出

Git Bash／MINGW 環境の検出

パス変換の問題が発生する可能性がある環境を検出するには、次の環境変数を使用します。

# Most reliable: Check for MSYSTEM
if [ -n "$MSYSTEM" ]; then
  echo "Running in Git Bash/MINGW - path conversion needed"
fi

# Alternative: Check uname
if [[ "$(uname -s)" == MINGW* ]]; then
  echo "Running in MINGW environment"
fi

# Environment variable to check:
# MSYSTEM values: MINGW64, MINGW32, MSYS

解決策 1：MSYS_NO_PATHCONV（Git Bash に推奨）

Windows の Git Bash では、最も信頼性の高い解決策です。

コマンドごとに使用する

各 Docker コマンドの前に MSYS_NO_PATHCONV=1 を付けます。

# Volume mount with $(pwd)
MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app myimage

# Volume mount with absolute path
MSYS_NO_PATHCONV=1 docker run -v /c/Users/project:/app myimage

# Multiple volume mounts
MSYS_NO_PATHCONV=1 docker run \
  -v $(pwd)/data:/data \
  -v $(pwd)/config:/etc/config \
  myimage

シェルレベルで設定する

セッション中のすべての Docker コマンドでパス変換を無効にします。

# Add to ~/.bashrc or run in current shell
export MSYS_NO_PATHCONV=1

# Now all Docker commands work normally
docker run -v $(pwd):/app myimage

関数ラッパー（Docker コマンドごとに自動適用）

パス変換を自動的に無効にする関数ラッパーを作成します。

# Add to ~/.bashrc
docker() {
  (export MSYS_NO_PATHCONV=1; command docker.exe "$@")
}

# Or using MSYS2_ARG_CONV_EXCL for MSYS2
docker() {
  (export MSYS2_ARG_CONV_EXCL='*'; command docker.exe "$@")
}

# Make function available in subshells
export -f docker

解決策 2：MSYS2_ARG_CONV_EXCL（MSYS2 専用）

MSYS2 環境（標準の Git Bash ではありません）では、次のようにします。

# Disable all argument conversion
export MSYS2_ARG_CONV_EXCL='*'

# Selective exclusion (specific patterns)
export MSYS2_ARG_CONV_EXCL='--dir=;/test'

# Environment variable conversion exclusion
export MSYS2_ENV_CONV_EXCL='*'

解決策 3：先頭にスラッシュを 2 つ付ける

変換を防ぐため、パスの先頭に / をもう 1 つ付けます。

# Single slash (converted - BROKEN)
docker run -v /c/Users/project:/app myimage

# Double slash (not converted - WORKS)
docker run -v //c/Users/project:/app myimage

# Works in Git Bash on Windows
# Treated as single slash on Linux (portable)

メリット：

• 環境変数が不要です
• ラッパー関数なしで動作します
• 移植性があります（Linux では余分なスラッシュは無視されます）

デメリット：

• 読みにくくなります
• 忘れやすい方法です
• 標準的な Docker の構文に見えません

解決策 4：適切にエスケープして $(pwd) を使用する

適切な構文で、小文字の $(pwd) を常に使用します（$PWD ではありません）。

# CORRECT: Round brackets, lowercase pwd, no quotes
MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app myimage

# CORRECT: With subdirectories
MSYS_NO_PATHCONV=1 docker run -v $(pwd)/src:/app/src myimage

# WRONG: Uppercase PWD variable (may not convert correctly)
docker run -v $PWD:/app myimage

# WRONG: Without MSYS_NO_PATHCONV (path gets mangled)
docker run -v $(pwd):/app myimage

Docker のボリュームマウントに関するベストプラクティス（Windows の Git Bash）

docker run コマンドの場合

# Named volumes (no path conversion issue)
docker run -v my-named-volume:/data myimage

# Bind mount with MSYS_NO_PATHCONV (RECOMMENDED)
MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app myimage

# Bind mount with double slash (ALTERNATIVE)
docker run -v //c/Users/project:/app myimage

# Read-only bind mount
MSYS_NO_PATHCONV=1 docker run -v $(pwd)/config:/etc/config:ro myimage

# Multiple volumes
MSYS_NO_PATHCONV=1 docker run \
  -v $(pwd)/src:/app/src \
  -v $(pwd)/data:/app/data \
  -v my-named-volume:/var/lib/data \
  myimage

docker-compose.yml ファイルの場合

Docker Compose ファイルではスラッシュと相対パスを使用します。これらは Git Bash で正しく動作します。

# WORKS WITHOUT MODIFICATION in Git Bash
services:
  app:
    image: myimage
    volumes:
      # Relative paths (RECOMMENDED)
      - ./src:/app/src
      - ./data:/app/data

      # Named volumes (RECOMMENDED)
      - my-data:/var/lib/data

      # Windows absolute paths with forward slashes (WORKS)
      - C:/Users/project:/app

      # Unix-style paths (WORKS if referring to WSL/MINGW paths)
      - /c/Users/project:/app

volumes:
  my-data:

重要： docker compose コマンドを実行する場合：

# No special handling needed for compose files
docker compose up -d

# But if you use command-line volume overrides:
MSYS_NO_PATHCONV=1 docker compose run -v $(pwd)/extra:/extra app

完全な例

例 1：シンプルなアプリケーション開発

# Set up environment once per session
export MSYS_NO_PATHCONV=1

# Run with live code reload
docker run -d \
  --name dev-app \
  -v $(pwd)/src:/app/src \
  -v $(pwd)/public:/app/public \
  -p 3000:3000 \
  node:20-alpine \
  npm run dev

# View logs
docker logs -f dev-app

例 2：データを永続化するデータベース

# Use named volume for database data (no path issues)
docker run -d \
  --name postgres-db \
  -e POSTGRES_PASSWORD=mypassword \
  -v pgdata:/var/lib/postgresql/data \
  -p 5432:5432 \
  postgres:16-alpine

# Mount init scripts with MSYS_NO_PATHCONV
MSYS_NO_PATHCONV=1 docker run -d \
  --name postgres-db \
  -e POSTGRES_PASSWORD=mypassword \
  -v pgdata:/var/lib/postgresql/data \
  -v $(pwd)/init.sql:/docker-entrypoint-initdb.d/init.sql:ro \
  -p 5432:5432 \
  postgres:16-alpine

例 3：Docker Compose を使ったフルスタック構成

# Project structure:
# /c/Users/project/
#   ├── docker-compose.yml
#   ├── backend/
#   ├── frontend/
#   └── data/

# docker-compose.yml (no special path handling needed)
cat > docker-compose.yml <<'EOF'
services:
  backend:
    build: ./backend
    volumes:
      - ./backend/src:/app/src
      - ./data:/app/data
    ports:
      - "4000:4000"

  frontend:
    build: ./frontend
    volumes:
      - ./frontend/src:/app/src
      - ./frontend/public:/app/public
    ports:
      - "3000:3000"
    depends_on:
      - backend

  database:
    image: postgres:16-alpine
    volumes:
      - db-data:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: changeme

volumes:
  db-data:
EOF

# Start everything (works normally)
docker compose up -d

# Override with additional volume (needs MSYS_NO_PATHCONV)
MSYS_NO_PATHCONV=1 docker compose run -v $(pwd)/scripts:/scripts backend bash

パスの問題のトラブルシューティング

問題：「No such file or directory」エラーが発生する

症状：

Error response from daemon: invalid mount config for type "bind":
bind source path does not exist: C:\Program Files\Git\c\Users\project

原因の特定：

• MINGW によってパスが誤って変換されています
• C:\Program Files\Git\ のプレフィックスが追加されていることを確認してください

解決策：

# Add MSYS_NO_PATHCONV before command
MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app myimage

問題：コンテナー内のボリュームが空に見える

症状：

• コンテナーは正常に起動します
• しかし、マウントされたディレクトリが空です
• ホストにはファイルがあります

原因の特定：

• パス変換によってソースパスが崩れています
• 代わりに Docker が空のディレクトリを作成しました

解決策：

# Use MSYS_NO_PATHCONV with $(pwd)
MSYS_NO_PATHCONV=1 docker run -v $(pwd)/data:/data myimage

# Or use double slash
docker run -v //c/Users/project/data:/data myimage

# Or use named volumes for persistent data
docker run -v my-named-volume:/data myimage

問題：スペースを含むパスが失敗する

症状：

Error: invalid reference format

原因の特定：

• Windows のパスに含まれるスペースが適切に引用符で囲まれていません
• パス変換とスペースが組み合わさると、問題が発生します

解決策：

# Use MSYS_NO_PATHCONV and quote $(pwd)
MSYS_NO_PATHCONV=1 docker run -v "$(pwd)":/app myimage

# Or avoid spaces in project paths entirely (RECOMMENDED)
# Move project from:
#   C:/Users/My Name/My Projects/app
# To:
#   C:/Users/MyName/projects/app

問題：$PWD が正しく動作しない

症状：

• $(pwd) ではなく $PWD 変数を使用しています
• 動作に一貫性がありません

解決策：

# WRONG: Using $PWD
docker run -v $PWD:/app myimage

# CORRECT: Using $(pwd)
MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app myimage

# Explanation:
# $(pwd) is a command that returns current directory
# $PWD is an environment variable that may not be properly formatted

設定のテスト

Docker のボリュームマウントが正しく動作するか確認するため、テストスクリプトを作成します。

#!/bin/bash
# test-docker-volume.sh

echo "Testing Docker volume mounts in Git Bash..."

# Create test file
mkdir -p test-mount
echo "Hello from host" > test-mount/test.txt

# Test 1: With MSYS_NO_PATHCONV
echo "Test 1: With MSYS_NO_PATHCONV"
MSYS_NO_PATHCONV=1 docker run --rm -v $(pwd)/test-mount:/data alpine cat /data/test.txt

# Test 2: With double slash
echo "Test 2: With double slash"
docker run --rm -v //$(pwd)/test-mount:/data alpine cat /data/test.txt

# Test 3: Without workaround (should fail)
echo "Test 3: Without workaround (may fail)"
docker run --rm -v $(pwd)/test-mount:/data alpine cat /data/test.txt

# Cleanup
rm -rf test-mount

echo "Testing complete!"

実行します。

chmod +x test-docker-volume.sh
./test-docker-volume.sh

推奨設定

~/.bashrc に追加します。

# Docker path conversion fix for Git Bash on Windows
export MSYS_NO_PATHCONV=1

# Or use a wrapper function if you prefer per-command control
docker() {
  (export MSYS_NO_PATHCONV=1; command docker.exe "$@")
}
export -f docker

# Alias for docker compose (if needed)
alias docker-compose='MSYS_NO_PATHCONV=1 docker compose'

プラットフォーム検出スクリプト

次のスクリプトを使用して、Git Bash 用の Docker を自動的に検出し、設定します。

# Add to ~/.bashrc
# Detect if running in Git Bash/MINGW on Windows
if [ -n "$MSYSTEM" ] || [[ "$(uname -s)" == MINGW* ]]; then
  # Running in Git Bash/MINGW
  echo "Git Bash detected - enabling Docker path conversion fix"
  export MSYS_NO_PATHCONV=1

  # Optional: Create wrapper function for explicit control
  docker() {
    (export MSYS_NO_PATHCONV=1; command docker.exe "$@")
  }
  export -f docker
fi

クイックリファレンス

環境変数

変数	目的	値
MSYS_NO_PATHCONV	パス変換をすべて無効にします（Git Bash）	無効にするには 1
MSYS2_ARG_CONV_EXCL	特定の引数を除外します（MSYS2）	'*' またはパターン
MSYS2_ENV_CONV_EXCL	環境変数を除外します（MSYS2）	'*' またはパターン
MSYSTEM	MSYS サブシステムの識別子	MINGW64、MINGW32、MSYS

コマンドのパターン

# RECOMMENDED: Export once per session
export MSYS_NO_PATHCONV=1
docker run -v $(pwd):/app myimage

# Per-command prefix
MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app myimage

# Double slash workaround
docker run -v //c/Users/project:/app myimage

# Named volumes (no path issues)
docker run -v my-data:/data myimage

# Docker Compose (relative paths work)
docker compose up -d

変更せずに動作するもの

以下の Docker コマンドは、特別な対応をしなくても Git Bash で通常どおり動作します。

• 名前付きボリューム：-v my-volume:/data
• ネットワークコマンド：docker network create
• イメージコマンド：docker build、docker pull
• ボリュームを指定しないコンテナーコマンド：docker run myimage
• YAML 内で相対パスを使用する Docker Compose

MSYS_NO_PATHCONV が必要なもの

以下のコマンドでは、パス変換の修正が必要です。

• 絶対パスを使ったバインドマウント：-v /c/Users/project:/app
• $(pwd) を使ったバインドマウント：-v $(pwd):/app
• docker run のコマンドラインでのボリュームマウント
• Unix 形式の絶対パスを含むコマンド

まとめ

Windows 上の Git Bash でのベストプラクティス：

1. ~/.bashrc に追加： export MSYS_NO_PATHCONV=1
2. docker-compose.yml で相対パスを使用： ./src:/app/src
3. データには名前付きボリュームを使用： my-data:/var/lib/data
4. バインドマウントには MSYS_NO_PATHCONV とともに $(pwd) を使用： MSYS_NO_PATHCONV=1 docker run -v $(pwd):/app

この設定により、パス変換の問題が発生することなく、Windows 上の Git Bash で Docker コマンドが正しく動作します。