Git Workflow Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The Git Workflow Strategy in Morty defines how the autonomous AI coding loop interacts with version control to ensure safety, isolation, and organized contributions. The strategy supports two primary modes: sequential execution on a single branch and parallel execution using isolated git worktrees. This architecture ensures that AI agents can work on multiple tasks simultaneously without local state corruption or file system conflicts.
Sources: morty.sh:10-30, README.md:120-140
Branching Management
Morty employs a specific naming convention and lifecycle for task-specific branches. When enabled, every task extracted from a PRD or provided as a single command results in a dedicated git branch.
Task Branch Lifecycle
- Creation: A branch name is generated by slugifying the task description and prefixing it with
morty/. - Isolation: Before switching, the current working directory state is preserved using
git stash. - Synchronization: The base branch (e.g.,
main) is pulled from the origin to ensure the AI works against the latest code. - Checkout: The new branch is created and checked out.
- Completion: Changes are auto-committed, and optionally, a Pull Request is created via the GitHub CLI (
gh).
Sources: cli/src/git/branch.ts:20-56, morty.sh:820-850
The diagram shows the standard lifecycle of a single-task branch from creation to resolution.
Sources: morty.sh:852-895, cli/src/git/branch.ts:20-40
Parallel Execution with Worktrees
To support simultaneous task execution, Morty utilizes git worktree. This allows the system to spawn multiple AI agents, each operating in its own isolated filesystem directory and git branch.
Isolation Logic
Each parallel agent is assigned a unique worktree directory (usually under .morty-worktrees/) and a unique branch name containing a timestamp and random suffix to prevent collisions. This ensures that file modifications in Agent A's workspace do not affect Agent B.
| Component | Description | Source |
|---|---|---|
| Worktree Base | Local directory (e.g., /tmp/xxx or .morty-worktrees) where agents reside. | cli/src/git/worktree.ts:74-80 |
| Agent Branch | Format: morty/agent-{num}-{uniqueId}-{slug}. | cli/src/git/worktree.ts:25-28 |
| Atomic Creation | Uses git worktree add -B to create/reset branches in one operation. | cli/src/git/worktree.ts:46 |
| Dirty Check | Prevents worktree removal if uncommitted changes exist. | cli/src/git/worktree.ts:57-65 |
Sources: cli/src/git/worktree.ts:20-50, cli/src/execution/parallel.ts:45-80
Integration Branches
For complex task lists (YAML with parallel_groups), Morty uses integration branches. When a group of parallel tasks completes, their branches are merged into a morty/integration-group-{n} branch. Subsequent groups then branch off this integration branch rather than the original base, ensuring dependency fulfillment.
Sources: morty.sh:1190-1230, cli/src/git/merge.ts:55-75
Merge and Conflict Resolution
When parallel tasks finish, Morty attempts to merge the results back into the base branch. Because parallel agents may touch overlapping files, the system includes an automated conflict resolution layer.
The sequence illustrates the fallback mechanism where an AI agent is invoked specifically to resolve git merge markers.
Sources: morty.sh:1300-1370, cli/src/execution/parallel.ts:180-210
Conflict Handling Strategy
- Standard Merge: Initial attempt using
git merge --no-ff. - AI Intervention: If conflicts occur, a specialized prompt is sent to the AI engine containing the conflict markers (
<<<<<<<,=======,>>>>>>>). - Validation: The AI must resolve markers and ensure the resulting code is valid.
- Finalization: If successful, Morty stages the files and completes the merge. If the AI fails, the branch is preserved for manual intervention.
Sources: cli/src/git/merge.ts:115-145, morty.sh:1310-1350
Configuration Options
The Git workflow behavior is controlled via CLI flags and the .morty/config.yaml file.
| Option | Type | Default | Description |
|---|---|---|---|
branchPerTask | Boolean | false | Enables dedicated branch creation for every task. |
baseBranch | String | "" | The branch from which task branches originate (defaults to current). |
createPr | Boolean | false | Automatically creates a GitHub PR upon task completion. |
draftPr | Boolean | false | Ensures created PRs are in "Draft" status. |
skipMerge | Boolean | false | In parallel mode, keeps branches separate without merging to base. |
autoCommit | Boolean | true | Automatically stages and commits AI changes. |
Sources: cli/src/config/types.ts:60-110, morty.sh:445-480
Conclusion
The Git Workflow Strategy in Morty provides a robust framework for autonomous development. By leveraging git worktree for concurrency and AI-assisted merge resolution for integration, it maintains repository integrity while allowing high-throughput parallel coding sessions. This strategy ensures that every AI contribution is traceable, isolated, and safely integrated into the project's main codebase.