🚨 CRITICAL GUIDELINES

🚨 关键准则

Windows File Path Requirements

Windows文件路径要求

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

强制要求：在Windows上始终使用反斜杠表示文件路径

在Windows系统上使用编辑或写入工具时，文件路径必须使用反斜杠（

），而非正斜杠（

）。

示例：

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

此要求适用于：

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

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

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

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

Windows and Git Bash Path Handling for SSDT

SSDT的Windows与Git Bash路径处理

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.

SQL Server开发以Windows环境为主，许多开发者在Windows上选择Git Bash（MINGW/MSYS2）作为首选Shell。这在使用SqlPackage、MSBuild和Visual Studio等Windows原生工具时，会带来独特的路径转换挑战，因为这些工具期望接收Windows风格的路径。

本指南提供了在Windows与Git Bash环境下处理SSDT工作流时，关于路径转换问题、Shell检测及最佳实践的全面指导。

The Path Conversion Problem

路径转换问题

What Happens in Git Bash/MINGW

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:

bash

undefined

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的影响：

bash

undefined

Git Bash converts /Action to a path!

Git Bash会将/Action转换为路径！

sqlpackage /Action:Publish /SourceFile:MyDB.dacpac

Becomes: sqlpackage C:/Program Files/Git/usr/Action:Publish ...

实际执行：sqlpackage C:/Program Files/Git/usr/Action:Publish ...

undefined

undefined

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)

✓ 包含

的参数（变量赋值） ✓ 驱动器标识符（

C:

） ✓ 带有

的参数（已为Windows格式） ✓ 以

//

开头的参数（Windows开关）

Solutions for SqlPackage in Git Bash

Git Bash中SqlPackage的解决方案

Method 1: MSYS_NO_PATHCONV (Recommended)

方法1：MSYS_NO_PATHCONV（推荐）

Disable path conversion for specific commands:

bash

undefined

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

bash

undefined

Temporarily disable path conversion

临时禁用路径转换

MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish
/SourceFile:"MyDatabase.dacpac"
/TargetServerName:"localhost"
/TargetDatabaseName:"MyDB"

Works for all SqlPackage actions

适用于所有SqlPackage操作

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`

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`

Method 2: Double Slash // (Alternative)

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

Use double slashes for SqlPackage parameters:

bash

undefined

为SqlPackage参数使用双斜杠：

bash

undefined

Works in Git Bash and CMD

在Git Bash和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

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


**优势：**
- 无需设置环境变量
- 跨Shell兼容
- 编写与Shell无关的脚本

Method 3: Use Windows-Style Paths with Quotes

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

Always quote paths with backslashes:

bash

undefined

始终为带反斜杠的路径添加引号：

bash

undefined

Quoted Windows paths work in Git Bash

带引号的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;"

Or with forward slashes (Windows accepts both)

也可使用正斜杠（Windows同时支持两种格式）

MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish
/SourceFile:"D:/Projects/MyDB/bin/Release/MyDB.dacpac"
/TargetConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;"

undefined

MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish
/SourceFile:"D:/Projects/MyDB/bin/Release/MyDB.dacpac"
/TargetConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;"

undefined

Method 4: Switch to PowerShell or CMD

方法4：切换到PowerShell或CMD

For Windows-native tools, consider using native shells:

powershell

undefined

对于Windows原生工具，考虑使用原生Shell：

powershell

undefined

PowerShell (recommended for Windows SSDT workflows)

PowerShell（推荐用于Windows SSDT工作流）

sqlpackage /Action:Publish

  /SourceFile:"MyDatabase.dacpac"

/TargetServerName:"localhost" ` /TargetDatabaseName:"MyDB"


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

sqlpackage /Action:Publish

  /SourceFile:"MyDatabase.dacpac"

/TargetServerName:"localhost" ` /TargetDatabaseName:"MyDB"


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

Shell Detection for Scripts

脚本中的Shell检测

Bash Script Detection

Bash脚本检测

bash

#!/bin/bash

bash

#!/bin/bash

Method 1: Check $OSTYPE

方法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


```bash

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


```bash

Method 2: Check uname -s (most portable)

方法2：检查uname -s（最具可移植性）

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


```bash

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或WSL echo "Linux detected" ;; Darwin*) # macOS echo "macOS detected" ;; esac


```bash

Method 3: Check $MSYSTEM (Git Bash specific)

方法3：检查$MSYSTEM（Git Bash专用）

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

undefined

if [ -n "$MSYSTEM" ]; then

运行在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

undefined

Complete Build Script Example

完整构建脚本示例

bash

#!/bin/bash

bash

#!/bin/bash

build-and-deploy.sh - Cross-platform SSDT build script

build-and-deploy.sh - 跨平台SSDT构建脚本

set -e # Exit on error

set -e # 出错即退出

Detect shell and set path conversion

检测Shell并设置路径转换规则

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

验证DACPAC文件是否存在

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

echo "DACPAC built successfully: $DACPAC_PATH"

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

undefined

sqlpackage //Action:Publish
//SourceFile:"$DACPAC_PATH"
//TargetServerName:"$TARGET_SERVER"
//TargetDatabaseName:"$TARGET_DB"
//p:BlockOnPossibleDataLoss=False

echo "Deployment complete!"

undefined

Common SSDT Path Issues in Git Bash

Git Bash中常见的SSDT路径问题

Issue 1: DACPAC File Paths

问题1：DACPAC文件路径

Problem:

bash

undefined

问题现象：

bash

undefined

Git Bash mangles the path

Git Bash会篡改路径

sqlpackage /Action:Publish /SourceFile:./bin/Release/MyDB.dacpac

Error: Cannot find file

错误提示：无法找到文件


**Solution:**
```bash


**解决方案：**
```bash

Use MSYS_NO_PATHCONV

使用MSYS_NO_PATHCONV

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

OR use absolute Windows path

或使用绝对Windows路径

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

undefined

sqlpackage //Action:Publish //SourceFile:./bin/Release/MyDB.dacpac

undefined

Issue 2: SQL Project File Paths

问题2：SQL项目文件路径

Problem:

bash

undefined

问题现象：

bash

undefined

Path with spaces causes issues

带空格的路径会引发问题

dotnet build "D:/Program Files/MyProject/Database.sqlproj"

Works in Git Bash (dotnet handles paths correctly)

在Git Bash中可正常运行（dotnet能正确处理路径）

But MSBuild paths may fail

但MSBuild路径可能执行失败

msbuild "D:/Program Files/MyProject/Database.sqlproj"

May fail if not quoted properly

若未正确添加引号可能会失败


**Solution:**
```bash


**解决方案：**
```bash

Always quote paths with spaces

始终为带空格的路径添加引号

dotnet build "D:/Program Files/MyProject/Database.sqlproj"

Use backslashes for MSBuild on Windows

在Windows上为MSBuild使用反斜杠

msbuild "D:\Program Files\MyProject\Database.sqlproj"

Or use 8.3 short names (no spaces)

或使用8.3短文件名（无空格）

msbuild "D:/PROGRA~1/MyProject/Database.sqlproj"

undefined

msbuild "D:/PROGRA~1/MyProject/Database.sqlproj"

undefined

Issue 3: Publish Profile Paths

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

Problem:

bash

undefined

问题现象：

bash

undefined

Publish profile not found

找不到发布配置文件

sqlpackage /Action:Publish
/SourceFile:MyDB.dacpac
/Profile:./Profiles/Production.publish.xml


**Solution:**
```bash

sqlpackage /Action:Publish
/SourceFile:MyDB.dacpac
/Profile:./Profiles/Production.publish.xml


**解决方案：**
```bash

Use MSYS_NO_PATHCONV with quoted paths

为带引号的路径使用MSYS_NO_PATHCONV

MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish
/SourceFile:"MyDB.dacpac"
/Profile:"./Profiles/Production.publish.xml"

Or absolute Windows path

或使用绝对Windows路径

MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish
/SourceFile:"D:/Projects/MyDB.dacpac"
/Profile:"D:/Projects/Profiles/Production.publish.xml"

undefined

MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish
/SourceFile:"D:/Projects/MyDB.dacpac"
/Profile:"D:/Projects/Profiles/Production.publish.xml"

undefined

Issue 4: Connection Strings

问题4：连接字符串

Problem:

bash

undefined

问题现象：

bash

undefined

File paths in connection strings

连接字符串中的文件路径

/SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;AttachDbFilename=D:/Data/MyDB.mdf"

Path gets mangled

路径会被篡改


**Solution:**
```bash


**解决方案：**
```bash

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"

undefined

/SourceConnectionString:"Server=localhost;Database=MyDB;Integrated Security=True;AttachDbFilename=D:\Data\MyDB.mdf"

undefined

CI/CD Considerations

CI/CD注意事项

GitHub Actions with Git Bash

使用Git Bash的GitHub Actions

yaml

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"

yaml

name: SSDT Build and Deploy

on: [push]

jobs:
  build:
    runs-on: windows-latest
    defaults:
      run:
        shell: bash  # 使用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)

PowerShell替代方案（Windows环境推荐）

yaml

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"

yaml

jobs:
  build:
    runs-on: windows-latest
    defaults:
      run:
        shell: pwsh  # 使用PowerShell - 无路径问题

    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

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

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)

检测Shell环境并条件设置
```
MSYS_NO_PATHCONV=1
```
为SqlPackage参数使用双斜杠//语法（兼容性最强）
Windows特定工作流优先使用PowerShell（构建脚本、CI/CD）
在所有目标平台上测试脚本（Windows PowerShell、Git Bash、Linux）

For CI/CD

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

在GitHub Actions的Windows运行器中使用PowerShell Shell（
```
shell: pwsh
```
）
自托管Windows代理 - 使用原生Windows路径和Shell
若必须使用Git Bash，将MSYS_NO_PATHCONV=1设置为环境变量
优先使用dotnet CLI而非MSBuild以实现跨平台兼容性

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

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

Quick Reference

快速参考

Environment Variables

环境变量

bash

undefined

bash

undefined

Disable path conversion (Git Bash/MSYS2/Cygwin)

禁用路径转换（Git Bash/MSYS2/Cygwin）

export MSYS_NO_PATHCONV=1

Re-enable path conversion

重新启用路径转换

env -u MSYS_NO_PATHCONV

undefined

env -u MSYS_NO_PATHCONV

undefined

SqlPackage Command Templates

SqlPackage命令模板

bash

undefined

bash

undefined

Git Bash - Method 1 (MSYS_NO_PATHCONV)

Git Bash - 方法1（MSYS_NO_PATHCONV）

MSYS_NO_PATHCONV=1 sqlpackage /Action:Publish /SourceFile:"MyDB.dacpac" /TargetServerName:"localhost" /TargetDatabaseName:"MyDB"

Git Bash - Method 2 (Double Slash)

Git Bash - 方法2（双斜杠）

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

PowerShell (Recommended for Windows)

PowerShell（Windows环境推荐）

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

CMD

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

undefined

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

undefined

Shell Detection One-Liners

Shell检测单行命令

bash

undefined

bash

undefined

Check if Git Bash/MSYS

检查是否为Git Bash/MSYS

[ -n "$MSYSTEM" ] && echo "Git Bash/MSYS2 detected"

Check uname

检查uname结果

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

Set path conversion conditionally

条件设置路径转换规则

[ -n "$MSYSTEM" ] && export MSYS_NO_PATHCONV=1

undefined

[ -n "$MSYSTEM" ] && export MSYS_NO_PATHCONV=1

undefined

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

症状： SqlPackage报告"Invalid parameter"或"Unknown action" 原因： Git Bash将

/Action

转换为文件路径 解决方法： 使用

MSYS_NO_PATHCONV=1

或双斜杠

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

症状： 路径正确但DACPAC或项目文件未找到 原因： 路径转换篡改了文件路径 解决方法： 为路径添加引号并使用

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

症状：

dotnet build

正常执行但

sqlpackage

失败 原因： dotnet CLI能正确处理路径，但SqlPackage使用

开头的参数 解决方法： 仅为SqlPackage命令设置

MSYS_NO_PATHCONV=1

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"

症状： 包含"Program Files"等空格的路径执行失败 原因： 未加引号的路径被拆分为多个参数 解决方法： 始终为路径添加引号：

/SourceFile:"D:/Program Files/MyDB.dacpac"

windows-git-bash-paths

Original

Translation

🚨 CRITICAL GUIDELINES

🚨 关键准则

Windows File Path Requirements

Windows文件路径要求

Documentation Guidelines

文档规范

Windows and Git Bash Path Handling for SSDT

SSDT的Windows与Git Bash路径处理

Overview

概述

The Path Conversion Problem

路径转换问题

What Happens in Git Bash/MINGW

Git Bash/MINGW中的路径转换行为

Git Bash converts /Action to a path!

Git Bash会将/Action转换为路径！

Becomes: sqlpackage C:/Program Files/Git/usr/Action:Publish ...

实际执行：sqlpackage C:/Program Files/Git/usr/Action:Publish ...

What Triggers Conversion

触发路径转换的场景

What's Exempt

豁免路径转换的场景

Solutions for SqlPackage in Git Bash

Git Bash中SqlPackage的解决方案

Method 1: MSYS_NO_PATHCONV (Recommended)

方法1：MSYS_NO_PATHCONV（推荐）

Temporarily disable path conversion

临时禁用路径转换

Works for all SqlPackage actions

适用于所有SqlPackage操作

Method 2: Double Slash // (Alternative)

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

Works in Git Bash and CMD

在Git Bash和CMD中均可生效

Extract with double slashes

使用双斜杠执行提取操作

Method 3: Use Windows-Style Paths with Quotes

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

Quoted Windows paths work in Git Bash

带引号的Windows路径在Git Bash中可正常使用

Or with forward slashes (Windows accepts both)

也可使用正斜杠（Windows同时支持两种格式）

Method 4: Switch to PowerShell or CMD

方法4：切换到PowerShell或CMD

PowerShell (recommended for Windows SSDT workflows)

PowerShell（推荐用于Windows SSDT工作流）

Shell Detection for Scripts

脚本中的Shell检测

Bash Script Detection

Bash脚本检测

Method 1: Check $OSTYPE

方法1：检查$OSTYPE

Method 2: Check uname -s (most portable)

方法2：检查uname -s（最具可移植性）

Method 3: Check $MSYSTEM (Git Bash specific)

方法3：检查$MSYSTEM（Git Bash专用）

Running in Git Bash/MSYS2

运行在Git Bash/MSYS2环境中

Complete Build Script Example

完整构建脚本示例

build-and-deploy.sh - Cross-platform SSDT build script

build-and-deploy.sh - 跨平台SSDT构建脚本

Detect shell and set path conversion

检测Shell并设置路径转换规则

Variables

变量定义

Build

构建项目

Verify DACPAC exists

验证DACPAC文件是否存在

Deploy

部署项目

Use double-slash method for maximum compatibility

使用双斜杠方法实现最大兼容性

Common SSDT Path Issues in Git Bash

Git Bash中常见的SSDT路径问题

Issue 1: DACPAC File Paths