feat: Enhance .gitattributes with canonical patterns from gitattributes/gitattributes

[rjmurillo]

Summary

Align .gitattributes with canonical patterns from gitattributes/gitattributes to improve cross-platform compatibility, diff rendering, and binary file handling.

Current State

The repository has a solid foundation:

• Global LF normalization (* text=auto eol=lf) to fix YAML frontmatter parsing issues
• Custom merge strategies for HANDOFF.md and handoffs
• Markdown diff rendering (*.md diff=markdown)

Gap Analysis

Missing from Common.gitattributes

Category	Pattern	Benefit
Documents	*.mdx text diff=markdown	MDX support
Documents	*.txt text	Explicit text handling
Graphics	*.png binary	Prevent corruption
Graphics	*.jpg binary, *.jpeg binary	Prevent corruption
Graphics	*.gif binary, *.ico binary	Prevent corruption
Graphics	*.svg text	Treat as diffable text
Scripts	*.sh text eol=lf	Unix scripts (bootstrap-vm.sh exists)
Serialization	*.json text	Explicit text handling
Serialization	*.yaml text, *.yml text	Explicit text handling
Serialization	*.toml text, *.xml text	Explicit text handling
Archives	*.zip binary, *.gz binary, etc.	Prevent corruption
Patches	*.patch -text	Preserve line endings
Export	.gitattributes export-ignore	Exclude from archives
Export	.gitignore export-ignore	Exclude from archives

Missing from PowerShell.gitattributes

Pattern	Note
*.psm1 text	Module files
*.psd1 text	Data files
*.ps1xml text	Format files
*.pssc text	Session config
*.psrc text	Role capability
*.cdxml text	CDXML files

Note: Template uses eol=crlf but our global eol=lf is intentional per Copilot CLI issue #694/#673. PowerShell 7+ handles LF fine cross-platform.

Missing from Python.gitattributes

Pattern	Benefit
*.py text diff=python	Python-aware diffs
*.pyw text diff=python	Python scripts
*.pyi text diff=python	Type stubs
*.ipynb text eol=lf	Jupyter notebooks
*.pyc binary export-ignore	Compiled bytecode
*.pyo binary export-ignore	Optimized bytecode
*.pyd binary	Python DLLs
*.pickle binary	Serialized data

Missing from Markdown.gitattributes

Pattern	Benefit
*.md linguist-detectable	GitHub language stats

Missing from VS Code / DevContainer

Pattern	Benefit
.vscode/*.json linguist-language=JSON-with-Comments	Proper syntax highlighting on GitHub
.devcontainer.json linguist-language=JSON-with-Comments	JSONC support

Proposed Structure

Reorganize into logical sections following the canonical template structure:

1. Line Ending Normalization (existing)
2. Documents (markdown, text files)
3. Graphics (binary images)
4. Scripts (shell, PowerShell)
5. Serialization (JSON, YAML, TOML, XML)
6. Python (source and binaries)
7. Archives (compressed files)
8. Patches (preserve line endings)
9. GitHub/Linguist (language detection, syntax highlighting)
10. Export (archive exclusions)
11. Custom Merge Strategies (existing HANDOFF.md, handoffs)

Acceptance Criteria

• Add explicit text attribute to markdown files: *.md text diff=markdown
• Add binary declarations for common image formats
• Add PowerShell file type declarations (*.psm1, *.psd1, etc.)
• Add Python file type declarations with diff=python
• Add shell script declarations (*.sh, *.bash, etc.)
• Add serialization format declarations (JSON, YAML, TOML, XML)
• Add archive binary declarations
• Add patch file handling (*.patch -text)
• Add linguist attributes for GitHub rendering
• Add export-ignore for git metadata files
• Preserve existing custom merge strategies
• Maintain LF-first decision (override template CRLF recommendations)

References

• gitattributes/gitattributes - Canonical templates
• Common.gitattributes
• PowerShell.gitattributes
• Python.gitattributes
• Markdown.gitattributes
• Copilot CLI issues feat(validator): add investigation-only session QA skip validation #694, feat(skills): Standardize skill output format across all skills #673 (YAML parsing with CRLF)

[traycerai]

Plan

Observations

The current file:.gitattributes has a solid foundation with global LF normalization (* text=auto eol=lf), custom merge strategies for HANDOFF.md and handoffs, and skill file diff configuration. The repository contains extensive PowerShell files (.ps1, .psm1, .psd1), Python scripts (.py), shell scripts (.sh), markdown files (.md), JSON files (.json), and YAML files (.yaml, *.yml). The existing structure is well-documented with comprehensive comments explaining the rationale behind each configuration decision, particularly the LF-first approach to resolve YAML frontmatter parsing issues.

Approach

Enhance file:.gitattributes by adding canonical patterns from gitattributes/gitattributes repository while preserving existing custom merge strategies and LF-first decision. Organize new patterns into logical sections following the proposed structure: Documents, Graphics, Scripts (Shell and PowerShell), Serialization, Python, Archives, Patches, GitHub/Linguist, and Export. Maintain the existing documentation style with clear comments explaining each section's purpose. Override PowerShell template's CRLF recommendation with LF to maintain consistency with the repository's established line ending strategy.

Implementation Steps

1. Add Documents Section

After the existing line ending normalization section and before custom merge strategies, add a new "Documents" section in file:.gitattributes:

• Add explicit text attribute to markdown files: *.md text diff=markdown (upgrade from current *.skill diff=markdown)
• Add MDX support: *.mdx text diff=markdown
• Add text file handling: *.txt text
• Include comment explaining that these patterns ensure proper text handling and diff rendering for documentation files

2. Add Graphics Section

Create a "Graphics" section for binary image handling:

• Add binary declarations for common image formats to prevent corruption:
  • PNG: *.png binary
  • JPEG: *.jpg binary, *.jpeg binary
  • GIF: *.gif binary
  • ICO: *.ico binary
• Add SVG as diffable text: *.svg text
• Include comment explaining that binary declarations prevent Git from attempting text operations on image files

3. Add Shell Scripts Section

Create a "Scripts - Shell" section:

• Add shell script declarations with LF line endings:
  • *.sh text eol=lf
  • *.bash text eol=lf
• Reference the existing bootstrap-vm.sh file in .github/actions/ai-review/ as justification
• Include comment explaining that Unix scripts require LF line endings to function correctly

4. Add PowerShell Section

Create a "Scripts - PowerShell" section:

• Add PowerShell file type declarations (note: use eol=lf instead of template's eol=crlf):
  • *.ps1 text eol=lf (scripts)
  • *.psm1 text eol=lf (modules - found 13 files)
  • *.psd1 text eol=lf (data files - found 2 files)
  • *.ps1xml text eol=lf (format files)
  • *.pssc text eol=lf (session config)
  • *.psrc text eol=lf (role capability)
  • *.cdxml text eol=lf (CDXML files)
• Include prominent comment explaining the LF override: "PowerShell 7+ handles LF fine cross-platform. This overrides the canonical template's CRLF recommendation to maintain consistency with our LF-first strategy (see Line Ending Normalization section above)."

5. Add Serialization Section

Create a "Serialization" section for structured data formats:

• Add explicit text handling for serialization formats:
  • *.json text
  • *.yaml text
  • *.yml text
  • *.toml text
  • *.xml text
• Include comment explaining that explicit text declarations ensure consistent handling of configuration and data files

6. Add Python Section

Create a "Python" section:

• Add Python source file declarations with diff=python:
  • *.py text diff=python (found 14 Python files)
  • *.pyw text diff=python
  • *.pyi text diff=python (type stubs)
• Add Jupyter notebook handling: *.ipynb text eol=lf
• Add Python binary file declarations:
  • *.pyc binary export-ignore (compiled bytecode)
  • *.pyo binary export-ignore (optimized bytecode)
  • *.pyd binary (Python DLLs)
  • *.pickle binary (serialized data)
• Include comment explaining that diff=python provides Python-aware diffs and export-ignore excludes compiled files from archives

7. Add Archives Section

Create an "Archives" section for compressed files:

• Add binary declarations for common archive formats:
  • *.zip binary
  • *.gz binary
  • *.tar binary
  • *.7z binary
  • *.rar binary
• Include comment explaining that archives must be treated as binary to prevent corruption

8. Add Patches Section

Create a "Patches" section:

• Add patch file handling: *.patch -text
• Add diff file handling: *.diff -text
• Include comment explaining that -text preserves original line endings in patch files, which is critical for patch application

9. Add GitHub/Linguist Section

Create a "GitHub/Linguist" section for GitHub-specific attributes:

• Add markdown language detection: *.md linguist-detectable
• Note: Skip VS Code/DevContainer patterns (.vscode/*.json linguist-language=JSON-with-Comments, .devcontainer.json linguist-language=JSON-with-Comments) as no such files exist in the repository
• Include comment explaining that linguist attributes improve GitHub's language statistics and syntax highlighting

10. Add Export Section

Create an "Export" section for archive exclusions:

• Add export-ignore for git metadata files:
  • .gitattributes export-ignore
  • .gitignore export-ignore
• Include comment explaining that export-ignore excludes these files from git archive operations, keeping distribution archives clean

11. Preserve Existing Sections

Maintain all existing sections without modification:

• Keep "Line Ending Normalization" section with * text=auto eol=lf and comprehensive documentation
• Keep "HANDOFF.md Merge Strategy" section with merge=ours configuration
• Keep "Branch Handoffs" section with merge=handoff-aggregate configuration
• Keep "Skill Files: Diff Configuration" section, but note that *.md text diff=markdown in the Documents section will supersede *.skill diff=markdown

12. Update Section Order

Reorganize file:.gitattributes to follow the proposed logical structure:

1. Line Ending Normalization (existing)
2. Documents (new)
3. Graphics (new)
4. Scripts - Shell (new)
5. Scripts - PowerShell (new)
6. Serialization (new)
7. Python (new)
8. Archives (new)
9. Patches (new)
10. GitHub/Linguist (new)
11. Export (new)
12. Custom Merge Strategies - HANDOFF.md (existing)
13. Custom Merge Strategies - Branch Handoffs (existing)
14. Skill Files (existing, may be redundant after Documents section)

13. Documentation Style

Maintain the existing documentation style throughout:

• Use section headers with equals signs: # ============================================================================
• Include "WHY DO WE NEED THIS?" subsections explaining the problem
• Include "HOW DOES IT WORK?" subsections explaining the solution
• Add references to relevant issues, ADRs, or external documentation where applicable
• Use clear, concise language that explains both the technical mechanism and business value

Import In IDE

🤖 Prompt for AI Agents

## Observations

The current file:`.gitattributes` has a solid foundation with global LF normalization (`* text=auto eol=lf`), custom merge strategies for HANDOFF.md and handoffs, and skill file diff configuration. The repository contains extensive PowerShell files (*.ps1, *.psm1, *.psd1), Python scripts (*.py), shell scripts (*.sh), markdown files (*.md), JSON files (*.json), and YAML files (*.yaml, *.yml). The existing structure is well-documented with comprehensive comments explaining the rationale behind each configuration decision, particularly the LF-first approach to resolve YAML frontmatter parsing issues.

## Approach

Enhance file:`.gitattributes` by adding canonical patterns from gitattributes/gitattributes repository while preserving existing custom merge strategies and LF-first decision. Organize new patterns into logical sections following the proposed structure: Documents, Graphics, Scripts (Shell and PowerShell), Serialization, Python, Archives, Patches, GitHub/Linguist, and Export. Maintain the existing documentation style with clear comments explaining each section's purpose. Override PowerShell template's CRLF recommendation with LF to maintain consistency with the repository's established line ending strategy.

## Implementation Steps

### 1. Add Documents Section

After the existing line ending normalization section and before custom merge strategies, add a new "Documents" section in file:`.gitattributes`:

- Add explicit `text` attribute to markdown files: `*.md text diff=markdown` (upgrade from current `*.skill diff=markdown`)
- Add MDX support: `*.mdx text diff=markdown`
- Add text file handling: `*.txt text`
- Include comment explaining that these patterns ensure proper text handling and diff rendering for documentation files

### 2. Add Graphics Section

Create a "Graphics" section for binary image handling:

- Add binary declarations for common image formats to prevent corruption:
  - PNG: `*.png binary`
  - JPEG: `*.jpg binary`, `*.jpeg binary`
  - GIF: `*.gif binary`
  - ICO: `*.ico binary`
- Add SVG as diffable text: `*.svg text`
- Include comment explaining that binary declarations prevent Git from attempting text operations on image files

### 3. Add Shell Scripts Section

Create a "Scripts - Shell" section:

- Add shell script declarations with LF line endings:
  - `*.sh text eol=lf`
  - `*.bash text eol=lf`
- Reference the existing bootstrap-vm.sh file in `.github/actions/ai-review/` as justification
- Include comment explaining that Unix scripts require LF line endings to function correctly

### 4. Add PowerShell Section

Create a "Scripts - PowerShell" section:

- Add PowerShell file type declarations (note: use `eol=lf` instead of template's `eol=crlf`):
  - `*.ps1 text eol=lf` (scripts)
  - `*.psm1 text eol=lf` (modules - found 13 files)
  - `*.psd1 text eol=lf` (data files - found 2 files)
  - `*.ps1xml text eol=lf` (format files)
  - `*.pssc text eol=lf` (session config)
  - `*.psrc text eol=lf` (role capability)
  - `*.cdxml text eol=lf` (CDXML files)
- Include prominent comment explaining the LF override: "PowerShell 7+ handles LF fine cross-platform. This overrides the canonical template's CRLF recommendation to maintain consistency with our LF-first strategy (see Line Ending Normalization section above)."

### 5. Add Serialization Section

Create a "Serialization" section for structured data formats:

- Add explicit text handling for serialization formats:
  - `*.json text`
  - `*.yaml text`
  - `*.yml text`
  - `*.toml text`
  - `*.xml text`
- Include comment explaining that explicit text declarations ensure consistent handling of configuration and data files

### 6. Add Python Section

Create a "Python" section:

- Add Python source file declarations with diff=python:
  - `*.py text diff=python` (found 14 Python files)
  - `*.pyw text diff=python`
  - `*.pyi text diff=python` (type stubs)
- Add Jupyter notebook handling: `*.ipynb text eol=lf`
- Add Python binary file declarations:
  - `*.pyc binary export-ignore` (compiled bytecode)
  - `*.pyo binary export-ignore` (optimized bytecode)
  - `*.pyd binary` (Python DLLs)
  - `*.pickle binary` (serialized data)
- Include comment explaining that diff=python provides Python-aware diffs and export-ignore excludes compiled files from archives

### 7. Add Archives Section

Create an "Archives" section for compressed files:

- Add binary declarations for common archive formats:
  - `*.zip binary`
  - `*.gz binary`
  - `*.tar binary`
  - `*.7z binary`
  - `*.rar binary`
- Include comment explaining that archives must be treated as binary to prevent corruption

### 8. Add Patches Section

Create a "Patches" section:

- Add patch file handling: `*.patch -text`
- Add diff file handling: `*.diff -text`
- Include comment explaining that `-text` preserves original line endings in patch files, which is critical for patch application

### 9. Add GitHub/Linguist Section

Create a "GitHub/Linguist" section for GitHub-specific attributes:

- Add markdown language detection: `*.md linguist-detectable`
- Note: Skip VS Code/DevContainer patterns (`.vscode/*.json linguist-language=JSON-with-Comments`, `.devcontainer.json linguist-language=JSON-with-Comments`) as no such files exist in the repository
- Include comment explaining that linguist attributes improve GitHub's language statistics and syntax highlighting

### 10. Add Export Section

Create an "Export" section for archive exclusions:

- Add export-ignore for git metadata files:
  - `.gitattributes export-ignore`
  - `.gitignore export-ignore`
- Include comment explaining that export-ignore excludes these files from `git archive` operations, keeping distribution archives clean

### 11. Preserve Existing Sections

Maintain all existing sections without modification:

- Keep "Line Ending Normalization" section with `* text=auto eol=lf` and comprehensive documentation
- Keep "HANDOFF.md Merge Strategy" section with `merge=ours` configuration
- Keep "Branch Handoffs" section with `merge=handoff-aggregate` configuration
- Keep "Skill Files: Diff Configuration" section, but note that `*.md text diff=markdown` in the Documents section will supersede `*.skill diff=markdown`

### 12. Update Section Order

Reorganize file:`.gitattributes` to follow the proposed logical structure:

1. Line Ending Normalization (existing)
2. Documents (new)
3. Graphics (new)
4. Scripts - Shell (new)
5. Scripts - PowerShell (new)
6. Serialization (new)
7. Python (new)
8. Archives (new)
9. Patches (new)
10. GitHub/Linguist (new)
11. Export (new)
12. Custom Merge Strategies - HANDOFF.md (existing)
13. Custom Merge Strategies - Branch Handoffs (existing)
14. Skill Files (existing, may be redundant after Documents section)

### 13. Documentation Style

Maintain the existing documentation style throughout:

- Use section headers with equals signs: `# ============================================================================`
- Include "WHY DO WE NEED THIS?" subsections explaining the problem
- Include "HOW DOES IT WORK?" subsections explaining the solution
- Add references to relevant issues, ADRs, or external documentation where applicable
- Use clear, concise language that explains both the technical mechanism and business value

---

Execution Information

Branch: main
Commit: e0318e3

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#222 - fix(workflow): add missing ./ prefix to Import-Module paths [merged]
#466 - feat(prompts): add context-aware evaluation to AI Quality Gate prompts [merged]
#473 - docs(github): update SKILL.md with new scripts and Copilot guidance [merged]
#543 - feat(copilot-detection): implement actual file comparison in Compare-DiffContent [merged]
#775 - docs: implement CLAUDE.md @imports pattern [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

AI Triage Summary

Note

This issue has been automatically triaged by AI agents

What is AI Triage?

This issue was analyzed by AI agents:

• Analyst Agent: Categorizes the issue and suggests appropriate labels
• Roadmap Agent: Aligns the issue with project milestones and priorities
• Explainer Agent (if escalated): Generates comprehensive PRD

Triage Results

Property	Value
Category	enhancement
Labels	["enhancement","area-infrastructure"]
Priority	P2
Milestone	Not assigned

Categorization Analysis

```json
{
  "labels": ["enhancement", "area-infrastructure"],
  "category": "enhancement",
  "confidence": 0.95,
  "reasoning": "Issue proposes new .gitattributes patterns for improved cross-platform compatibility and is infrastructure-related"
}

</details>

<details>
<summary>Roadmap Alignment</summary>

```json
```json
{
  "milestone": "",
  "priority": "P2",
  "epic_alignment": "",
  "confidence": 0.85,
  "reasoning": "Infrastructure enhancement for cross-platform compatibility; no blocking issues, clear implementation path from canonical templates",
  "escalate_to_prd": false,
  "escalation_criteria": [],
  "complexity_score": 0
}

</details>

---

<sub>Powered by [AI Issue Triage](https://github.com/rjmurillo/ai-agents) workflow</sub>