⚠️

重要前提

安装AI Skills的关键前提是：必须科学上网，且开启TUN模式，这一点至关重要，直接决定安装能否顺利完成，在此郑重提醒三遍：科学上网，科学上网，科学上网。查看完整安装教程 →

Windows Git Bash路径处理指南：解决SSDT、SqlPackage路径转换问题

windows-git-bash-paths by josiahsiegel/claude-plugin-marketplace

63 周安装量

21 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/josiahsiegel/claude-plugin-marketplace --skill windows-git-bash-paths

开发命令行工具版本控制

🇨🇳中文介绍

🚨 关键准则

Windows 文件路径要求

强制：在 Windows 上始终对文件路径使用反斜杠

在 Windows 上使用编辑或写入工具时，您必须在文件路径中使用反斜杠 (\)，而不是正斜杠 (/)。

示例：

❌ 错误：D:/repos/project/file.tsx
✅ 正确：D:\repos\project\file.tsx

这适用于：

编辑工具的 file_path 参数
写入工具的 file_path 参数
Windows 系统上的所有文件操作

文档准则

除非用户明确要求，否则切勿创建新的文档文件。

优先级：更新现有的 README.md 文件，而不是创建新文档
仓库整洁性：保持仓库根目录整洁 - 除非用户另有要求，否则只保留 README.md
风格：文档应简洁、直接且专业 - 避免 AI 生成的语气
用户偏好：仅当用户明确要求文档时，才创建额外的 .md 文件

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

适用于 SSDT 的 Windows 和 Git Bash 路径处理

SQL Server 开发主要基于 Windows，许多开发人员在 Windows 上使用 Git Bash (MINGW/MSYS2) 作为首选 shell。当与需要 Windows 风格路径的 Windows 原生工具（如 SqlPackage、MSBuild 和 Visual Studio）一起工作时，这带来了独特的路径转换挑战。

本技能提供了在 Windows 上使用 Git Bash 进行 SSDT 工作流时，处理路径转换问题、shell 检测和最佳实践的全面指导。

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 将 /Action 转换为路径！
sqlpackage /Action:Publish /SourceFile:MyDB.dacpac
# 变为：sqlpackage C:/Program Files/Git/usr/Action:Publish ...

触发转换的情况

✓ 参数中的前导正斜杠 (/) ✓ 冒号分隔的路径列表 ✓ 跟在 - 或 , 后面且包含路径组件的参数

✓ 包含 = 的参数（变量赋值） ✓ 驱动器说明符 (C:) ✓ 包含 ; 的参数（已经是 Windows 格式） ✓ 以 // 开头的参数（Windows 开关）

Git Bash 中 SqlPackage 的解决方案

方法 1：MSYS_NO_PATHCONV（推荐）

为特定命令禁用路径转换：

# 临时禁用路径转换
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"MyDatabase.dacpac" \
  /TargetServerName:"localhost" \
  /TargetDatabaseName:"MyDB"

# 适用于所有 SqlPackage 操作
MSYS_NO_PATHCONV=1 sqlpackage /Action:Extract \
  /SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;" \
  /TargetFile:"MyDB_backup.dacpac"

变量的值无关紧要 - 设置为 0、false 或空值仍会禁用转换
只要变量被定义即可
要重新启用：env -u MSYS_NO_PATHCONV

方法 2：双斜杠 //（替代方案）

对 SqlPackage 参数使用双斜杠：

# 在 Git Bash 和 CMD 中均有效
sqlpackage //Action:Publish \
  //SourceFile:MyDatabase.dacpac \
  //TargetServerName:localhost \
  //TargetDatabaseName:MyDB

# 使用双斜杠进行提取
sqlpackage //Action:Extract \
  //SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;" \
  //TargetFile:output.dacpac

不需要环境变量
跨 shell 工作
与 shell 无关的脚本

方法 3：使用带引号的 Windows 风格路径

始终使用反斜杠引用路径：

# 带引号的 Windows 路径在 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;"

# 或使用正斜杠（Windows 两者都接受）
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 原生工具，考虑使用原生 shell：

# PowerShell（推荐用于 Windows SSDT 工作流）
sqlpackage /Action:Publish `
  /SourceFile:"MyDatabase.dacpac" `
  /TargetServerName:"localhost" `
  /TargetDatabaseName:"MyDB"



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

脚本的 Shell 检测

#!/bin/bash

# 方法 1：检查 $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



# 方法 2：检查 uname -s（最便携）
case "$(uname -s)" in
  MINGW64*|MINGW32*)
    # Git Bash
    export MSYS_NO_PATHCONV=1
    echo "Git Bash 检测到 - 路径转换已禁用"
    ;;
  MSYS_NT*)
    # MSYS
    export MSYS_NO_PATHCONV=1
    echo "MSYS 检测到 - 路径转换已禁用"
    ;;
  CYGWIN*)
    # Cygwin
    export MSYS_NO_PATHCONV=1
    echo "Cygwin 检测到 - 路径转换已禁用"
    ;;
  Linux*)
    # Linux 或 WSL
    echo "Linux 检测到"
    ;;
  Darwin*)
    # macOS
    echo "macOS 检测到"
    ;;
esac



# 方法 3：检查 $MSYSTEM（Git Bash 特定）
if [ -n "$MSYSTEM" ]; then
  # 在 Git Bash/MSYS2 中运行
  export MSYS_NO_PATHCONV=1
  echo "MSYS 环境检测到：$MSYSTEM"
  case "$MSYSTEM" in
    MINGW64) echo "64 位原生 Windows 环境" ;;
    MINGW32) echo "32 位原生 Windows 环境" ;;
    MSYS)    echo "POSIX 兼容环境" ;;
  esac
fi

完整的构建脚本示例

#!/bin/bash
# build-and-deploy.sh - 跨平台 SSDT 构建脚本

set -e  # 出错时退出

# 检测 shell 并设置路径转换
if [ -n "$MSYSTEM" ]; then
  echo "Git Bash/MSYS2 检测到 - 禁用路径转换"
  export MSYS_NO_PATHCONV=1
fi

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

# 构建
echo "正在构建 ${PROJECT_NAME}..."
dotnet build "${PROJECT_NAME}.sqlproj" -c "$BUILD_CONFIG"

# 验证 DACPAC 是否存在
if [ ! -f "$DACPAC_PATH" ]; then
  echo "错误：在 $DACPAC_PATH 未找到 DACPAC"
  exit 1
fi

echo "DACPAC 构建成功：$DACPAC_PATH"

# 部署
echo "正在部署到 ${TARGET_SERVER}/${TARGET_DB}..."

# 使用双斜杠方法以获得最大兼容性
sqlpackage //Action:Publish \
  //SourceFile:"$DACPAC_PATH" \
  //TargetServerName:"$TARGET_SERVER" \
  //TargetDatabaseName:"$TARGET_DB" \
  //p:BlockOnPossibleDataLoss=False

echo "部署完成！"

Git Bash 中常见的 SSDT 路径问题

问题 1：DACPAC 文件路径

# Git Bash 破坏了路径
sqlpackage /Action:Publish /SourceFile:./bin/Release/MyDB.dacpac
# 错误：找不到文件

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

# 或使用绝对 Windows 路径
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"D:/Projects/MyDB/bin/Release/MyDB.dacpac"

# 或使用双斜杠
sqlpackage //Action:Publish //SourceFile:./bin/Release/MyDB.dacpac

问题 2：SQL 项目文件路径

# 包含空格的路径会导致问题
dotnet build "D:/Program Files/MyProject/Database.sqlproj"
# 在 Git Bash 中有效（dotnet 正确处理路径）

# 但 MSBuild 路径可能会失败
msbuild "D:/Program Files/MyProject/Database.sqlproj"
# 如果未正确引用，可能会失败

# 始终引用包含空格的路径
dotnet build "D:/Program Files/MyProject/Database.sqlproj"

# 在 Windows 上对 MSBuild 使用反斜杠
msbuild "D:\Program Files\MyProject\Database.sqlproj"

# 或使用 8.3 短名称（无空格）
msbuild "D:/PROGRA~1/MyProject/Database.sqlproj"

问题 3：发布配置文件路径

# 找不到发布配置文件
sqlpackage /Action:Publish \
  /SourceFile:MyDB.dacpac \
  /Profile:./Profiles/Production.publish.xml

# 使用带引号路径的 MSYS_NO_PATHCONV
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"MyDB.dacpac" \
  /Profile:"./Profiles/Production.publish.xml"

# 或使用绝对 Windows 路径
MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish \
  /SourceFile:"D:/Projects/MyDB.dacpac" \
  /Profile:"D:/Projects/Profiles/Production.publish.xml"

问题 4：连接字符串

# 连接字符串中的文件路径
/SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;AttachDbFilename=D:/Data/MyDB.mdf"
# 路径被破坏

# 引用整个连接字符串
MSYS_NO_PATHCONV=1 sqlpackage /Action:Extract \
  /SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;AttachDbFilename=D:\Data\MyDB.mdf" \
  /TargetFile:"output.dacpac"

# 或在连接字符串中使用双反斜杠
/SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;AttachDbFilename=D:\\Data\\MyDB.mdf"

使用 Git Bash 的 GitHub Actions

name: SSDT 构建与部署

on: [push]

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

    steps:
      - uses: actions/checkout@v4

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

      - name: 安装 SqlPackage
        run: dotnet tool install -g Microsoft.SqlPackage

      - name: 构建数据库项目
        run: dotnet build Database.sqlproj -c Release

      - name: 部署（禁用路径转换）
        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  # 使用 PowerShell - 无路径问题

    steps:
      - name: 部署数据库
        run: |
          sqlpackage /Action:Publish `
            /SourceFile:"bin/Release/MyDatabase.dacpac" `
            /TargetServerName:"localhost" `
            /TargetDatabaseName:"MyDB"

对于交互式开发

在 Windows 上使用 PowerShell 或 CMD 进行 SSDT - 完全避免路径转换问题
如果使用 Git Bash，请在 shell 配置文件中为 SSDT 工作设置 MSYS_NO_PATHCONV=1
始终引用包含空格或特殊字符的路径
尽可能使用绝对路径以避免歧义

检测 shell 环境并条件性地设置 MSYS_NO_PATHCONV=1
对 SqlPackage 参数使用双斜杠 // 语法（最便携）
对于 Windows 特定的工作流，优先使用 PowerShell（构建脚本、CI/CD）
在所有目标平台上测试脚本（Windows PowerShell、Git Bash、Linux）

在 GitHub Actions 中使用 PowerShell shell 用于 Windows 运行器（shell: pwsh）
自托管的 Windows 代理 - 使用原生 Windows 路径和 shell
如果需要 Git Bash，则将 MSYS_NO_PATHCONV=1 设置为环境变量
为了跨平台兼容性，优先使用 dotnet CLI 而不是 MSBuild

在仓库 README 中记录 shell 要求
为所有 shell 提供脚本（bash、PowerShell、CMD）
尽可能在 Windows SSDT 工作流中标准化使用 PowerShell
使用容器化构建以避免 shell 特定问题

# 禁用路径转换（Git Bash/MSYS2/Cygwin）
export MSYS_NO_PATHCONV=1

# 重新启用路径转换
env -u MSYS_NO_PATHCONV

SqlPackage 命令模板

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

# Git Bash - 方法 2 (双斜杠)
sqlpackage //Action:Publish //SourceFile:MyDB.dacpac //TargetServerName:localhost //TargetDatabaseName:MyDB

# PowerShell (推荐用于 Windows)
sqlpackage /Action:Publish /SourceFile:"MyDB.dacpac" /TargetServerName:"localhost" /TargetDatabaseName:"MyDB"

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

Shell 检测单行命令

# 检查是否为 Git Bash/MSYS
[ -n "$MSYSTEM" ] && echo "Git Bash/MSYS2 检测到"

# 检查 uname
[[ "$(uname -s)" =~ ^MINGW ]] && echo "Git Bash 检测到"

# 条件性地设置路径转换
[ -n "$MSYSTEM" ] && export MSYS_NO_PATHCONV=1

"无效参数" 错误

症状： SqlPackage 报告"无效参数"或"未知操作" 原因： Git Bash 将 /Action 转换为文件路径 修复： 使用 MSYS_NO_PATHCONV=1 或双斜杠 //Action

路径有效但"找不到文件"

症状： 路径正确但找不到 DACPAC 或项目文件 原因： 路径转换破坏了文件路径 修复： 引用路径并使用 MSYS_NO_PATHCONV=1

构建成功但发布失败

症状： dotnet build 有效但 sqlpackage 失败 原因： dotnet CLI 正确处理路径，但 SqlPackage 使用 / 参数 修复： 仅对 SqlPackage 命令使用 MSYS_NO_PATHCONV=1

路径中的空格导致错误

症状： 包含"Program Files"或其他空格的路径失败 原因： 未引用的路径被拆分为多个参数 修复： 始终引用路径：/SourceFile:"D:/Program Files/MyDB.dacpac"

🇺🇸English

🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

❌ WRONG: D:/repos/project/file.tsx
✅ CORRECT: D:\repos\project\file.tsx

This applies to:

Edit tool file_path parameter
Write tool file_path parameter
All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

Priority : Update existing README.md files rather than creating new documentation
Repository cleanliness : Keep repository root clean - only README.md unless user requests otherwise
Style : Documentation should be concise, direct, and professional - avoid AI-generated tone
User preference : Only create additional .md files when user specifically asks for documentation

Windows and Git Bash Path Handling for SSDT

Overview

SQL Server development is Windows-heavy, and many developers use Git Bash (MINGW/MSYS2) as their preferred shell on Windows. This creates unique path conversion challenges when working with Windows-native tools like SqlPackage, MSBuild, and Visual Studio that expect Windows-style paths.

This skill provides comprehensive guidance on handling path conversion issues, shell detection, and best practices for SSDT workflows on Windows with Git Bash.

The Path Conversion Problem

What Happens in Git Bash/MINGW

Git Bash automatically converts POSIX-style paths to Windows paths, but this can cause issues with command-line arguments:

Automatic Conversions:

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

Problematic for SqlPackage:

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

What Triggers Conversion

✓ Leading forward slash (/) in arguments ✓ Colon-separated path lists ✓ Arguments after - or , with path components

What's Exempt

✓ Arguments containing = (variable assignments) ✓ Drive specifiers (C:) ✓ Arguments with ; (already Windows format) ✓ Arguments starting with // (Windows switches)

Solutions for SqlPackage in Git Bash

Method 1: MSYS_NO_PATHCONV (Recommended)

Disable path conversion for specific commands:

# 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"

Important Notes:

The VALUE doesn't matter - setting to 0, false, or empty still disables conversion
Only matters that variable is DEFINED
To re-enable: env -u MSYS_NO_PATHCONV

Method 2: Double Slash // (Alternative)

Use double slashes for SqlPackage parameters:

# 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

Advantages:

No environment variable needed
Works across shells
Shell-agnostic scripts

Method 3: Use Windows-Style Paths with Quotes

Always quote paths with backslashes:

# 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;"

Method 4: Switch to PowerShell or CMD

For Windows-native tools, consider using native shells:

# 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"

Shell Detection for Scripts

Bash Script Detection

#!/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

Complete Build Script Example

#!/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!"

Common SSDT Path Issues in Git Bash

Issue 1: DACPAC File Paths

Problem:

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

Solution:

# 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

Issue 2: SQL Project File Paths

Problem:

# 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

Solution:

# 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"

Issue 3: Publish Profile Paths

Problem:

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

Solution:

# 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"

Issue 4: Connection Strings

Problem:

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

Solution:

# 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 Considerations

GitHub Actions with Git Bash

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 Alternative (Recommended for 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"

Best Practices Summary

For Interactive Development

Use PowerShell or CMD for SSDT on Windows - avoids path conversion issues entirely
If using Git Bash , set MSYS_NO_PATHCONV=1 in your shell profile for SSDT work
Always quote paths containing spaces or special characters
Use absolute paths when possible to avoid ambiguity

For Scripts

Detect shell environment and set MSYS_NO_PATHCONV=1 conditionally
Use double-slash // syntax for SqlPackage arguments (most portable)
Prefer PowerShell for Windows-specific workflows (build scripts, CI/CD)
Test scripts on all target platforms (Windows PowerShell, Git Bash, Linux)

For CI/CD

Use PowerShell shell in GitHub Actions for Windows runners (shell: pwsh)
Self-hosted Windows agents - use native Windows paths and shells
Set MSYS_NO_PATHCONV=1 as environment variable if Git Bash required
Prefer dotnet CLI over MSBuild for cross-platform compatibility

For Teams

Document shell requirements in repository README
Provide scripts for all shells (bash, PowerShell, CMD)
Standardize on PowerShell for Windows SSDT workflows when possible
Use containerized builds to avoid shell-specific issues

Quick Reference

Environment Variables

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

# Re-enable path conversion
env -u MSYS_NO_PATHCONV

SqlPackage Command Templates

# 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"

Shell Detection One-Liners

# 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

Resources

Troubleshooting

"Invalid parameter" errors

Symptom: SqlPackage reports "Invalid parameter" or "Unknown action" Cause: Git Bash converting /Action to a file path Fix: Use MSYS_NO_PATHCONV=1 or double-slash //Action

"File not found" with valid paths

Symptom: DACPAC or project file not found despite correct path Cause: Path conversion mangling the file path Fix: Quote paths and use MSYS_NO_PATHCONV=1

Build succeeds but publish fails

Symptom: dotnet build works but sqlpackage fails Cause: dotnet CLI handles paths correctly, but SqlPackage uses / parameters Fix: Use MSYS_NO_PATHCONV=1 for SqlPackage commands only

Spaces in paths cause errors

Symptom: Paths with "Program Files" or other spaces fail Cause: Unquoted paths split into multiple arguments Fix: Always quote paths: /SourceFile:"D:/Program Files/MyDB.dacpac"

Weekly Installs

Repository

josiahsiegel/cl…ketplace

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

claude-code51

gemini-cli49

opencode49

codex46

cursor45

github-copilot42

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

123,700 周安装

Windows Git Bash路径处理指南：解决SSDT、SqlPackage路径转换问题

🇨🇳中文介绍

🚨 关键准则

Windows 文件路径要求

文档准则

相关 Skills

适用于 SSDT 的 Windows 和 Git Bash 路径处理

概述

路径转换问题

Git Bash/MINGW 中发生的情况

触发转换的情况

豁免情况

Git Bash 中 SqlPackage 的解决方案

方法 1：MSYS_NO_PATHCONV（推荐）

方法 2：双斜杠 //（替代方案）

方法 3：使用带引号的 Windows 风格路径

方法 4：切换到 PowerShell 或 CMD

脚本的 Shell 检测

Bash 脚本检测

完整的构建脚本示例

Git Bash 中常见的 SSDT 路径问题

问题 1：DACPAC 文件路径

问题 2：SQL 项目文件路径

问题 3：发布配置文件路径

问题 4：连接字符串

CI/CD 注意事项

使用 Git Bash 的 GitHub Actions

PowerShell 替代方案（推荐用于 Windows）

最佳实践总结

对于交互式开发

对于脚本

对于 CI/CD

对于团队

快速参考

环境变量

SqlPackage 命令模板

Shell 检测单行命令

资源

故障排除

"无效参数" 错误

路径有效但"找不到文件"

构建成功但发布失败

路径中的空格导致错误

🇺🇸English

🚨 CRITICAL GUIDELINES

Windows File Path Requirements

Documentation Guidelines

Windows and Git Bash Path Handling for SSDT

Overview

The Path Conversion Problem

What Happens in Git Bash/MINGW

What Triggers Conversion

What's Exempt

Solutions for SqlPackage in Git Bash

Method 1: MSYS_NO_PATHCONV (Recommended)

Method 2: Double Slash // (Alternative)

Method 3: Use Windows-Style Paths with Quotes

Method 4: Switch to PowerShell or CMD

Shell Detection for Scripts

Bash Script Detection

Complete Build Script Example

Common SSDT Path Issues in Git Bash

Issue 1: DACPAC File Paths

Issue 2: SQL Project File Paths

Issue 3: Publish Profile Paths

Issue 4: Connection Strings

CI/CD Considerations

GitHub Actions with Git Bash

PowerShell Alternative (Recommended for Windows)

Best Practices Summary

For Interactive Development

For Scripts

For CI/CD

For Teams

Quick Reference

Environment Variables

SqlPackage Command Templates

Shell Detection One-Liners

Resources

Troubleshooting