Sync issues

Common problems when running aligntrue sync and how to fix them.

Why aren’t my new files syncing?

Symptom: You added new rule files (e.g., CLAUDE.md, .cursor/rules/new.mdc) but they’re not showing up in sync.

Causes:

Files not in edit_source (most common)
Files have no content or sections
Watch mode not picking up changes

Fix:

Check edit_source configuration:
```
aligntrue config get sync.edit_source
```
If your file isn’t covered by the pattern, run sync interactively:
```
aligntrue sync
```
AlignTrue will detect the new files and prompt you to import them.
Verify file has content:
```
# File must have markdown headings (## or ###)
cat CLAUDE.md
```
If the file is empty or has no headings, AlignTrue won’t detect it as having content.

For watch mode, new files are logged but not auto-imported:


# Stop watch
Ctrl+C
 
# Run sync interactively
aligntrue sync
 
# Restart watch
aligntrue watch

Example:


# 1. Check current configuration
aligntrue config get sync.edit_source
# Output: "AGENTS.md"
 
# 2. You added CLAUDE.md but it's not tracked
 
# 3. Run sync to detect and import
aligntrue sync
 
# 4. Prompt appears asking to import CLAUDE.md
# Choose: Import all and merge
 
# 5. File is now tracked
aligntrue config get sync.edit_source
# Output: ["AGENTS.md", "CLAUDE.md"]

Missing sections after sync

Symptom: After syncing, some sections from your files are missing in the output.

Causes:

Duplicate sections (last-write-wins applied)
Files not detected as edited
Parse errors in markdown

Fix:

Check for conflicts:
```
aligntrue sync --verbose
```
Look for warning messages about duplicate sections.
Review drift log:
```
cat .aligntrue/.drift-log.json
```
Shows which files were detected and their status.
Check file modification times:
```
ls -la AGENTS.md .cursor/rules/*.mdc
```
Only files modified since last sync are processed.

Force a full re-import:


# Remove drift log to reset
rm .aligntrue/.drift-log.json
 
# Run sync
aligntrue sync

Duplicate sections in output

Symptom: The same section appears multiple times in exported files.

Causes:

Same section in multiple source files
Different headings that look similar

Fix:

Identify duplicates:


# Grep for duplicate headings
grep "^## " AGENTS.md | sort | uniq -c | grep -v "^ *1 "

Remove duplicates from source files:


nano AGENTS.md  # Remove duplicate sections
nano CLAUDE.md  # Remove duplicate sections

Sync again:
```
aligntrue sync
```

AlignTrue’s behavior: When the same section appears in multiple files, last-write-wins (most recently modified file) is used.

Sync shows no changes but files are different

Symptom: You edited files but aligntrue sync says “no changes detected.”

Causes:

File not in edit_source
File modification time not updated
Editing read-only exports

Fix:

Check if file is in edit_source:
```
aligntrue config get sync.edit_source
```
Touch file to update mtime:
```
touch AGENTS.md
aligntrue sync
```
Verify you’re editing the right file:
```
# Check for read-only warning at top of file
head -20 .cursor/rules/aligntrue.mdc
```
If you see <!-- WARNING: READ-ONLY FILE, you should edit the source file listed in the warning instead.

Watch mode not detecting new files

Symptom: You added a new file while aligntrue watch is running, but no sync triggered.

Expected behavior: Watch mode logs new files but doesn’t auto-import them by default.

What you see:


[Watch] New file detected: CLAUDE.md (5 sections)
  ℹ Run 'aligntrue sync' to review and import

Fix:

Stop watch and run sync:


# In watch terminal: Ctrl+C
aligntrue sync
# Choose import strategy
aligntrue watch  # Restart

Or enable auto-import (opt-in):


# .aligntrue/config.yaml
watch:
  on_new_files: "auto_import"

Then restart watch:


aligntrue watch

Formatting issues in exported files

Symptom: Exported files have missing newlines or malformed markdown.

Example:


---### Heading

Instead of:


---
 
### Heading

Cause: Source files have formatting issues.

Fix:

Check source files for issues:


# Look for horizontal rules without spacing
grep -n "^---[^-]" AGENTS.md CLAUDE.md

Fix manually or let AlignTrue normalize:
```
# AlignTrue automatically fixes common issues during export
aligntrue sync
```
The exporter now includes automatic formatting normalization.

Drift log shows pending files that don’t exist

Symptom: .aligntrue/.drift-log.json references files you’ve deleted.

Fix:

Clear drift log:
```
rm .aligntrue/.drift-log.json
```

Or edit manually:


nano .aligntrue/.drift-log.json
# Remove entries for deleted files

Run sync to rebuild:
```
aligntrue sync
```

Edit source changed unexpectedly

Symptom: After running aligntrue sync, your sync.edit_source configuration changed from one file to another.

Example:

Before: sync.edit_source was "AGENTS.md"
After: sync.edit_source became ".cursor/rules/*.mdc"

Root cause: AlignTrue auto-detects when multi-file agents (like Cursor) are introduced and automatically switches to that format for better scalability and file organization.

When this happens:

You create new agent files (e.g., .cursor/rules/aligntrue.mdc)
You run aligntrue sync with --yes flag (non-interactive mode)
AlignTrue detects the multi-file structure and auto-switches edit_source
The change is logged but may not be obvious in non-interactive mode

To see what changed:


# Check current edit_source
aligntrue config get sync.edit_source
 
# Review recent sync output
# Look for: "Auto-switching edit_source from X to Y"

Fix if unwanted:

If you prefer to keep the original edit_source, reset it:


# Reset to AGENTS.md
aligntrue config set sync.edit_source "AGENTS.md"
 
# Run sync again
aligntrue sync

To prevent auto-detection:

Run sync interactively (without --yes):


aligntrue sync

This prompts you to confirm the edit_source switch before it happens.

Best practice:

Use interactive mode (aligntrue sync) during setup to see and approve changes
Use non-interactive mode (aligntrue sync --yes) in CI after setup is complete
Document your chosen edit_source in project README so team members know the convention

Getting help

If you’re still stuck:

Run with verbose output:
```
aligntrue sync --verbose
```
Check debug logs:
```
DEBUG_SYNC=1 aligntrue sync
```
Review backup:
```
aligntrue backup list
```
File an issue:
- Repository: https://github.com/AlignTrue/aligntrue
- Include verbose output and configuration