Skip to main content
skill CX Codex

windows-git-bash-compatibility — Claude Code skill

windows-git-bash-compatibility fixes path conversion conflicts and shell issues when running Azure Data Factory tooling inside Git Bash on Windows.

MIT 165 installs ★ 66 updated 2026-06-18

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-git-bash-compatibility -a claude-code
Open on GitHub

What windows-git-bash-compatibility does

Git Bash on Windows translates POSIX path arguments into Windows file paths by default. When running Azure Data Factory commands, this behavior mangles Azure subscription identifiers and factory resource paths passed to CLI tools.

This skill gives your coding agent patterns to disable translation using MSYS_NO_PATHCONV=1. It provides safe templates for running npm run build validate, exporting ARM templates, and invoking PowerShell deployment scripts directly from bash sessions.

It includes environment detection snippets for Bash and Node.js runtime scripts. Without disabling MSYS path translation, standard calls to az deployment group create fail whenever resource IDs begin with a slash.

What it helps with

  • prevent path corruption when invoking ADF CLI tools
  • pass uncorrupted ARM template paths to Azure CLI
  • execute PowerShell deployment scripts from Git Bash
  • detect MinGW and Git Bash environments in build scripts

Example prompts for the agent

  • Fix the path translation errors when running ADF validation inside Git Bash.
  • Show how to pass ARM template parameters to Azure CLI from Windows bash.
  • Add Git Bash shell detection to my npm deployment script.

How to install windows-git-bash-compatibility

1Skills CLI (Vercel)

npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-git-bash-compatibility -a claude-code

2Manually: put the files in place

~/.claude/skills/windows-git-bash-compatibility/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/windows-git-bash-compatibility/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about windows-git-bash-compatibility

How to install windows-git-bash-compatibility in Claude Code?

Run npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-git-bash-compatibility -a claude-code in your terminal.

What does windows-git-bash-compatibility do?

It guides the agent on managing path conversion and environment flags for Azure Data Factory tools running on Windows shells.

Which environment variable resolves the path conversion problem?

Setting MSYS_NO_PATHCONV=1 stops MinGW from altering Azure resource IDs and slash-prefixed arguments.

Source text

SKILL.md · MIT
---
name: windows-git-bash-compatibility
description: |
  Windows and Git Bash compatibility for ADF tooling.
  PROACTIVELY activate for: (1) MSYS_NO_PATHCONV usage with ADF CLI tools, (2) Git Bash path conversion when running ADF npm builds, (3) PowerShell scripts called from Git Bash for ADF, (4) Azure CLI from Git Bash on Windows for ADF deployments, (5) ARM template export issues on Windows, (6) ADF utilities npm package on Windows, (7) line-ending issues in JSON pipeline definitions.
  Provides: MSYS env-var recipes, npm-on-Windows fixes, PowerShell-from-bash patterns, and Azure CLI auth on Git Bash.
---

# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# Calling PowerShell scripts from Git Bash
pwsh ./PrePostDeploymentScript.Ver2.ps1 -armTemplate "./ARMTemplate/ARMTemplateForFactory.json"
# Path conversion may interfere
```

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

### ARM Template Paths

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

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

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

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

```powershell
# 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):
```bash
#!/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):
```bash
#!/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

```json
{
  "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**:
```javascript
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:**
```bash
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:**
```bash
export MSYS_NO_PATHCONV=1
npm run build validate ./adf-resources /subscriptions/abc/...
```

### Issue 2: PowerShell script paths incorrect

**Symptom:**
```bash
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:**
```bash
MSYS_NO_PATHCONV=1 pwsh PrePostDeploymentScript.Ver2.ps1 -armTemplate "./ARM/template.json"
```

### Issue 3: Azure CLI template-file parameter fails

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

**Cause:** Path conversion interfering with Azure CLI

**Solution:**
```bash
export MSYS_NO_PATHCONV=1
az deployment group create --template-file ./ARMTemplate/file.json
```

## Best Practices

### 1. Set MSYS_NO_PATHCONV in .bashrc

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

### 2. Create Wrapper Scripts

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

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

# Over this
ARMTemplate/ARMTemplateForFactory.json
```

### 4. Document Shell Requirements

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

```bash
# 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`, `MSYS` |
| `WSL_DISTRO_NAME` | WSL distribution name | `Ubuntu`, `Debian`, etc. |

## Resources

- [Git for Windows Path Conversion](https://github.com/git-for-windows/git/wiki/FAQ#path-conversion)
- [MSYS2 Path Conversion](https://www.msys2.org/docs/filesystem-paths/)
- [Azure CLI on Windows](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-windows)
- [PowerShell Core](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell)

## Summary

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

© JosiahSiegel · MIT · JosiahSiegel/claude-plugin-marketplace

Similar skills

All skills for Cloud: AWS, Azure, GCP →

From the same set96

The whole set →
azure-openai-2025 azure-openai-2025 — a reference skill for Azure OpenAI Service: the 2025 model lineup, deployment through az, SKU and quota notes, Python SDK recipes. CX Codex +1 167installs github-actions-2025 github-actions-2025 guides your agent through modern GitHub Actions features, including 1 vCPU runners, immutable releases, and Node24 migrations. CX Codex +1 166installs defender-for-devops defender-for-devops is a Claude Code skill for adding security checks to Azure Pipelines. It activates for MSDO setup, code and dependency scans, container checks, and IaC analysis. CX Codex +1 166installs docker-watch-mode-2025 docker-watch-mode-2025 sets up Compose watch rules so source edits land in the running container, while dependency manifests trigger a rebuild. CX Codex +1 166installs windows-git-bash-testing windows-git-bash-testing fixes Vitest, Playwright and MSW failures that only show up on Windows and in Git Bash: rewritten arguments, snapshot line endings, missing browsers. CX Codex +1 164installs git-2025-features git-2025-features is a skill for Claude Code and other platforms with reference for Git 2.48–2.49 features and modern workflows. The agent uses it for reftables, sparse-checkout, partial clone and worktrees. CX Codex +1 164installs adf-master adf-master configures Azure Data Factory CI/CD pipelines, handles ARM template exports, and manages triggers during deployments. CX Codex +1 164installs azure-sql-optimization azure-sql-optimization — a skill for tuning Azure SQL Database: tier choice, automatic tuning, Hyperscale, Serverless and elastic pools. CX Codex +1 164installs

Project sponsors

Companies that keep this analytics open