Skip to main content

​
How Tracer Uses Git

Tracer stores issues in JSONL (JSON Lines) format at .trace/issues.jsonl. This file is:
  • Human-readable - each line is a JSON object
  • Git-friendly - changes are easy to merge
  • Portable - works across any machine with Git
Tracer automatically syncs between its SQLite database and the JSONL file, giving you the best of both worlds:
  • Fast queries via SQLite
  • Git-friendly storage for syncing

​
Automatic Export

Every time you make a change, Tracer updates .trace/issues.jsonl: 
# Create an issue
tracer create "New feature" -t feature
# ✓ Automatically written to .trace/issues.jsonl

# Update status
tracer update bd-1 --status in_progress
# ✓ Automatically updates .trace/issues.jsonl
No manual export needed - it just works.
The .trace/ directory is designed to be committed to Git. Add it to your repository to share issues with your team.

​
Automatic Import

When you pull changes from Git, Tracer detects updates automatically: 
# Pull changes from remote
git pull origin main

# Run any tracer command
tracer ready
# ✓ Automatically imports updated issues from .trace/issues.jsonl
Tracer checks the file hash and only imports when changes are detected.

​
Multi-Machine Workflow

Use Tracer seamlessly across multiple machines:
1

Machine A: Create issues

# On your laptop
tracer create "Implement auth" -t feature
tracer create "Add tests" -t task --deps "blocks:bd-1"

# Commit and push
git add .trace/issues.jsonl
git commit -m "Add auth tasks"
git push origin main
2

Machine B: Pull and continue

# On your server
git pull origin main

# Issues automatically sync
tracer ready
# Shows: bd-1 Implement auth [P2, feature]

# Start work
tracer update bd-1 --status in_progress
3

Machine B: Push progress

# Make progress and update
tracer comment bd-1 "Auth endpoint implemented"
tracer close bd-1

# Push changes back
git add .trace/issues.jsonl
git commit -m "Complete auth implementation"
git push origin main
4

Machine A: Sync latest

# Pull updates
git pull origin main

# See completed work
tracer show bd-1
# Status: closed
# Comment: "Auth endpoint implemented"

# bd-2 is now unblocked and ready
tracer ready
# Shows: bd-2 Add tests [P2, task]

​
Handling Merge Conflicts

If two machines modify the same issue simultaneously, Git may create a merge conflict in .trace/issues.jsonl.

​
Resolving Conflicts

1

Git shows conflict

git pull origin main
# CONFLICT (content): Merge conflict in .trace/issues.jsonl
2

Resolve the conflict

Open .trace/issues.jsonl and resolve the conflict manually:
<<<<<<< HEAD
{"id":"bd-1","title":"Feature","status":"in_progress",...}
=======
{"id":"bd-1","title":"Feature","status":"closed",...}
>>>>>>> origin/main
Usually keep both changes (they’re on separate lines):
{"id":"bd-1","title":"Feature","status":"closed",...}
{"id":"bd-2","title":"Other","status":"open",...}
For the same issue ID, keep the most recent version (check timestamps).
3

Import the resolved file

# Import to sync with database
tracer import -i .trace/issues.jsonl

# Complete the merge
git add .trace/issues.jsonl
git commit -m "Resolve merge conflict in issues"
git push origin main
JSONL format makes conflicts rare - each issue is on its own line, so most changes merge automatically.

​
Manual Export & Import

While Tracer handles sync automatically, you can manually export and import if needed.

​
Export Issues

Export all issues to JSONL: 
# Export to file
tracer export -o backup.jsonl

# Export to stdout
tracer export

# Export only open issues
tracer export --status open -o open-issues.jsonl
Use manual export to create backups or share filtered issue sets.

​
Import Issues

Import issues from JSONL: 
# Import from file
tracer import -i issues.jsonl

# Import from stdin
cat issues.jsonl | tracer import

# Skip existing issues (don't update)
tracer import -i issues.jsonl --skip-existing

# Dry run to see what would be imported
tracer import -i issues.jsonl --dry-run
Import behavior:
  • New issues - Created in the database
  • Existing issues - Updated with new data (unless --skip-existing)
  • Dependencies - Imported and created automatically
# Import and update all issues
tracer import -i issues.jsonl
# ✓ Import complete:
#   Created: 5
#   Updated: 3

​
JSONL Format

Each line in .trace/issues.jsonl is a complete issue object: 
{"id":"bd-1","title":"Implement auth","description":"","status":"open","priority":1,"issue_type":"feature","assignee":"","created_at":"2025-10-15T10:00:00Z","updated_at":"2025-10-15T10:00:00Z","closed_at":null,"dependencies":[]}
{"id":"bd-2","title":"Add tests","description":"","status":"open","priority":2,"issue_type":"task","assignee":"","created_at":"2025-10-15T11:00:00Z","updated_at":"2025-10-15T11:00:00Z","closed_at":null,"dependencies":[{"issue_id":"bd-2","depends_on_id":"bd-1","dep_type":"blocks","created_at":"2025-10-15T11:00:00Z","created_by":"system"}]}
This format is:
  • One issue per line
  • Valid JSON on each line
  • Includes dependencies inline
  • Sortable and diffable
Don’t edit .trace/issues.jsonl manually unless you know what you’re doing. Use tracer commands instead.

​
Multi-Agent Collaboration

Multiple agents can work on the same project by syncing via Git: 
# Agent 1: Claim work
tracer --actor agent-1 update bd-5 --status in_progress
tracer --actor agent-1 comment bd-5 "Starting API work"

git add .trace/issues.jsonl
git commit -m "agent-1: Start bd-5"
git push origin main
Coordinate work to avoid conflicts - use tracer show to check who’s working on what before starting.

​
Git Best Practices

Commit .trace/ to your repository - this makes issues available to everyone on your team.
Pull before starting work - always git pull to get the latest issues before running tracer ready.
Commit frequently - commit after completing or updating issues so others can see your progress.
Use meaningful commit messages - reference issue IDs in commits:
git commit -m "bd-5: Implement auth endpoint"
Don’t force push - this can cause lost issue data. Use normal merge workflows.

​
Backup and Recovery

Create backups of your issues: 
# Backup all issues
tracer export -o backup-$(date +%Y%m%d).jsonl

# Restore from backup
tracer import -i backup-20251015.jsonl
Your Git history is also a backup - you can always check out old versions: 
# View issues from a previous commit
git show HEAD~5:.trace/issues.jsonl

# Restore issues from 3 days ago
git checkout HEAD~10 -- .trace/issues.jsonl
tracer import -i .trace/issues.jsonl

​
Advanced: Custom Sync Scripts

Automate syncing with Git hooks or scripts: 
# .git/hooks/post-commit
#!/bin/bash
if git diff --cached --name-only | grep -q '.trace/issues.jsonl'; then
  echo "Issues updated"
fi

​
Troubleshooting

Make sure .trace/issues.jsonl is committed:
git status
git add .trace/issues.jsonl
git commit -m "Add issues"
git push origin main
Trigger import manually:
tracer import -i .trace/issues.jsonl
Or run any tracer command (import happens automatically):
tracer ready
Check Git history:
git log -p .trace/issues.jsonl
Restore from backup or previous commit if needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us