К основному содержанию
скилл CX Codex

ado-windows-git-bash-compatibility — скилл для Claude Code

Скилл ado-windows-git-bash-compatibility для Claude и других агентов: разбирает падения пайплайнов Azure DevOps на Windows-агентах и в Git Bash — конвертацию путей, выбор shell-задачи, переводы строк.

MIT 159 установок ★ 66 обновлён 2026-06-18

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add JosiahSiegel/claude-plugin-marketplace --skill ado-windows-git-bash-compatibility -a claude-code
Открыть на GitHub

Что делает ado-windows-git-bash-compatibility

Скилл включается, когда пайплайн в Azure Pipelines проходит на Linux и валится на Windows-агенте. Внутри разбор конвертации путей в MINGW и MSYS, выбор задачи shell (bash@3, pwsh@2, powershell@2), переводы строк CRLF и LF в закоммиченных скриптах, Docker на Windows-агентах, ограничения UNC и длинных путей.

ОС скилл советует определять тремя способами: по $OSTYPE, через uname -s и по переменной $(Agent.OS). Пути переводятся через cygpath -u, cygpath -w и cygpath -m. Когда ломаются отдельные аргументы, а не весь скрипт, берётся MSYS2_ARG_CONV_EXCL со списком префиксов вроде --config=;/p:.

Microsoft не советует настраивать агент на mintty-оболочках вроде git-bash, а Windows-агент по умолчанию использует Git из своего комплекта; переопределить это можно через System.PreferGitFromPath=true. Флаги вида /p:Configuration=Release в Git Bash без MSYS_NO_PATHCONV искажаются: MINGW принимает их за пути.

Какие задачи решает

  • починить пайплайн, который зелёный на Linux и падает на Windows-агенте
  • выбрать между задачами bash@3, pwsh@2 и powershell@2
  • отключить автоматическую конвертацию путей через MSYS_NO_PATHCONV
  • перевести путь между Windows и Unix через cygpath
  • убрать CRLF из скриптов, лежащих в репозитории

Примеры запросов агенту

  • Пайплайн проходит на ubuntu-latest, а на windows-2025 падает на cd $(System.DefaultWorkingDirectory) — найди причину.
  • Добавь в azure-pipelines.yml определение ОС через uname -s и выставь MSYS_NO_PATHCONV для MINGW.
  • build.sh приезжает с CRLF, и bash на нём спотыкается. Как исправить?

Как установить ado-windows-git-bash-compatibility

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/ado-windows-git-bash-compatibility/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об ado-windows-git-bash-compatibility

Как установить ado-windows-git-bash-compatibility в Claude Code?

Выполните npx skills add JosiahSiegel/claude-plugin-marketplace --skill ado-windows-git-bash-compatibility -a claude-code. Файл скилла окажется по пути ~/.claude/skills/ado-windows-git-bash-compatibility/SKILL.md.

Что делает этот скилл?

Разбирает несовместимости Azure Pipelines с Windows-агентами и Git Bash: конвертацию путей в MINGW, выбор задачи shell, переводы строк в скриптах, Docker и ограничения длинных путей.

Чем MSYS_NO_PATHCONV отличается от MSYS2_ARG_CONV_EXCL?

Первый выключает всю автоматическую конвертацию путей в скрипте. Второй исключает только заданные префиксы аргументов, например --config=;/p:.

Исходный текст

SKILL.md · MIT
---
name: ado-windows-git-bash-compatibility
description: |
  Windows and Git Bash compatibility for Azure Pipelines.
  PROACTIVELY activate for: (1) pipelines that pass on Linux but fail on Windows agents, (2) path conversion issues in pipeline scripts (MSYS, MINGW), (3) shell detection (bash@3, pwsh@2, powershell@2 task selection), (4) MSYS_NO_PATHCONV and MSYS2_ARG_CONV_EXCL workarounds, (5) Windows self-hosted agent configuration, (6) cross-platform script patterns, (7) line-ending issues (CRLF vs LF) in checked-in scripts, (8) Docker on Windows agents, (9) UNC and long-path limitations.
  Provides: shell-task selection matrix, path-conversion env-var recipes, line-ending fixes, and a Windows-specific pipeline troubleshooting playbook.
---

# Azure Pipelines: Windows & Git Bash Compatibility

## Overview

Azure Pipelines frequently run on Windows agents, and teams often use Git Bash for scripting. This creates path conversion and shell compatibility challenges that can cause pipeline failures. This guide provides comprehensive solutions for Windows/Git Bash integration in Azure DevOps pipelines.

## Critical Windows Agent Facts

### Git Bash Integration

**Microsoft's Official Position:**
- Microsoft advises **avoiding mintty-based shells** (like git-bash) for agent configuration
- mintty is not fully compatible with native Windows Input/Output API
- However, Git Bash tasks in pipelines are widely used and supported

**Git Version Management:**
- Windows agents use Git bundled with agent software by default
- Microsoft recommends using bundled Git version
- Override available via `System.PreferGitFromPath=true`

**Git Bash Location on Windows Agents:**
```text
C:\Program Files (x86)\Git\usr\bin\bash.exe
C:\Program Files\Git\usr\bin\bash.exe
```

## Path Conversion Issues in Pipelines

### The Core Problem

When using Bash tasks on Windows agents, Azure DevOps variables return Windows-style paths, but Git Bash (MINGW) performs automatic path conversion that can cause issues.

### Common Failure Patterns

#### Issue 1: Backslash Escape in Bash
```yaml
# ❌ FAILS - Backslashes treated as escape characters
- bash: |
    cd $(System.DefaultWorkingDirectory)  # d:\a\s\1 becomes d:as1
```

**Solution:**
```yaml
# ✅ CORRECT - Use forward slashes or variable properly
- bash: |
    cd "$BUILD_SOURCESDIRECTORY"
    # Or use PWD variable which is already set correctly
    echo "Working in: $PWD"
```

#### Issue 2: Path Variables in Arguments
```yaml
# ❌ FAILS - MINGW converts /d /s style arguments
- bash: |
    my-tool /d $(Build.SourcesDirectory)
```

**Solution:**
```yaml
# ✅ CORRECT - Use double slashes or environment variable
- bash: |
    export MSYS_NO_PATHCONV=1
    my-tool /d $(Build.SourcesDirectory)
    unset MSYS_NO_PATHCONV
```

#### Issue 3: Colon-Separated Path Lists
```yaml
# ❌ FAILS - MINGW converts colon-separated Windows paths
- bash: |
    export PATH="/usr/bin:$(Agent.ToolsDirectory)"
```

**Solution:**
```yaml
# ✅ CORRECT - Use semicolon for Windows or convert properly
- bash: |
    # For Windows-style paths
    export PATH="/usr/bin;$(Agent.ToolsDirectory)"
```

## Shell Detection in Pipeline Scripts

### Method 1: Using $OSTYPE (Bash-Specific)

```yaml
- bash: |
    case "$OSTYPE" in
      linux-gnu*)
        echo "Running on Linux agent"
        BUILD_PATH="$(Build.SourcesDirectory)"
        ;;
      darwin*)
        echo "Running on macOS agent"
        BUILD_PATH="$(Build.SourcesDirectory)"
        ;;
      msys*|mingw*|cygwin*)
        echo "Running on Windows agent with Git Bash"
        # Windows paths already work in MINGW, but may need conversion
        BUILD_PATH="$(Build.SourcesDirectory)"
        export MSYS_NO_PATHCONV=1
        ;;
      *)
        echo "Unknown OS: $OSTYPE"
        BUILD_PATH="$(Build.SourcesDirectory)"
        ;;
    esac

    echo "Build path: $BUILD_PATH"
    cd "$BUILD_PATH"
  displayName: 'Cross-platform path handling'
```

### Method 2: Using uname (Most Portable)

```yaml
- bash: |
    OS_TYPE=$(uname -s)

    case "$OS_TYPE" in
      Darwin*)
        echo "macOS agent detected"
        ;;
      Linux*)
        echo "Linux agent detected"
        # Check if WSL
        if grep -qi microsoft /proc/version 2>/dev/null; then
          echo "Running in WSL"
        fi
        ;;
      MINGW64*|MINGW32*)
        echo "Git Bash on Windows detected"
        export MSYS_NO_PATHCONV=1
        ;;
      CYGWIN*)
        echo "Cygwin on Windows detected"
        ;;
      MSYS_NT*)
        echo "MSYS on Windows detected"
        export MSYS_NO_PATHCONV=1
        ;;
      *)
        echo "Unknown OS: $OS_TYPE"
        ;;
    esac
  displayName: 'Detect shell environment'
```

### Method 3: Using Agent.OS (Azure Pipelines Variable)

```yaml
- bash: |
    if [ "$(Agent.OS)" = "Windows_NT" ]; then
      echo "Windows agent - applying MINGW path handling"
      export MSYS_NO_PATHCONV=1
    elif [ "$(Agent.OS)" = "Linux" ]; then
      echo "Linux agent"
    elif [ "$(Agent.OS)" = "Darwin" ]; then
      echo "macOS agent"
    fi
  displayName: 'Agent-specific configuration'
```

## Path Conversion Control

### MSYS_NO_PATHCONV (Primary Method)

Disables ALL automatic path conversion in MINGW/Git Bash:

```yaml
- bash: |
    # Disable path conversion for this script
    export MSYS_NO_PATHCONV=1

    # Now Windows paths work as-is
    dotnet build /p:Configuration=Release
    docker run -v "$(Build.SourcesDirectory):/workspace" myimage

    # Optionally re-enable
    unset MSYS_NO_PATHCONV
  displayName: 'Build with path conversion disabled'
```

### MSYS2_ARG_CONV_EXCL (Selective Exclusion)

Exclude specific argument patterns from conversion:

```yaml
- bash: |
    # Exclude specific prefixes from conversion
    export MSYS2_ARG_CONV_EXCL="--config=;/p:"

    dotnet build /p:Configuration=Release --config=$(Build.SourcesDirectory)/app.config
  displayName: 'Selective path conversion'
```

### Manual Conversion with cygpath

Convert between Windows and Unix paths explicitly:

```yaml
- bash: |
    # Convert Windows path to Unix
    UNIX_PATH=$(cygpath -u "$(Build.SourcesDirectory)")
    echo "Unix path: $UNIX_PATH"

    # Convert Unix path to Windows
    WINDOWS_PATH=$(cygpath -w "$PWD")
    echo "Windows path: $WINDOWS_PATH"

    # Mixed format (forward slashes with drive letter)
    MIXED_PATH=$(cygpath -m "$(Build.SourcesDirectory)")
    echo "Mixed path: $MIXED_PATH"
  displayName: 'Path conversion examples'
```

## Cross-Platform Pipeline Patterns

### Pattern 1: Platform-Specific Steps with Conditions

```yaml
jobs:
  - job: CrossPlatformBuild
    strategy:
      matrix:
        Linux:
          imageName: 'ubuntu-24.04'
          osType: 'Linux'
        Windows:
          imageName: 'windows-2025'
          osType: 'Windows_NT'
        macOS:
          imageName: 'macOS-15'
          osType: 'Darwin'
    pool:
      vmImage: $(imageName)

    steps:
      # Windows-specific setup
      - bash: |
          export MSYS_NO_PATHCONV=1
          echo "Windows Git Bash configuration applied"
        condition: eq(variables['Agent.OS'], 'Windows_NT')
        displayName: 'Windows Git Bash setup'

      # Cross-platform build
      - bash: |
          echo "Building on: $(Agent.OS)"
          cd "$(Build.SourcesDirectory)"
          npm install
          npm run build
        displayName: 'Cross-platform build'
```

### Pattern 2: Reusable Template with Platform Detection

```yaml
# File: templates/cross-platform-script.yml
parameters:
  - name: script
    type: string

steps:
  - bash: |
      # Auto-detect Windows and apply MSYS configuration
      if [ "$(Agent.OS)" = "Windows_NT" ]; then
        export MSYS_NO_PATHCONV=1
      fi

      # Run provided script
      ${{ parameters.script }}
    displayName: 'Cross-platform script execution'

# Usage in main pipeline:
steps:
  - template: templates/cross-platform-script.yml
    parameters:
      script: |
        dotnet build /p:Configuration=Release
        dotnet test --no-build
```

### Pattern 3: PowerShell for Windows, Bash for Unix

```yaml
- pwsh: |
    Write-Host "Building on Windows with PowerShell"
    dotnet build /p:Configuration=Release
  condition: eq(variables['Agent.OS'], 'Windows_NT')
  displayName: 'Windows build (PowerShell)'

- bash: |
    echo "Building on Unix with Bash"
    dotnet build -p:Configuration=Release
  condition: ne(variables['Agent.OS'], 'Windows_NT')
  displayName: 'Unix build (Bash)'
```

## Azure DevOps CLI on Windows Agents

### Common CLI Path Issues

```yaml
# ❌ FAILS - Windows paths in bash arguments
- bash: |
    az pipelines run --id 123 --variables sourceDir=$(Build.SourcesDirectory)
```

**Solution:**
```yaml
# ✅ CORRECT - Use MSYS_NO_PATHCONV or proper quoting
- bash: |
    export MSYS_NO_PATHCONV=1
    az pipelines run --id 123 --variables sourceDir="$(Build.SourcesDirectory)"
```

### Repository Operations with Paths

```yaml
- bash: |
    # Configure Git to handle Windows paths correctly
    git config --global core.autocrlf true
    git config --global core.safecrlf false

    # Clone with proper path handling
    export MSYS_NO_PATHCONV=1
    az repos pr create \
      --repository myrepo \
      --source-branch feature/new \
      --target-branch main
  displayName: 'Git operations on Windows agent'
  condition: eq(variables['Agent.OS'], 'Windows_NT')
```

## Agent Configuration Best Practices

### Configure Git for Windows Agents

```yaml
- bash: |
    # Recommended Git configuration for Windows agents
    git config --global core.autocrlf true
    git config --global core.longpaths true
    git config --global core.symlinks false

    # Show configuration
    git config --list | grep core
  displayName: 'Configure Git for Windows'
  condition: eq(variables['Agent.OS'], 'Windows_NT')
```

### Use System.PreferGitFromPath

```yaml
# Use system Git instead of agent-bundled Git
variables:
  System.PreferGitFromPath: true

steps:
  - bash: |
      git --version
      which git
    displayName: 'Check Git version'
```

### Agent .env Configuration

For self-hosted Windows agents, create `.env` file in agent root:

```bash
# File: agent/.env
System.PreferGitFromPath=true
MSYS_NO_PATHCONV=1
```

## Troubleshooting Windows Pipeline Failures

### Diagnostic Script

```yaml
- bash: |
    echo "=== Environment Diagnostics ==="
    echo "Agent.OS: $(Agent.OS)"
    echo "Agent.OSArchitecture: $(Agent.OSArchitecture)"
    echo "System.DefaultWorkingDirectory: $(System.DefaultWorkingDirectory)"
    echo "Build.SourcesDirectory: $(Build.SourcesDirectory)"
    echo ""

    echo "=== Shell Detection ==="
    echo "OSTYPE: $OSTYPE"
    echo "MSYSTEM: $MSYSTEM"
    uname -a
    echo ""

    echo "=== Path Information ==="
    echo "PWD: $PWD"
    echo "HOME: $HOME"
    echo "PATH: $PATH"
    echo ""

    echo "=== Git Configuration ==="
    git --version
    which git
    git config --list | grep core
    echo ""

    echo "=== Path Conversion Test ==="
    echo "Windows-style: $(Build.SourcesDirectory)"
    if command -v cygpath &> /dev/null; then
      echo "Unix-style: $(cygpath -u "$(Build.SourcesDirectory)")"
      echo "Mixed-style: $(cygpath -m "$(Build.SourcesDirectory)")"
    fi
  displayName: 'Windows agent diagnostics'
  condition: eq(variables['Agent.OS'], 'Windows_NT')
```

### Common Error Patterns and Fixes

#### Error: "No such file or directory"
```yaml
# Error: bash: line 1: d:as1: No such file or directory

# ❌ Problem: Backslashes removed
- bash: cd $(System.DefaultWorkingDirectory)

# ✅ Solution: Quote the variable
- bash: cd "$(System.DefaultWorkingDirectory)"
```

#### Error: "Invalid switch"
```yaml
# Error: Invalid switch - "/d"

# ❌ Problem: MINGW converts /d to Windows path
- bash: dotnet test /d:SonarQubeAnalysisPath=.

# ✅ Solution: Disable path conversion
- bash: |
    export MSYS_NO_PATHCONV=1
    dotnet test /d:SonarQubeAnalysisPath=.
```

#### Error: "Access denied" with spaces in path
```yaml
# Error: Access to path 'C:\Program' is denied

# ❌ Problem: Unquoted path with spaces
- bash: my-tool $(Agent.ToolsDirectory)/mytool

# ✅ Solution: Always quote paths
- bash: my-tool "$(Agent.ToolsDirectory)/mytool"
```

## Best Practices Summary

### Always Do
1. **Quote all path variables**: `"$(Build.SourcesDirectory)"`
2. **Use MSYS_NO_PATHCONV** for Windows-specific commands
3. **Detect platform** using `$(Agent.OS)` or `uname`
4. **Test on Windows agents** if targeting Windows deployments
5. **Use forward slashes** in paths when possible (Git Bash compatible)

### Never Do
1. ❌ Use unquoted paths: `cd $(Build.SourcesDirectory)`
2. ❌ Assume Bash = Linux (Windows has Git Bash)
3. ❌ Hardcode platform-specific paths
4. ❌ Mix PowerShell and Bash syntax in same script
5. ❌ Ignore MINGW path conversion in arguments

### Platform Detection Template

Use this at the start of complex cross-platform scripts:

```yaml
- bash: |
    #!/bin/bash
    set -euo pipefail

    # Detect platform and configure
    if [ "$(Agent.OS)" = "Windows_NT" ]; then
      echo "Windows agent detected"
      export MSYS_NO_PATHCONV=1
      PATH_SEP=";"
    else
      echo "Unix-like agent detected"
      PATH_SEP=":"
    fi

    # Your script logic here
    echo "Build directory: $(Build.SourcesDirectory)"
    cd "$(Build.SourcesDirectory)"

    # Platform-agnostic operations
    npm install
    npm run build
  displayName: 'Cross-platform build script'
```

## Additional Resources

- [Azure Pipelines Windows Agents](https://learn.microsoft.com/azure/devops/pipelines/agents/windows-agent)
- [Git for Windows Documentation](https://git-scm.com/docs)
- [MINGW Path Conversion](https://www.msys2.org/docs/filesystem-paths/)
- [Azure Pipelines Variables](https://learn.microsoft.com/azure/devops/pipelines/build/variables)

## Quick Reference Card

| Scenario | Solution |
|----------|----------|
| Bash script on Windows | Use `export MSYS_NO_PATHCONV=1` |
| Detect Windows agent | Check `$(Agent.OS)` = `Windows_NT` |
| Detect Git Bash | Check `uname -s` starts with `MINGW` |
| Convert Windows → Unix | `cygpath -u "C:\path"` |
| Convert Unix → Windows | `cygpath -w "/c/path"` |
| Quote paths with spaces | Always use `"$(variable)"` |
| Disable conversion for arg | `export MSYS2_ARG_CONV_EXCL="pattern"` |
| Check Git version | `git --version && which git` |
| Use system Git | Set `System.PreferGitFromPath: true` |
| Test path handling | Run diagnostic script above |

---

**When in doubt, use `MSYS_NO_PATHCONV=1` for Windows agents running Bash tasks.**

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

Похожие скиллы

Все скиллы по теме «DevOps и инфраструктура» →
windows-agent-shell Paweł Huryn Скилл windows-agent-shell для Claude Code помогает разбирать ошибки командной оболочки Windows: неверные пути, кавычки, кодировка и окончания строк. Активируется, когда вывод искажён или команда работает в одной среде, но ломается в другой. CX Codex +1 ★ 741звёзд репо azure-pipelines MicrosoftDocs Помогает настраивать и отлаживать Azure Pipelines. Разбирает YAML, агентов, секреты Key Vault и развёртывание в Azure. CX Codex +1 470установок windows-builder hashicorp Скилл windows-builder для Claude Code помогает собирать образы Windows через Packer. Он включается при подготовке AMI для AWS, образа Azure или шаблона VMware. CX Codex +1 2 900установок windows-vm obra Скилл windows-vm для Claude Code запускает и управляет headless-ВМ с Windows 11 в Docker и доступом по SSH. Выполняйте команды Windows прямо из кода. CX Codex +1 285установок dotnet-local-tools Aaronontheweb Скилл dotnet-local-tools объясняет, как вести локальные .NET CLI-инструменты через .config/dotnet-tools.json, чтобы у команды и в CI были одинаковые версии. CX Codex +1 560установок setup-ci-cd-pipeline davila7 Команда setup-ci-cd-pipeline настраивает CI/CD-пайплайн под GitHub Actions, GitLab CI, Azure Pipelines или Jenkins с тестами, проверками безопасности и сценариями деплоя. CX Codex +1 346установок

Из того же набора96

Весь набор →
git-2-49-features Скилл git-2-49-features подсказывает агенту, что появилось в Git 2.49: git backfill, path-walk API, сжатие через zlib-ng. Пригодится при переходе на новую версию. CX Codex +1 161установок process-substitution-fifos Скилл process-substitution-fifos для Claude Code помогает собирать Bash-пайплайны с process substitution, FIFO и coprocess. Передаёт данные между процессами без временных файлов. CX Codex +1 161установок fabric-onelake-2025 Скилл fabric-onelake-2025 для Claude по связке Azure Data Factory с Microsoft Fabric: коннекторы Lakehouse и Warehouse, шорткаты OneLake, вызов пайплайнов в обе стороны. CX Codex +1 161установок aks-automatic-2025 Скилл aks-automatic-2025 для работы с Azure Kubernetes Service в режиме Automatic. Подключает знания о Karpenter, автоскейлинге, workload identity и настройках кластеров 2025 года. CX Codex +1 161установок azure-emulators-2025 Скилл azure-emulators-2025 для Claude Code настраивает локальные эмуляторы Azure в Docker: Azurite, Cosmos DB и SQL Server 2025. Позволяет отлаживать и тестировать без подключения к облаку. CX Codex +1 159установок advanced-features-2025 Скилл advanced-features-2025 для Claude Code настраивает хуки, MCP-серверы и распространение плагинов на уровне репозитория. Описывает сборку плагинов Claude Code для команды. CX Codex +1 159установок plugin-master Скилл plugin-master помогает проектировать, валидировать и публиковать плагины для Claude Code со всеми манифестами, хуками и агентами. CX Codex +1 158установок deployment-stacks-2025 Скилл deployment-stacks-2025 помогает проектировать и разбирать Azure Deployment Stacks: защиту ресурсов, очистку при удалении из шаблона и команды Azure CLI. CX Codex +1 157установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой