windows-git-bash-paths

🚨 重要なガイドライン

Windows のファイルパス要件

必須：Windows ではファイルパスに必ずバックスラッシュを使用してください

Windows で Edit ツールまたは Write ツールを使う場合、ファイルパスにはスラッシュ（/）ではなく、必ずバックスラッシュ（\）を使用してください。

例：

• ❌ 誤り：D:/repos/project/file.tsx
• ✅ 正しい：D:\repos\project\file.tsx

これは以下に適用されます。

• Edit ツールの file_path パラメーター
• Write ツールの file_path パラメーター
• Windows システム上でのすべてのファイル操作

ドキュメント作成のガイドライン

ユーザーから明示的に依頼されない限り、新しいドキュメントファイルを作成しないでください。

• 優先事項：新しいドキュメントを作成するのではなく、既存の README.md ファイルを更新してください
• リポジトリの整理：ユーザーから別途依頼がない限り、リポジトリのルートは README.md のみとし、整理された状態を保ってください
• スタイル：ドキュメントは簡潔で、直接的かつプロフェッショナルなものにしてください。AI が生成したような文体は避けてください
• ユーザーの希望：ユーザーがドキュメントの作成を明示的に依頼した場合に限り、追加の .md ファイルを作成してください

---

SSDT のための Windows と Git Bash のパス処理

概要

SQL Server の開発は Windows 中心であり、多くの開発者は Windows 上で Git Bash（MINGW/MSYS2）を優先するシェルとして使用しています。そのため、Windows 形式のパスを想定する SqlPackage、MSBuild、Visual Studio などの Windows ネイティブツールを使う際に、固有のパス変換の問題が発生します。

このスキルでは、Windows 上で Git Bash を使用した SSDT ワークフローにおけるパス変換の問題、シェルの検出、ベストプラクティスへの包括的な対処法を説明します。

パス変換の問題

Git Bash/MINGW で起きること

Git Bash は POSIX 形式のパスを自動的に Windows のパスに変換しますが、コマンドライン引数で問題が発生することがあります。

自動変換：

• /foo → C:/Program Files/Git/usr/foo
• /foo:/bar → C:\msys64\foo;C:\msys64\bar
• --dir=/foo → --dir=C:/msys64/foo

SqlPackage で問題となる例：

# Git Bash converts /Action to a path!
sqlpackage /Action:Publish /SourceFile:MyDB.dacpac
# Becomes: sqlpackage C:/Program Files/Git/usr/Action:Publish ...

変換が発生する条件

✓ 引数の先頭にスラッシュ（/）がある ✓ コロン区切りのパスリスト ✓ パス要素を含む、- または , の後の引数

変換されないもの

✓ = を含む引数（変数の割り当て） ✓ ドライブ指定子（C:） ✓ ; を含む引数（すでに Windows 形式） ✓ // で始まる引数（Windows のスイッチ）

Git Bash で SqlPackage を使うための解決策

方法 1：MSYS_NO_PATHCONV（推奨）

特定のコマンドでパス変換を無効にします。

# Temporarily disable path conversion
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"MyDatabase.dacpac" \
  /TargetServerName:"localhost" \
  /TargetDatabaseName:"MyDB"

# Works for all SqlPackage actions
MSYS_NO_PATHCONV=1 sqlpackage /Action:Extract \
  /SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;" \
  /TargetFile:"MyDB_backup.dacpac"

重要な注意事項：

• VALUE の値は関係ありません。0、false、空文字列のいずれを設定しても変換は無効になります
• 重要なのは、この変数が定義されていることだけです
• 再び有効にするには：env -u MSYS_NO_PATHCONV

方法 2：ダブルスラッシュ //（代替）

SqlPackage のパラメーターにはダブルスラッシュを使用します。

# Works in Git Bash and CMD
sqlpackage //Action:Publish \
  //SourceFile:MyDatabase.dacpac \
  //TargetServerName:localhost \
  //TargetDatabaseName:MyDB

# Extract with double slashes
sqlpackage //Action:Extract \
  //SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;" \
  //TargetFile:output.dacpac

利点：

• 環境変数が不要です
• さまざまなシェルで動作します
• シェルに依存しないスクリプトを作成できます

方法 3：引用符で囲んだ Windows 形式のパスを使う

バックスラッシュを含むパスは必ず引用符で囲んでください。

# Quoted Windows paths work in Git Bash
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"D:\Projects\MyDB\bin\Release\MyDB.dacpac" \
  /TargetConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;"

# Or with forward slashes (Windows accepts both)
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"D:/Projects/MyDB/bin/Release/MyDB.dacpac" \
  /TargetConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;"

方法 4：PowerShell または CMD に切り替える

Windows ネイティブツールには、ネイティブシェルの使用を検討してください。

# PowerShell (recommended for Windows SSDT workflows)
sqlpackage /Action:Publish `
  /SourceFile:"MyDatabase.dacpac" `
  /TargetServerName:"localhost" `
  /TargetDatabaseName:"MyDB"

:: CMD
sqlpackage /Action:Publish ^
  /SourceFile:"MyDatabase.dacpac" ^
  /TargetServerName:"localhost" ^
  /TargetDatabaseName:"MyDB"

スクリプトでのシェル検出

Bash スクリプトでの検出

#!/bin/bash

# Method 1: Check $OSTYPE
case "$OSTYPE" in
  msys*)       # MSYS/Git Bash/MinGW
    export MSYS_NO_PATHCONV=1
    SQLPACKAGE_ARGS="/Action:Publish /SourceFile:MyDB.dacpac"
    ;;
  cygwin*)     # Cygwin
    export MSYS_NO_PATHCONV=1
    SQLPACKAGE_ARGS="/Action:Publish /SourceFile:MyDB.dacpac"
    ;;
  linux-gnu*)  # Linux
    SQLPACKAGE_ARGS="/Action:Publish /SourceFile:MyDB.dacpac"
    ;;
  darwin*)     # macOS
    SQLPACKAGE_ARGS="/Action:Publish /SourceFile:MyDB.dacpac"
    ;;
esac

sqlpackage $SQLPACKAGE_ARGS

# Method 2: Check uname -s (most portable)
case "$(uname -s)" in
  MINGW64*|MINGW32*)
    # Git Bash
    export MSYS_NO_PATHCONV=1
    echo "Git Bash detected - path conversion disabled"
    ;;
  MSYS_NT*)
    # MSYS
    export MSYS_NO_PATHCONV=1
    echo "MSYS detected - path conversion disabled"
    ;;
  CYGWIN*)
    # Cygwin
    export MSYS_NO_PATHCONV=1
    echo "Cygwin detected - path conversion disabled"
    ;;
  Linux*)
    # Linux or WSL
    echo "Linux detected"
    ;;
  Darwin*)
    # macOS
    echo "macOS detected"
    ;;
esac

# Method 3: Check $MSYSTEM (Git Bash specific)
if [ -n "$MSYSTEM" ]; then
  # Running in Git Bash/MSYS2
  export MSYS_NO_PATHCONV=1
  echo "MSYS environment detected: $MSYSTEM"
  case "$MSYSTEM" in
    MINGW64) echo "64-bit native Windows environment" ;;
    MINGW32) echo "32-bit native Windows environment" ;;
    MSYS)    echo "POSIX-compliant environment" ;;
  esac
fi

ビルドスクリプトの完全な例

#!/bin/bash
# build-and-deploy.sh - Cross-platform SSDT build script

set -e  # Exit on error

# Detect shell and set path conversion
if [ -n "$MSYSTEM" ]; then
  echo "Git Bash/MSYS2 detected - disabling path conversion"
  export MSYS_NO_PATHCONV=1
fi

# Variables
PROJECT_NAME="MyDatabase"
BUILD_CONFIG="Release"
DACPAC_PATH="bin/${BUILD_CONFIG}/${PROJECT_NAME}.dacpac"
TARGET_SERVER="${SQL_SERVER:-localhost}"
TARGET_DB="${SQL_DATABASE:-MyDB}"

# Build
echo "Building ${PROJECT_NAME}..."
dotnet build "${PROJECT_NAME}.sqlproj" -c "$BUILD_CONFIG"

# Verify DACPAC exists
if [ ! -f "$DACPAC_PATH" ]; then
  echo "ERROR: DACPAC not found at $DACPAC_PATH"
  exit 1
fi

echo "DACPAC built successfully: $DACPAC_PATH"

# Deploy
echo "Deploying to ${TARGET_SERVER}/${TARGET_DB}..."

# Use double-slash method for maximum compatibility
sqlpackage //Action:Publish \
  //SourceFile:"$DACPAC_PATH" \
  //TargetServerName:"$TARGET_SERVER" \
  //TargetDatabaseName:"$TARGET_DB" \
  //p:BlockOnPossibleDataLoss=False

echo "Deployment complete!"

Git Bash でよくある SSDT のパス問題

問題 1：DACPAC ファイルのパス

問題：

# Git Bash mangles the path
sqlpackage /Action:Publish /SourceFile:./bin/Release/MyDB.dacpac
# Error: Cannot find file

解決策：

# Use MSYS_NO_PATHCONV
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"./bin/Release/MyDB.dacpac"

# OR use absolute Windows path
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"D:/Projects/MyDB/bin/Release/MyDB.dacpac"

# OR use double slashes
sqlpackage //Action:Publish //SourceFile:./bin/Release/MyDB.dacpac

問題 2：SQL プロジェクトファイルのパス

問題：

# Path with spaces causes issues
dotnet build "D:/Program Files/MyProject/Database.sqlproj"
# Works in Git Bash (dotnet handles paths correctly)

# But MSBuild paths may fail
msbuild "D:/Program Files/MyProject/Database.sqlproj"
# May fail if not quoted properly

解決策：

# Always quote paths with spaces
dotnet build "D:/Program Files/MyProject/Database.sqlproj"

# Use backslashes for MSBuild on Windows
msbuild "D:\Program Files\MyProject\Database.sqlproj"

# Or use 8.3 short names (no spaces)
msbuild "D:/PROGRA~1/MyProject/Database.sqlproj"

問題 3：発行プロファイルのパス

問題：

# Publish profile not found
sqlpackage /Action:Publish \
  /SourceFile:MyDB.dacpac \
  /Profile:./Profiles/Production.publish.xml

解決策：

# Use MSYS_NO_PATHCONV with quoted paths
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"MyDB.dacpac" \
  /Profile:"./Profiles/Production.publish.xml"

# Or absolute Windows path
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"D:/Projects/MyDB.dacpac" \
  /Profile:"D:/Projects/Profiles/Production.publish.xml"

問題 4：接続文字列

問題：

# File paths in connection strings
/SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;AttachDbFilename=D:/Data/MyDB.mdf"
# Path gets mangled

解決策：

# Quote entire connection string
MSYS_NO_PATHCONV=1 sqlpackage /Action:Extract \
  /SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;AttachDbFilename=D:\Data\MyDB.mdf" \
  /TargetFile:"output.dacpac"

# Or use double backslashes in connection string
/SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;AttachDbFilename=D:\\Data\\MyDB.mdf"

CI/CD に関する考慮事項

Git Bash を使った GitHub Actions

name: SSDT Build and Deploy

on: [push]

jobs:
  build:
    runs-on: windows-latest
    defaults:
      run:
        shell: bash  # Use Git Bash

    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Install SqlPackage
        run: dotnet tool install -g Microsoft.SqlPackage

      - name: Build Database Project
        run: dotnet build Database.sqlproj -c Release

      - name: Deploy with Path Conversion Disabled
        env:
          MSYS_NO_PATHCONV: 1
        run: |
          sqlpackage /Action:Publish \
            /SourceFile:"bin/Release/MyDatabase.dacpac" \
            /TargetServerName:"localhost" \
            /TargetDatabaseName:"MyDB"

PowerShell の代替案（Windows で推奨）

jobs:
  build:
    runs-on: windows-latest
    defaults:
      run:
        shell: pwsh  # Use PowerShell - no path issues

    steps:
      - name: Deploy Database
        run: |
          sqlpackage /Action:Publish `
            /SourceFile:"bin/Release/MyDatabase.dacpac" `
            /TargetServerName:"localhost" `
            /TargetDatabaseName:"MyDB"

ベストプラクティスのまとめ

対話形式の開発では

1. Windows での SSDT には PowerShell または CMD を使用してください。パス変換の問題を完全に回避できます
2. Git Bash を使用する場合は、SSDT の作業に備えてシェルプロファイルで MSYS_NO_PATHCONV=1 を設定してください
3. スペースや特殊文字を含むパスは必ず引用符で囲んでください
4. 可能な場合は絶対パスを使用して、曖昧さを避けてください

スクリプトの場合

1. シェル環境を検出し、条件に応じて MSYS_NO_PATHCONV=1 を設定します
2. SqlPackage の引数にはダブルスラッシュ構文を使用します（最も移植性に優れています）
3. Windows 固有のワークフロー（ビルドスクリプト、CI/CD）には PowerShell を優先します
4. 対象となるすべてのプラットフォーム（Windows PowerShell、Git Bash、Linux）でスクリプトをテストします

CI/CD の場合

1. GitHub Actions の Windows ランナーでは PowerShell シェル（shell: pwsh）を使用します
2. セルフホストの Windows エージェントでは、ネイティブの Windows パスとシェルを使用します
3. Git Bash が必要な場合は、MSYS_NO_PATHCONV=1 を環境変数として設定します
4. クロスプラットフォーム互換性を高めるため、MSBuild よりも dotnet CLI を優先します

チームの場合

1. リポジトリの README にシェル要件を記載します
2. すべてのシェル（bash、PowerShell、CMD）用のスクリプトを用意します
3. 可能な限り、Windows SSDT ワークフローでは PowerShell を標準として使用します
4. シェル固有の問題を避けるため、コンテナー化したビルドを使用します

クイックリファレンス

環境変数

# Disable path conversion (Git Bash/MSYS2/Cygwin)
export MSYS_NO_PATHCONV=1

# Re-enable path conversion
env -u MSYS_NO_PATHCONV

SqlPackage コマンドテンプレート

# Git Bash - Method 1 (MSYS_NO_PATHCONV)
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish /SourceFile:"MyDB.dacpac" /TargetServerName:"localhost" /TargetDatabaseName:"MyDB"

# Git Bash - Method 2 (Double Slash)
sqlpackage //Action:Publish //SourceFile:MyDB.dacpac //TargetServerName:localhost //TargetDatabaseName:MyDB

# PowerShell (Recommended for Windows)
sqlpackage /Action:Publish /SourceFile:"MyDB.dacpac" /TargetServerName:"localhost" /TargetDatabaseName:"MyDB"

# CMD
sqlpackage /Action:Publish /SourceFile:"MyDB.dacpac" /TargetServerName:"localhost" /TargetDatabaseName:"MyDB"

シェル検出のワンライナー

# Check if Git Bash/MSYS
[ -n "$MSYSTEM" ] && echo "Git Bash/MSYS2 detected"

# Check uname
[[ "$(uname -s)" =~ ^MINGW ]] && echo "Git Bash detected"

# Set path conversion conditionally
[ -n "$MSYSTEM" ] && export MSYS_NO_PATHCONV=1

リソース

• Git Bash のパス変換ガイド
• MSYS2 のパス変換ドキュメント
• SqlPackage のドキュメント
• Microsoft.Build.Sql SDK
• Git for Windows

トラブルシューティング

「Invalid parameter」エラー

症状： SqlPackage が「Invalid parameter」または「Unknown action」と報告します
原因： Git Bash が /Action をファイルパスに変換しています
対処方法： MSYS_NO_PATHCONV=1 またはダブルスラッシュの //Action を使用します

有効なパスを指定しているのに「File not found」と表示される

症状： パスが正しいにもかかわらず、DACPAC またはプロジェクトファイルが見つかりません
原因： パス変換によってファイルパスが書き換えられています
対処方法： パスを引用符で囲み、MSYS_NO_PATHCONV=1 を使用します

ビルドは成功するが、発行に失敗する

症状： dotnet build は動作しますが、sqlpackage は失敗します
原因： dotnet CLI はパスを正しく処理しますが、SqlPackage は / 形式のパラメーターを使用します
対処方法： SqlPackage コマンドにのみ MSYS_NO_PATHCONV=1 を使用します

パスにスペースが含まれているとエラーになる

症状： 「Program Files」など、スペースを含むパスで失敗します
原因： 引用符で囲まれていないパスが複数の引数に分割されています
対処方法： 常にパスを引用符で囲みます：/SourceFile:"D:/Program Files/MyDB.dacpac"