Workflow Modes
Workflow Modes
Section titled “Workflow Modes”The mode parameter controls how Copybara creates commits in the destination repository.
Mode Comparison
Section titled “Mode Comparison”| Mode | Commits | Destination | Review | Best For |
|---|---|---|---|---|
SQUASH | All → 1 | Direct push | No | Simple sync |
ITERATIVE | 1 → 1 | Direct push | No | History preservation |
CHANGE_REQUEST | All → 1 PR | PR/CL | Yes | External review |
CHANGE_REQUEST_FROM_SOT | All → 1 PR | PR/CL | Yes | Bidirectional |
SQUASH Mode
Section titled “SQUASH Mode”The default and most commonly used mode. All origin changes are combined into a single destination commit.
core.workflow( name = "export", mode = "SQUASH", ...)Behavior
Section titled “Behavior”
Commit Message
Section titled “Commit Message”SQUASH mode creates a commit message with metadata:
Sync from origin
- Change A description- Change B description- Change C description
GitOrigin-RevId: abc123def456When to Use
Section titled “When to Use”- Most sync workflows
- When origin history isn’t important
- When you want clean destination history
- When dealing with complex merge histories
ITERATIVE Mode
Section titled “ITERATIVE Mode”Preserves individual commits from the origin. Each origin commit becomes a destination commit.
core.workflow( name = "export", mode = "ITERATIVE", ...)Behavior
Section titled “Behavior”
When to Use
Section titled “When to Use”- When commit history must be preserved
- When individual changes need to be traceable
- For auditing or compliance requirements
Limitations
Section titled “Limitations”- Merge commits can cause issues
- More complex to troubleshoot
- Larger initial sync time
CHANGE_REQUEST Mode
Section titled “CHANGE_REQUEST Mode”Creates a pull request (GitHub) or change list (Gerrit) instead of pushing directly.
core.workflow( name = "export", mode = "CHANGE_REQUEST", destination = git.github_pr_destination( url = "https://github.com/org/repo", destination_ref = "main", pr_branch = "copybara/sync-${CONTEXT_REFERENCE}", title = "Sync from internal", ), ...)Behavior
Section titled “Behavior”
When to Use
Section titled “When to Use”- When changes need review before merging
- When you don’t have direct push access
- For audited change processes
- When human approval is required
PR Destination Options
Section titled “PR Destination Options”git.github_pr_destination( url = "https://github.com/org/repo", destination_ref = "main", pr_branch = "copybara/sync-${CONTEXT_REFERENCE}", title = "Sync: ${CONTEXT_REFERENCE}", body = "Automated sync from internal repository", # Optional settings update_description = True, # Update PR description on re-run primary_branch_migration = True, # Use default branch if main doesn't exist)CHANGE_REQUEST_FROM_SOT Mode
Section titled “CHANGE_REQUEST_FROM_SOT Mode”Similar to CHANGE_REQUEST, but designed for importing changes back to the source of truth.
core.workflow( name = "import", mode = "CHANGE_REQUEST_FROM_SOT", origin = git.github_pr_origin( url = "https://github.com/org/public-repo", branch = "main", ), destination = git.gerrit_destination( url = "https://gerrit.internal/repo", push_to_refs_for = "main", ), ...)Behavior
Section titled “Behavior”Imports external PRs as internal CLs for review:
When to Use
Section titled “When to Use”- Importing external contributions to internal systems
- When external changes need internal review
- Gerrit-based internal development
Mode Selection Guide
Section titled “Mode Selection Guide”Use SQUASH:
mode = "SQUASH",destination = git.destination(url = ..., push = "main"),Best for: Regular sync where destination history doesn’t need to match origin.
Use ITERATIVE:
mode = "ITERATIVE",destination = git.destination(url = ..., push = "main"),Best for: When you need 1:1 commit mapping.
Use CHANGE_REQUEST:
mode = "SQUASH", # or "ITERATIVE"destination = git.github_pr_destination(...),Best for: When changes need review, or you lack push access.