Fix Formatting Skill

Automatically fix code formatting issues across file types.

When to Use

Pre-commit checks fail due to formatting
Before committing code
After writing new code
CI formatting checks fail

Quick Reference

# Fix everything
./scripts/fix_all_formatting.sh

# Fix specific types
pixi run mojo format src/**/*.mojo
npx markdownlint-cli2 --fix "**/*.md"
just pre-commit-all

Auto-Fix Capabilities

| Tool | Coverage | Manual Fixes | |------|----------|--------------| | pixi run mojo format | 100% | None | | markdownlint | 70% | Language tags, line length | | pre-commit | 100% | None |

Formatting Tools

Mojo Code (100% auto-fix)

# Format all Mojo files
pixi run mojo format src/**/*.mojo

# Format single file
pixi run mojo format src/tensor.mojo

# Check without fixing
pixi run mojo format --check src/**/*.mojo

Fixes: indentation, spacing, line wrapping, blank lines

Markdown (Partial auto-fix)

# Fix markdown issues
npx markdownlint-cli2 --fix "**/*.md"

# Check only
npx markdownlint-cli2 "**/*.md"

Auto-fixes: blank lines, spacing Manual fixes: language tags, line length

Pre-commit Hooks (100% auto-fix)

# Run hooks on changed files
just pre-commit

# Run hooks on all files
just pre-commit-all

Auto-fixes: trailing whitespace, missing newlines, line endings, YAML

Workflow

# 1. Fix all formatting
./scripts/fix_all_formatting.sh

# 2. Review changes
git diff

# 3. Stage changes
git add .

# 4. Commit
git commit -m "fix: apply code formatting"

Common Fixes

Before/After: Mojo

# Before
fn add(x:Int,y:Int)->Int:
    return x+y

# After
fn add(x: Int, y: Int) -> Int:
    return x + y

Before/After: Markdown

Before: Code block immediately follows text without blank line.

After: Add blank line before opening fence and after closing fence.

Before/After: Whitespace

Before (trailing spaces):

line with trailing spaces
another line

After (no trailing spaces):

line with trailing spaces
another line

Manual Fixes Required

Some issues need manual intervention:

Markdown Language Tags

Before (no language tag):

```
code here
```

After (with language tag):

```python
code here
```

Line Length

# Too long (break manually at 120 chars)
This is a very long line that exceeds 120 characters and should be
manually broken into multiple lines for readability.

Scripts Available

scripts/fix_all_formatting.sh - Fix everything
scripts/fix_formatting.sh --mojo - Mojo only
scripts/fix_formatting.sh --markdown - Markdown only
scripts/fix_formatting.sh --precommit - Pre-commit only

CI Integration

CI checks formatting but doesn't fix:

- name: Check Formatting
  run: |
    pixi run mojo format --check src/**/*.mojo
    npx markdownlint-cli2 "**/*.md"

Fix locally and push if CI fails.

Error Handling

| Error | Cause | Fix | |-------|-------|-----| | "Syntax error" | Invalid Mojo code | Fix syntax before formatting | | "Permission denied" | File permissions | Check file ownership | | "Merge conflict" | Merge markers present | Resolve conflicts first |

Best Practices

Fix before commit - Always format before committing
Use pre-commit hooks - Let hooks auto-fix
Review changes - Check what was formatted
Separate commits - Format in separate commit if large changes
NEVER bypass hooks - Using --no-verify is strictly prohibited. If formatting fails, fix the code instead of bypassing the check.

References

Git Commit Policy - Hook bypass prohibition
Configuration: .pre-commit-config.yaml, .markdownlint.yaml
Related skill: run-precommit for pre-commit hooks
Related skill: quality-run-linters for complete linting