docs: update $ARGUMENTS syntax for v2.1.19 breaking change + evaluation
Updated all documentation and examples to reflect Claude Code v2.1.19
breaking change: $ARGUMENTS.0 → $ARGUMENTS[0] (bracket syntax).
Changes:
- guide/ultimate-guide.md: 7 occurrences updated to bracket/shorthand syntax
- guide/cheatsheet.md: Command template updated
- Added migration note in § 6.2 Variable Interpolation
- Created migration scripts: migrate-arguments-syntax.{sh,ps1}
• Automated detection + conversion with backups
• Dry-run mode, cross-platform (macOS/Linux/Windows)
- Added formal evaluation: eval-claude-code-releases-jan2026.md
• Score: 5/5 (Critical - Integrate Immediately)
• Covers releases 2.1.0 to 2.1.19 (January 2026)
• Technical accuracy verified against GitHub CHANGELOG
Files:
- guide/ultimate-guide.md (+23 lines, 7 occurrences fixed)
- guide/cheatsheet.md (+1 line)
- examples/scripts/migrate-arguments-syntax.sh (+152 lines)
- examples/scripts/migrate-arguments-syntax.ps1 (+143 lines)
- docs/resource-evaluations/eval-claude-code-releases-jan2026.md (+273 lines)
- CHANGELOG.md (+12 lines, Unreleased section)
Total: +605 lines
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
08a2a4261f
commit
3a7671ac5e
6 changed files with 605 additions and 9 deletions
143
examples/scripts/migrate-arguments-syntax.ps1
Normal file
143
examples/scripts/migrate-arguments-syntax.ps1
Normal file
|
|
@ -0,0 +1,143 @@
|
|||
# Migration Script: $ARGUMENTS syntax (v2.1.19 breaking change)
|
||||
#
|
||||
# Purpose: Update custom commands from old dot notation to new bracket syntax
|
||||
# Breaking Change: $ARGUMENTS.0 → $ARGUMENTS[0] (introduced in Claude Code v2.1.19)
|
||||
#
|
||||
# Usage:
|
||||
# .\migrate-arguments-syntax.ps1 # Preview changes
|
||||
# .\migrate-arguments-syntax.ps1 -Apply # Apply changes
|
||||
#
|
||||
# Safety: Creates backups before modifying files
|
||||
|
||||
param(
|
||||
[switch]$Apply
|
||||
)
|
||||
|
||||
# Configuration
|
||||
$BackupDir = Join-Path $env:USERPROFILE ".claude\backups\arguments-migration-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
|
||||
|
||||
# Directories to scan
|
||||
$ScanDirs = @(
|
||||
(Join-Path $env:USERPROFILE ".claude\commands"),
|
||||
(Join-Path $env:USERPROFILE ".claude\skills"),
|
||||
".claude\commands",
|
||||
".claude\skills"
|
||||
)
|
||||
|
||||
Write-Host "╔═══════════════════════════════════════════════════════════╗" -ForegroundColor Blue
|
||||
Write-Host "║ Claude Code v2.1.19 - `$ARGUMENTS Syntax Migration ║" -ForegroundColor Blue
|
||||
Write-Host "╚═══════════════════════════════════════════════════════════╝" -ForegroundColor Blue
|
||||
Write-Host ""
|
||||
Write-Host "Breaking Change: " -NoNewline -ForegroundColor Yellow
|
||||
Write-Host "`$ARGUMENTS.N → `$ARGUMENTS[N]"
|
||||
Write-Host ""
|
||||
|
||||
# Check if any scan directories exist
|
||||
$foundDirs = $false
|
||||
foreach ($dir in $ScanDirs) {
|
||||
if (Test-Path $dir) {
|
||||
$foundDirs = $true
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
if (-not $foundDirs) {
|
||||
Write-Host "✓ No custom commands/skills directories found" -ForegroundColor Green
|
||||
Write-Host " Nothing to migrate."
|
||||
exit 0
|
||||
}
|
||||
|
||||
# Find files with old syntax
|
||||
Write-Host "Scanning for files with old `$ARGUMENTS.N syntax..."
|
||||
Write-Host ""
|
||||
|
||||
$affectedFiles = @()
|
||||
foreach ($dir in $ScanDirs) {
|
||||
if (-not (Test-Path $dir)) {
|
||||
continue
|
||||
}
|
||||
|
||||
# Find .md files with $ARGUMENTS.N pattern
|
||||
Get-ChildItem -Path $dir -Filter "*.md" -Recurse -ErrorAction SilentlyContinue | ForEach-Object {
|
||||
$content = Get-Content $_.FullName -Raw
|
||||
if ($content -match '\$ARGUMENTS\.[0-9]') {
|
||||
$affectedFiles += $_.FullName
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Report findings
|
||||
if ($affectedFiles.Count -eq 0) {
|
||||
Write-Host "✓ No files need migration" -ForegroundColor Green
|
||||
Write-Host " All custom commands already use the new syntax."
|
||||
exit 0
|
||||
}
|
||||
|
||||
Write-Host "Found $($affectedFiles.Count) file(s) with old syntax:" -ForegroundColor Yellow
|
||||
Write-Host ""
|
||||
|
||||
# Preview changes
|
||||
foreach ($file in $affectedFiles) {
|
||||
Write-Host "📄 $file" -ForegroundColor Blue
|
||||
|
||||
# Show occurrences
|
||||
$lineNum = 0
|
||||
Get-Content $file | ForEach-Object {
|
||||
$lineNum++
|
||||
if ($_ -match '\$ARGUMENTS\.[0-9]') {
|
||||
Write-Host " Line ${lineNum}: $_" -ForegroundColor Yellow
|
||||
}
|
||||
}
|
||||
Write-Host ""
|
||||
}
|
||||
|
||||
# Apply changes if requested
|
||||
if ($Apply) {
|
||||
Write-Host "Creating backups in: $BackupDir" -ForegroundColor Yellow
|
||||
New-Item -ItemType Directory -Path $BackupDir -Force | Out-Null
|
||||
|
||||
foreach ($file in $affectedFiles) {
|
||||
# Create backup
|
||||
$fileName = Split-Path $file -Leaf
|
||||
$backupPath = Join-Path $BackupDir $fileName
|
||||
Copy-Item $file $backupPath
|
||||
Write-Host "✓ Backed up: $fileName" -ForegroundColor Green
|
||||
|
||||
# Apply migration
|
||||
$content = Get-Content $file -Raw
|
||||
$newContent = $content -replace '\$ARGUMENTS\.([0-9])', '$ARGUMENTS[$1]'
|
||||
Set-Content -Path $file -Value $newContent -NoNewline
|
||||
|
||||
Write-Host "✓ Migrated: $file" -ForegroundColor Green
|
||||
}
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "╔═══════════════════════════════════════════════════════════╗" -ForegroundColor Green
|
||||
Write-Host "║ ✓ Migration Complete ║" -ForegroundColor Green
|
||||
Write-Host "╚═══════════════════════════════════════════════════════════╝" -ForegroundColor Green
|
||||
Write-Host ""
|
||||
Write-Host "Backups saved to: $BackupDir"
|
||||
Write-Host ""
|
||||
Write-Host "Changes applied:"
|
||||
Write-Host " • `$ARGUMENTS.0 → `$ARGUMENTS[0]"
|
||||
Write-Host " • `$ARGUMENTS.1 → `$ARGUMENTS[1]"
|
||||
Write-Host " • etc."
|
||||
Write-Host ""
|
||||
Write-Host "You can also use shorthand: `$0, `$1, `$2, ..."
|
||||
|
||||
} else {
|
||||
Write-Host "═══════════════════════════════════════════════════════════" -ForegroundColor Yellow
|
||||
Write-Host "DRY RUN MODE - No changes applied" -ForegroundColor Yellow
|
||||
Write-Host "═══════════════════════════════════════════════════════════" -ForegroundColor Yellow
|
||||
Write-Host ""
|
||||
Write-Host "To apply these changes, run:"
|
||||
Write-Host " .\migrate-arguments-syntax.ps1 -Apply" -ForegroundColor Green
|
||||
Write-Host ""
|
||||
Write-Host "This will:"
|
||||
Write-Host " 1. Create backups in %USERPROFILE%\.claude\backups\"
|
||||
Write-Host " 2. Update all files to new bracket syntax"
|
||||
Write-Host " 3. Preserve original files in backup directory"
|
||||
}
|
||||
|
||||
Write-Host ""
|
||||
Write-Host "Documentation: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md#2119"
|
||||
152
examples/scripts/migrate-arguments-syntax.sh
Executable file
152
examples/scripts/migrate-arguments-syntax.sh
Executable file
|
|
@ -0,0 +1,152 @@
|
|||
#!/bin/bash
|
||||
# Migration Script: $ARGUMENTS syntax (v2.1.19 breaking change)
|
||||
#
|
||||
# Purpose: Update custom commands from old dot notation to new bracket syntax
|
||||
# Breaking Change: $ARGUMENTS.0 → $ARGUMENTS[0] (introduced in Claude Code v2.1.19)
|
||||
#
|
||||
# Usage:
|
||||
# ./migrate-arguments-syntax.sh # Preview changes
|
||||
# ./migrate-arguments-syntax.sh --apply # Apply changes
|
||||
#
|
||||
# Safety: Creates backups before modifying files
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# Colors
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
# Configuration
|
||||
APPLY_CHANGES=false
|
||||
BACKUP_DIR="$HOME/.claude/backups/arguments-migration-$(date +%Y%m%d-%H%M%S)"
|
||||
|
||||
# Directories to scan
|
||||
SCAN_DIRS=(
|
||||
"$HOME/.claude/commands"
|
||||
"$HOME/.claude/skills"
|
||||
".claude/commands"
|
||||
".claude/skills"
|
||||
)
|
||||
|
||||
# Parse arguments
|
||||
if [[ "${1:-}" == "--apply" ]]; then
|
||||
APPLY_CHANGES=true
|
||||
fi
|
||||
|
||||
echo -e "${BLUE}╔═══════════════════════════════════════════════════════════╗${NC}"
|
||||
echo -e "${BLUE}║ Claude Code v2.1.19 - \$ARGUMENTS Syntax Migration ║${NC}"
|
||||
echo -e "${BLUE}╚═══════════════════════════════════════════════════════════╝${NC}"
|
||||
echo ""
|
||||
echo -e "${YELLOW}Breaking Change:${NC} \$ARGUMENTS.N → \$ARGUMENTS[N]"
|
||||
echo ""
|
||||
|
||||
# Check if any scan directories exist
|
||||
found_dirs=false
|
||||
for dir in "${SCAN_DIRS[@]}"; do
|
||||
if [[ -d "$dir" ]]; then
|
||||
found_dirs=true
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
if [[ "$found_dirs" == "false" ]]; then
|
||||
echo -e "${GREEN}✓ No custom commands/skills directories found${NC}"
|
||||
echo " Nothing to migrate."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Find files with old syntax
|
||||
echo "Scanning for files with old \$ARGUMENTS.N syntax..."
|
||||
echo ""
|
||||
|
||||
affected_files=()
|
||||
for dir in "${SCAN_DIRS[@]}"; do
|
||||
if [[ ! -d "$dir" ]]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
# Find .md files with $ARGUMENTS.N pattern
|
||||
while IFS= read -r file; do
|
||||
if grep -q '\$ARGUMENTS\.[0-9]' "$file"; then
|
||||
affected_files+=("$file")
|
||||
fi
|
||||
done < <(find "$dir" -type f -name "*.md" 2>/dev/null || true)
|
||||
done
|
||||
|
||||
# Report findings
|
||||
if [[ ${#affected_files[@]} -eq 0 ]]; then
|
||||
echo -e "${GREEN}✓ No files need migration${NC}"
|
||||
echo " All custom commands already use the new syntax."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo -e "${YELLOW}Found ${#affected_files[@]} file(s) with old syntax:${NC}"
|
||||
echo ""
|
||||
|
||||
# Preview changes
|
||||
for file in "${affected_files[@]}"; do
|
||||
echo -e "${BLUE}📄 $file${NC}"
|
||||
|
||||
# Show occurrences
|
||||
grep -n '\$ARGUMENTS\.[0-9]' "$file" | while IFS=: read -r line_num line_content; do
|
||||
echo -e " ${YELLOW}Line $line_num:${NC} $line_content"
|
||||
done
|
||||
echo ""
|
||||
done
|
||||
|
||||
# Apply changes if requested
|
||||
if [[ "$APPLY_CHANGES" == "true" ]]; then
|
||||
echo -e "${YELLOW}Creating backups in: $BACKUP_DIR${NC}"
|
||||
mkdir -p "$BACKUP_DIR"
|
||||
|
||||
for file in "${affected_files[@]}"; do
|
||||
# Create backup
|
||||
backup_path="$BACKUP_DIR/$(basename "$file")"
|
||||
cp "$file" "$backup_path"
|
||||
echo -e "${GREEN}✓${NC} Backed up: $(basename "$file")"
|
||||
|
||||
# Apply migration (macOS-compatible sed)
|
||||
if [[ "$OSTYPE" == "darwin"* ]]; then
|
||||
# macOS
|
||||
sed -i '' 's/\$ARGUMENTS\.\([0-9]\)/\$ARGUMENTS[\1]/g' "$file"
|
||||
else
|
||||
# Linux
|
||||
sed -i 's/\$ARGUMENTS\.\([0-9]\)/\$ARGUMENTS[\1]/g' "$file"
|
||||
fi
|
||||
|
||||
echo -e "${GREEN}✓${NC} Migrated: $file"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo -e "${GREEN}╔═══════════════════════════════════════════════════════════╗${NC}"
|
||||
echo -e "${GREEN}║ ✓ Migration Complete ║${NC}"
|
||||
echo -e "${GREEN}╚═══════════════════════════════════════════════════════════╝${NC}"
|
||||
echo ""
|
||||
echo "Backups saved to: $BACKUP_DIR"
|
||||
echo ""
|
||||
echo "Changes applied:"
|
||||
echo " • \$ARGUMENTS.0 → \$ARGUMENTS[0]"
|
||||
echo " • \$ARGUMENTS.1 → \$ARGUMENTS[1]"
|
||||
echo " • etc."
|
||||
echo ""
|
||||
echo "You can also use shorthand: \$0, \$1, \$2, ..."
|
||||
|
||||
else
|
||||
echo -e "${YELLOW}═══════════════════════════════════════════════════════════${NC}"
|
||||
echo -e "${YELLOW}DRY RUN MODE - No changes applied${NC}"
|
||||
echo -e "${YELLOW}═══════════════════════════════════════════════════════════${NC}"
|
||||
echo ""
|
||||
echo "To apply these changes, run:"
|
||||
echo -e " ${GREEN}./migrate-arguments-syntax.sh --apply${NC}"
|
||||
echo ""
|
||||
echo "This will:"
|
||||
echo " 1. Create backups in ~/.claude/backups/"
|
||||
echo " 2. Update all files to new bracket syntax"
|
||||
echo " 3. Preserve original files in backup directory"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "Documentation: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md#2119"
|
||||
Loading…
Add table
Add a link
Reference in a new issue