SQUASH vs ITERATIVE

SQUASH vs ITERATIVE

Two workflow modes that push directly to the destination, with different approaches to commit history.

Visual Comparison

SQUASH Mode

ITERATIVE Mode

Feature Comparison

Feature	SQUASH	ITERATIVE
Commits created	1 per sync	1 per origin commit
History preserved	No	Yes
Handles merges	Gracefully	May fail
Bisect-friendly	No	Yes
Initial sync speed	Fast	Slower
Complexity	Low	Higher

When to Use SQUASH

Recommended for most workflows. Use SQUASH when:

• Destination history doesn’t need to match origin
• You have complex merge histories
• You want cleaner destination history
• You’re syncing frequently (avoid commit spam)
• You’re just mirroring without bidirectional sync

core.workflow(
    name = "export",
    mode = "SQUASH",
    ...
)

SQUASH Commit Messages

Copybara creates informative commit messages:

Project import generated by Copybara.

Changes:
- fix: correct validation logic
- feat: add user authentication
- docs: update README

GitOrigin-RevId: abc123def456

You can customize with metadata.squash_notes():

transformations = [
    metadata.squash_notes(
        prefix = "Sync from internal:\n\n",
        show_author = True,
        show_description = True,
        oldest_first = True,
    ),
]

When to Use ITERATIVE

Use ITERATIVE when:

• You need exact commit-to-commit mapping
• Auditing requires preserved history
• You need to git bisect on the destination
• Each commit must be individually traceable
• Linear history in origin (no merges)

core.workflow(
    name = "export",
    mode = "ITERATIVE",
    ...
)

Caution

ITERATIVE mode can fail on merge commits. If your origin has a complex merge history, use SQUASH instead.

ITERATIVE Commit Messages

Each destination commit includes:

Original commit message here

GitOrigin-RevId: abc123

Handling Merge Commits

SQUASH Behavior

Merge commits are handled transparently - all changes are combined:

ITERATIVE Behavior

Merge commits can cause issues:

Tip

If you must use ITERATIVE with merges, ensure your origin has a linear history (rebased, no merge commits).

Performance Comparison

Initial Sync

Mode	100 commits	1000 commits	10000 commits
SQUASH	Fast	Fast	Fast
ITERATIVE	Moderate	Slow	Very slow

SQUASH processes all changes at once; ITERATIVE must process each commit individually.

Incremental Syncs

Both modes perform similarly for incremental syncs (only new commits are processed).

Configuration Examples

SQUASH with Custom Notes

core.workflow(
    name = "export-squash",
    mode = "SQUASH",
    transformations = [
        metadata.squash_notes(
            prefix = "Weekly sync from internal:\n\n",
            show_author = True,
            show_description = True,
        ),
        metadata.add_header("Synced-From: internal"),
    ],
    ...
)

ITERATIVE with Author Mapping

core.workflow(
    name = "export-iterative",
    mode = "ITERATIVE",
    transformations = [
        metadata.map_author({
            "internal@corp.com": "external@example.com",
        }),
        metadata.expose_label("Reviewed-by"),
    ],
    ...
)

Decision Flowchart

Switching Between Modes

You can switch modes between syncs, but be aware:

• SQUASH → ITERATIVE: Works, but you’ll lose the “squash” point in history
• ITERATIVE → SQUASH: Works, subsequent sync will squash all new changes

The state tracking (via GitOrigin-RevId) works across mode changes.

Next Steps

• CHANGE_REQUEST for PR workflows
• Metadata transformations