Sync Rules

Sync Rule Components

A Sync Rule consists of:

• Source Configuration: Where files come from (repository, branch, path)
• Target Configuration: Where files should go (repository, branch, path)
• Pattern Matching: How to identify which files to sync
• Sync Behavior: How to handle conflicts and file operations
• File Filtering: Which files to include or exclude

Key Behaviors

No Files Found = No Sync

When no files match the source criteria:

• No pull request is created
• No errors are generated
• The sync completes successfully (expected behavior)
• Logs will indicate "No changes found"

When Files Are Found

The sync rule will:

• Analyze differences between source and target
• Create file changes (add, modify, delete)
• Generate a pull request with the changes

Path Configuration

Path Types

Paths are automatically categorized as:

File Path (Default)

• A path without slashes
• Doesn't end with '/'
• Doesn't match directory glob patterns
• Examples: README.md, config.json, tsconfig

Directory Path

• Ends with '/'
• Ends with '/**'
• Matches directory glob pattern ('**/')
• Examples: docs/, src/, config/**

Pattern Types

Exact Match

Perfect for syncing specific files or directories.

README.md              → Syncs exactly this file
src/config.json        → Syncs exactly this file
docs/                  → Syncs the entire docs directory

Glob Patterns

For syncing multiple files matching a pattern.

Syntax:

• * - Matches any characters except '/'
• ** - Matches any characters including '/' (recursive)
• ? - Matches any single character
• [abc] - Matches any character in brackets
• {a,b} - Matches any comma-separated patterns

Examples:

src/*.ts               → All TypeScript files in src/
src/**/*.ts           → All TypeScript files in src/ and subdirectories
docs/**/*.md          → All Markdown files in docs/ recursively
*.{js,ts}             → All JavaScript and TypeScript files in root

Target Path Behavior

For Exact Matches:

Source: README.md
Target: (empty)     → README.md
Target: docs/       → docs/README.md

For Glob Patterns:

Source: src/**/*.ts
Target: (empty)     → src/utils/helper.ts, src/components/Button.ts
Target: lib/        → lib/src/utils/helper.ts, lib/src/components/Button.ts

Sync Configuration

Core Options

Overwrite Existing Files

• Enabled: Replaces existing files with source versions
• Disabled: Skips files that already exist in the target

Use Cases:

• Enable for: Configuration files, shared utilities, documentation
• Disable for: Template files, initial setup files, customizable configs

Delete Orphaned Files

• Enabled: Removes files in target that aren't in source (only for directory sources)
• Disabled: Leaves existing target files untouched

Important:

• Only works for directory sources (paths ending with '/')
• Not available for exact file paths or glob patterns
• Designed to prevent accidental deletions

File Filtering

Include Patterns

Comma-separated glob patterns for files to include (applied after path matching).:

*.ts, *.tsx           → Only TypeScript files
**/*.{md,mdx}         → Only Markdown files
src/**, docs/**       → Files from src/ and docs/ directories

Exclude Patterns

Comma-separated glob patterns for files to exclude (applied after path matching):

*.test.*, **/__tests__/**     → Exclude test files
*.min.js, *.bundle.*          → Exclude minified/bundle files
node_modules/**, .env*        → Exclude dependencies and env files

Common Use Cases

Documentation Syncing

Source: docs/
Target: (empty)
Delete Orphaned: true
→ Exact mirror of docs/ directory

Shared Components

Source: src/components/**/*.tsx
Target: (empty)
Include: *.tsx, *.ts
Exclude: *.test.*, *.stories.*
→ Syncs components without tests/stories

Configuration Distribution

Source: .github/workflows/ci.yml
Target: .github/workflows/
Overwrite: true
→ Updates CI workflow in target

Best Practices

Path Design

• Be specific to avoid unintended file syncing
• Test patterns before running
• Document rule intentions

Safety

• Start with Overwrite disabled
• Backup important files
• Always review PRs before merging

Performance

• Use specific paths over broad patterns
• Use effective include/exclude filters
• Group related synchronizations

Troubleshooting

No Files Found

Not an error - sync completes without creating a PR.

Common Causes:

• Nonexistent paths
• Empty directories
• Pattern mismatches
• Overly restrictive filters

Debugging Steps:

1. Check pattern syntax
2. Verify paths exist
3. Review filters
4. Browse repository manually
5. Test complex patterns

Unexpected Files

• Refine glob patterns
• Add exclude patterns
• Verify source paths

Conflicts

• Check Overwrite setting
• Verify branch configuration
• Review target paths

---

Ready to create powerful sync rules? Start with simple exact matches and gradually explore glob patterns as your needs grow!