windows-git-bash-paths

What this skill does

## 🚨 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:**
```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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
# PowerShell (recommended for Windows SSDT workflows)
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

### Bash Script Detection

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

```bash
# 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
```

```bash
# 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

```bash
#!/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:**
```bash
# Git Bash mangles the path
sqlpackage /Action:Publish /SourceFile:./bin/Release/MyDB.dacpac
# Error: Cannot find file
```

**Solution:**
```bash
# 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:**
```bash
# Path with spaces causes issues
dotnet build "D:/Progr