⚠️

重要前提

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

解决Azure Data Factory在Windows Git Bash中的路径兼容性问题 | 开发运维指南

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

72 周安装量

23 GitHub Stars

GitHub

安装命令

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

云服务开发运维命令行工具

🇨🇳中文介绍

Azure Data Factory 的 Windows 和 Git Bash 兼容性

概述

Azure Data Factory 开发经常在 Windows 机器上使用 Git Bash (MINGW64) 作为主要 shell。这引入了路径转换挑战，可能会破坏 CI/CD 流水线、npm 命令和部署脚本。

Git Bash 路径转换行为

自动路径转换

Git Bash (MINGW) 自动将 Unix 风格的路径转换为 Windows 路径：

转换示例：

/foo → C:/Program Files/Git/usr/foo
/foo:/bar → C:\msys64\foo;C:\msys64\bar (路径列表)
--dir=/foo → --dir=C:/msys64/foo (参数)

触发转换的条件：

参数中的前导正斜杠 (/)

广告位招租

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

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

联系我们

相关 Skills

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

305,300 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

174,900 周安装

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

162,100 周安装

Azure Data Explorer (Kusto) 查询技能：KQL数据分析、日志遥测与时间序列处理

161,200 周安装

#!/usr/bin/env bash

# 方法 1：检查 $MSYSTEM (Git Bash/MSYS2 特有)
if [ -n "$MSYSTEM" ]; then
  echo "Running in Git Bash/MinGW ($MSYSTEM)"
  export MSYS_NO_PATHCONV=1
fi

# 方法 2：检查 uname -s (更便携)
case "$(uname -s)" in
  MINGW64*|MINGW32*|MSYS*)
    echo "Git Bash detected"
    export MSYS_NO_PATHCONV=1
    ;;
  Linux*)
    if grep -q Microsoft /proc/version 2>/dev/null; then
      echo "WSL detected"
    else
      echo "Native Linux"
    fi
    ;;
  Darwin*)
    echo "macOS"
    ;;
esac

# 方法 3：检查 $OSTYPE (bash 特有)
case "$OSTYPE" in
  msys*)
    echo "Git Bash/MSYS"
    export MSYS_NO_PATHCONV=1
    ;;
  linux-gnu*)
    echo "Linux"
    ;;
  darwin*)
    echo "macOS"
    ;;
esac

// detect-shell.js - 用于 npm 脚本或 Node 工具
function detectShell() {
  const env = process.env;

  // Git Bash/MinGW (最可靠)
  if (env.MSYSTEM) {
    return {
      type: 'mingw',
      subsystem: env.MSYSTEM,  // MINGW64, MINGW32, or MSYS
      needsPathFix: true
    };
  }

  // WSL
  if (env.WSL_DISTRO_NAME) {
    return {
      type: 'wsl',
      distro: env.WSL_DISTRO_NAME,
      needsPathFix: false
    };
  }

  // PowerShell (PSModulePath 中有 3+ 个路径)
  if (env.PSModulePath?.split(';').length >= 3) {
    return {
      type: 'powershell',
      needsPathFix: false
    };
  }

  // CMD
  if (process.platform === 'win32' && env.PROMPT === '$P$G') {
    return {
      type: 'cmd',
      needsPathFix: false
    };
  }

  // Cygwin
  if (env.TERM === 'cygwin') {
    return {
      type: 'cygwin',
      needsPathFix: true
    };
  }

  // Unix shells
  if (env.SHELL?.includes('bash')) {
    return { type: 'bash', needsPathFix: false };
  }
  if (env.SHELL?.includes('zsh')) {
    return { type: 'zsh', needsPathFix: false };
  }

  return {
    type: 'unknown',
    platform: process.platform,
    needsPathFix: false
  };
}

// 用法
const shell = detectShell();
console.log(`Detected shell: ${shell.type}`);

if (shell.needsPathFix) {
  process.env.MSYS_NO_PATHCONV = '1';
  console.log('Path conversion disabled for Git Bash compatibility');
}

module.exports = { detectShell };

#!/usr/bin/env bash
set -e

# 检测并处理 Git Bash
if [ -n "$MSYSTEM" ]; then
  export MSYS_NO_PATHCONV=1
  echo "🔧 Git Bash detected - path conversion disabled"
fi

# 配置
ADF_ROOT="./adf-resources"
FACTORY_ID="/subscriptions/${AZURE_SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}/providers/Microsoft.DataFactory/factories/${FACTORY_NAME}"

# 验证 ADF 资源
echo "📋 Validating ADF resources..."
npm run build validate "$ADF_ROOT" "$FACTORY_ID"

# 生成 ARM 模板
echo "📦 Generating ARM templates..."
npm run build export "$ADF_ROOT" "$FACTORY_ID" "ARMTemplate"

echo "✅ Validation complete"

#!/usr/bin/env bash
set -e

# 检测 shell
detect_shell() {
  if [ -n "$MSYSTEM" ]; then echo "git-bash"
  elif [ -n "$WSL_DISTRO_NAME" ]; then echo "wsl"
  elif [[ "$OSTYPE" == "darwin"* ]]; then echo "macos"
  else echo "linux"
  fi
}

SHELL_TYPE=$(detect_shell)
echo "🖥️  Detected shell: $SHELL_TYPE"

# 处理 Git Bash
if [ "$SHELL_TYPE" = "git-bash" ]; then
  export MSYS_NO_PATHCONV=1
fi

# 下载 PrePostDeploymentScript
curl -sLo PrePostDeploymentScript.Ver2.ps1 \
  https://raw.githubusercontent.com/Azure/Azure-DataFactory/main/SamplesV2/ContinuousIntegrationAndDelivery/PrePostDeploymentScript.Ver2.ps1

# 停止触发器
echo "⏸️  Stopping triggers..."
MSYS_NO_PATHCONV=1 pwsh ./PrePostDeploymentScript.Ver2.ps1 \
  -armTemplate "./ARMTemplate/ARMTemplateForFactory.json" \
  -ResourceGroupName "$RESOURCE_GROUP" \
  -DataFactoryName "$FACTORY_NAME" \
  -predeployment $true \
  -deleteDeployment $false

# 部署 ARM 模板
echo "🚀 Deploying ARM template..."
az deployment group create \
  --resource-group "$RESOURCE_GROUP" \
  --template-file ./ARMTemplate/ARMTemplateForFactory.json \
  --parameters ./ARMTemplate/ARMTemplateParametersForFactory.json \
  --parameters factoryName="$FACTORY_NAME"

# 启动触发器
echo "▶️  Starting triggers..."
MSYS_NO_PATHCONV=1 pwsh ./PrePostDeploymentScript.Ver2.ps1 \
  -armTemplate "./ARMTemplate/ARMTemplateForFactory.json" \
  -ResourceGroupName "$RESOURCE_GROUP" \
  -DataFactoryName "$FACTORY_NAME" \
  -predeployment $false \
  -deleteDeployment $true

echo "✅ Deployment complete"

环境变量	用途	值
`MSYS_NO_PATHCONV`	禁用所有路径转换 (Git for Windows)	`1`
`MSYS2_ARG_CONV_EXCL`	从转换中排除特定参数 (MSYS2)	`*` 或模式
`MSYSTEM`	当前 MSYS 子系统	`MINGW64`, `MINGW32`, `MSYS`
`WSL_DISTRO_NAME`	WSL 发行版名称	`Ubuntu`, `Debian`, 等。

🇺🇸English

Windows & Git Bash Compatibility for Azure Data Factory

Overview

Azure Data Factory development frequently occurs on Windows machines using Git Bash (MINGW64) as the primary shell. This introduces path conversion challenges that can break CI/CD pipelines, npm commands, and deployment scripts.

Git Bash Path Conversion Behavior

Automatic Path Conversion

Git Bash (MINGW) automatically converts Unix-style paths to Windows paths:

Conversions:

/foo → C:/Program Files/Git/usr/foo
/foo:/bar → C:\msys64\foo;C:\msys64\bar (path lists)
--dir=/foo → --dir=C:/msys64/foo (arguments)

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)

ADF-Specific Path Issues

npm Build Commands

Problem:

# This fails in Git Bash due to path conversion
npm run build validate ./adf-resources /subscriptions/abc/resourceGroups/rg/providers/Microsoft.DataFactory/factories/myFactory

# Path gets converted incorrectly

Solution:

# Disable path conversion before running
export MSYS_NO_PATHCONV=1
npm run build validate ./adf-resources /subscriptions/abc/resourceGroups/rg/providers/Microsoft.DataFactory/factories/myFactory

# Or wrap the command
MSYS_NO_PATHCONV=1 npm run build export ./adf-resources /subscriptions/.../myFactory "ARMTemplate"

PowerShell Scripts

Problem:

# Calling PowerShell scripts from Git Bash
pwsh ./PrePostDeploymentScript.Ver2.ps1 -armTemplate "./ARMTemplate/ARMTemplateForFactory.json"
# Path conversion may interfere

Solution:

# Disable conversion for PowerShell calls
MSYS_NO_PATHCONV=1 pwsh ./PrePostDeploymentScript.Ver2.ps1 -armTemplate "./ARMTemplate/ARMTemplateForFactory.json"

ARM Template Paths

Problem:

# Azure CLI deployment from Git Bash
az deployment group create \
  --resource-group myRG \
  --template-file ARMTemplate/ARMTemplateForFactory.json  # Path may get converted

Solution:

# Use relative paths with ./ prefix or absolute Windows paths
export MSYS_NO_PATHCONV=1
az deployment group create \
  --resource-group myRG \
  --template-file ./ARMTemplate/ARMTemplateForFactory.json

Shell Detection Patterns

Bash Shell Detection

#!/usr/bin/env bash

# Method 1: Check $MSYSTEM (Git Bash/MSYS2 specific)
if [ -n "$MSYSTEM" ]; then
  echo "Running in Git Bash/MinGW ($MSYSTEM)"
  export MSYS_NO_PATHCONV=1
fi

# Method 2: Check uname -s (more portable)
case "$(uname -s)" in
  MINGW64*|MINGW32*|MSYS*)
    echo "Git Bash detected"
    export MSYS_NO_PATHCONV=1
    ;;
  Linux*)
    if grep -q Microsoft /proc/version 2>/dev/null; then
      echo "WSL detected"
    else
      echo "Native Linux"
    fi
    ;;
  Darwin*)
    echo "macOS"
    ;;
esac

# Method 3: Check $OSTYPE (bash-specific)
case "$OSTYPE" in
  msys*)
    echo "Git Bash/MSYS"
    export MSYS_NO_PATHCONV=1
    ;;
  linux-gnu*)
    echo "Linux"
    ;;
  darwin*)
    echo "macOS"
    ;;
esac

Node.js Shell Detection

// detect-shell.js - For use in npm scripts or Node tools
function detectShell() {
  const env = process.env;

  // Git Bash/MinGW (MOST RELIABLE)
  if (env.MSYSTEM) {
    return {
      type: 'mingw',
      subsystem: env.MSYSTEM,  // MINGW64, MINGW32, or MSYS
      needsPathFix: true
    };
  }

  // WSL
  if (env.WSL_DISTRO_NAME) {
    return {
      type: 'wsl',
      distro: env.WSL_DISTRO_NAME,
      needsPathFix: false
    };
  }

  // PowerShell (3+ paths in PSModulePath)
  if (env.PSModulePath?.split(';').length >= 3) {
    return {
      type: 'powershell',
      needsPathFix: false
    };
  }

  // CMD
  if (process.platform === 'win32' && env.PROMPT === '$P$G') {
    return {
      type: 'cmd',
      needsPathFix: false
    };
  }

  // Cygwin
  if (env.TERM === 'cygwin') {
    return {
      type: 'cygwin',
      needsPathFix: true
    };
  }

  // Unix shells
  if (env.SHELL?.includes('bash')) {
    return { type: 'bash', needsPathFix: false };
  }
  if (env.SHELL?.includes('zsh')) {
    return { type: 'zsh', needsPathFix: false };
  }

  return {
    type: 'unknown',
    platform: process.platform,
    needsPathFix: false
  };
}

// Usage
const shell = detectShell();
console.log(`Detected shell: ${shell.type}`);

if (shell.needsPathFix) {
  process.env.MSYS_NO_PATHCONV = '1';
  console.log('Path conversion disabled for Git Bash compatibility');
}

module.exports = { detectShell };

PowerShell Detection

# Detect PowerShell edition and version
function Get-ShellInfo {
  $info = @{
    Edition = $PSVersionTable.PSEdition
    Version = $PSVersionTable.PSVersion
    OS = $PSVersionTable.OS
    Platform = $PSVersionTable.Platform
  }

  if ($info.Edition -eq 'Core') {
    Write-Host "PowerShell Core (pwsh) - Cross-platform compatible" -ForegroundColor Green
    $info.CrossPlatform = $true
  } else {
    Write-Host "Windows PowerShell - Windows only" -ForegroundColor Yellow
    $info.CrossPlatform = $false
  }

  return $info
}

$shellInfo = Get-ShellInfo

CI/CD Pipeline Patterns

Local Development Scripts

validate-adf.sh (Git Bash compatible):

#!/usr/bin/env bash
set -e

# Detect and handle Git Bash
if [ -n "$MSYSTEM" ]; then
  export MSYS_NO_PATHCONV=1
  echo "🔧 Git Bash detected - path conversion disabled"
fi

# Configuration
ADF_ROOT="./adf-resources"
FACTORY_ID="/subscriptions/${AZURE_SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}/providers/Microsoft.DataFactory/factories/${FACTORY_NAME}"

# Validate ADF resources
echo "📋 Validating ADF resources..."
npm run build validate "$ADF_ROOT" "$FACTORY_ID"

# Generate ARM templates
echo "📦 Generating ARM templates..."
npm run build export "$ADF_ROOT" "$FACTORY_ID" "ARMTemplate"

echo "✅ Validation complete"

deploy-adf.sh (Cross-platform):

#!/usr/bin/env bash
set -e

# Detect shell
detect_shell() {
  if [ -n "$MSYSTEM" ]; then echo "git-bash"
  elif [ -n "$WSL_DISTRO_NAME" ]; then echo "wsl"
  elif [[ "$OSTYPE" == "darwin"* ]]; then echo "macos"
  else echo "linux"
  fi
}

SHELL_TYPE=$(detect_shell)
echo "🖥️  Detected shell: $SHELL_TYPE"

# Handle Git Bash
if [ "$SHELL_TYPE" = "git-bash" ]; then
  export MSYS_NO_PATHCONV=1
fi

# Download PrePostDeploymentScript
curl -sLo PrePostDeploymentScript.Ver2.ps1 \
  https://raw.githubusercontent.com/Azure/Azure-DataFactory/main/SamplesV2/ContinuousIntegrationAndDelivery/PrePostDeploymentScript.Ver2.ps1

# Stop triggers
echo "⏸️  Stopping triggers..."
MSYS_NO_PATHCONV=1 pwsh ./PrePostDeploymentScript.Ver2.ps1 \
  -armTemplate "./ARMTemplate/ARMTemplateForFactory.json" \
  -ResourceGroupName "$RESOURCE_GROUP" \
  -DataFactoryName "$FACTORY_NAME" \
  -predeployment $true \
  -deleteDeployment $false

# Deploy ARM template
echo "🚀 Deploying ARM template..."
az deployment group create \
  --resource-group "$RESOURCE_GROUP" \
  --template-file ./ARMTemplate/ARMTemplateForFactory.json \
  --parameters ./ARMTemplate/ARMTemplateParametersForFactory.json \
  --parameters factoryName="$FACTORY_NAME"

# Start triggers
echo "▶️  Starting triggers..."
MSYS_NO_PATHCONV=1 pwsh ./PrePostDeploymentScript.Ver2.ps1 \
  -armTemplate "./ARMTemplate/ARMTemplateForFactory.json" \
  -ResourceGroupName "$RESOURCE_GROUP" \
  -DataFactoryName "$FACTORY_NAME" \
  -predeployment $false \
  -deleteDeployment $true

echo "✅ Deployment complete"

package.json with Shell Detection

{
  "scripts": {
    "prevalidate": "node scripts/detect-shell.js",
    "validate": "node node_modules/@microsoft/azure-data-factory-utilities/lib/index validate",
    "prebuild": "node scripts/detect-shell.js",
    "build": "node node_modules/@microsoft/azure-data-factory-utilities/lib/index export"
  },
  "dependencies": {
    "@microsoft/azure-data-factory-utilities": "^1.0.3"
  }
}

scripts/detect-shell.js :

const detectShell = () => {
  if (process.env.MSYSTEM) {
    console.log('🔧 Git Bash detected - disabling path conversion');
    process.env.MSYS_NO_PATHCONV = '1';
    return 'git-bash';
  }
  console.log(`🖥️  Shell: ${process.platform}`);
  return process.platform;
};

detectShell();

Common Issues and Solutions

Issue 1: npm build validate fails with "Resource not found"

Symptom:

npm run build validate ./adf-resources /subscriptions/abc/...
# Error: Resource '/subscriptions/C:/Program Files/Git/subscriptions/abc/...' not found

Cause: Git Bash converted the factory ID path

Solution:

export MSYS_NO_PATHCONV=1
npm run build validate ./adf-resources /subscriptions/abc/...

Issue 2: PowerShell script paths incorrect

Symptom:

pwsh PrePostDeploymentScript.Ver2.ps1 -armTemplate "./ARM/template.json"
# Error: Cannot find path 'C:/Program Files/Git/ARM/template.json'

Cause: Git Bash converted the ARM template path

Solution:

MSYS_NO_PATHCONV=1 pwsh PrePostDeploymentScript.Ver2.ps1 -armTemplate "./ARM/template.json"

Issue 3: Azure CLI template-file parameter fails

Symptom:

az deployment group create --template-file ./ARMTemplate/file.json
# Error: Template file not found

Cause: Path conversion interfering with Azure CLI

Solution:

export MSYS_NO_PATHCONV=1
az deployment group create --template-file ./ARMTemplate/file.json

Best Practices

1. Set MSYS_NO_PATHCONV in .bashrc

# Add to ~/.bashrc for Git Bash
if [ -n "$MSYSTEM" ]; then
  export MSYS_NO_PATHCONV=1
fi

2. Create Wrapper Scripts

# adf-cli.sh - Wrapper for ADF npm commands
#!/usr/bin/env bash
export MSYS_NO_PATHCONV=1
npm run build "$@"

3. Use Relative Paths with ./

# Prefer this (less likely to trigger conversion)
./ARMTemplate/ARMTemplateForFactory.json

# Over this
ARMTemplate/ARMTemplateForFactory.json

4. Document Shell Requirements

# README.md

## Development Environment

### Windows Users
- Use Git Bash or PowerShell Core (pwsh)
- Git Bash users: Add `export MSYS_NO_PATHCONV=1` to .bashrc
- Alternative: Use WSL2 for native Linux environment

5. Test on Multiple Shells

# Test matrix for Windows developers
- Git Bash (MINGW64)
- PowerShell Core 7+
- WSL2 (Ubuntu/Debian)
- cmd.exe (if applicable)

Quick Reference

Environment Variable	Purpose	Value
`MSYS_NO_PATHCONV`	Disable all path conversion (Git for Windows)	`1`
`MSYS2_ARG_CONV_EXCL`	Exclude specific arguments from conversion (MSYS2)	`*` or patterns
`MSYSTEM`	Current MSYS subsystem	`MINGW64`, `MINGW32`,

Resources

Summary

Key Takeaways:

Git Bash automatically converts Unix-style paths to Windows paths
Use export MSYS_NO_PATHCONV=1 to disable conversion
Detect shell environment using $MSYSTEM variable
Test CI/CD scripts on all shells used by your team
Use PowerShell Core (pwsh) for cross-platform scripts
Add shell detection to local development scripts

Weekly Installs

Repository

josiahsiegel/cl…ketplace

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

claude-code44

gemini-cli42

opencode41

codex39

cursor38

antigravity36

解决Azure Data Factory在Windows Git Bash中的路径兼容性问题 | 开发运维指南

🇨🇳中文介绍

Azure Data Factory 的 Windows 和 Git Bash 兼容性

概述

Git Bash 路径转换行为

自动路径转换

相关 Skills

ADF 特定的路径问题

npm 构建命令

PowerShell 脚本

ARM 模板路径

Shell 检测模式

Bash Shell 检测

Node.js Shell 检测

PowerShell 检测

CI/CD 流水线模式

本地开发脚本

带 Shell 检测的 package.json

常见问题及解决方案

问题 1：npm build validate 失败并显示"未找到资源"

问题 2：PowerShell 脚本路径不正确

问题 3：Azure CLI template-file 参数失败

最佳实践

1. 在 .bashrc 中设置 MSYS_NO_PATHCONV

2. 创建包装脚本

3. 使用带 ./ 的相对路径

4. 记录 Shell 要求

5. 在多个 Shell 上测试

快速参考

资源

总结

🇺🇸English

Windows & Git Bash Compatibility for Azure Data Factory

Overview

Git Bash Path Conversion Behavior

Automatic Path Conversion

ADF-Specific Path Issues

npm Build Commands

PowerShell Scripts

ARM Template Paths

Shell Detection Patterns

Bash Shell Detection

Node.js Shell Detection

PowerShell Detection

CI/CD Pipeline Patterns

Local Development Scripts

package.json with Shell Detection

Common Issues and Solutions

Issue 1: npm build validate fails with "Resource not found"

Issue 2: PowerShell script paths incorrect

Issue 3: Azure CLI template-file parameter fails

Best Practices

1. Set MSYS_NO_PATHCONV in .bashrc

2. Create Wrapper Scripts

3. Use Relative Paths with ./

4. Document Shell Requirements

5. Test on Multiple Shells

Quick Reference

Resources

Summary

最新 Skills