muse-e2e-demo.md
markdown
| 1 | # Muse E2E Walkthrough |
| 2 | |
| 3 | A complete tour of every Muse VCS primitive using the CLI, from `init` to |
| 4 | three-way merge conflict resolution. |
| 5 | |
| 6 | --- |
| 7 | |
| 8 | ## Setup |
| 9 | |
| 10 | ```bash |
| 11 | # Install |
| 12 | pip install -e ".[dev]" |
| 13 | |
| 14 | # Create a project directory |
| 15 | mkdir my-project && cd my-project |
| 16 | |
| 17 | # Initialize a Muse repository (default domain: music) |
| 18 | muse init |
| 19 | ``` |
| 20 | |
| 21 | ``` |
| 22 | Initialized empty Muse repository in my-project/.muse/ |
| 23 | Domain: music |
| 24 | ``` |
| 25 | |
| 26 | --- |
| 27 | |
| 28 | ## Step 0 — Root Commit |
| 29 | |
| 30 | ```bash |
| 31 | cp ~/some-beat.mid state/beat.mid |
| 32 | muse commit -m "Root: initial beat" |
| 33 | ``` |
| 34 | |
| 35 | ``` |
| 36 | [main a1b2c3d4] Root: initial beat |
| 37 | ``` |
| 38 | |
| 39 | ```bash |
| 40 | muse log |
| 41 | ``` |
| 42 | |
| 43 | ``` |
| 44 | commit a1b2c3d4 (HEAD -> main) |
| 45 | Date: 2026-03-17 12:00:00 UTC |
| 46 | |
| 47 | Root: initial beat |
| 48 | |
| 49 | + beat.mid |
| 50 | 1 file(s) changed |
| 51 | ``` |
| 52 | |
| 53 | --- |
| 54 | |
| 55 | ## Step 1 — Mainline Commit |
| 56 | |
| 57 | ```bash |
| 58 | cp ~/bass-line.mid state/bass.mid |
| 59 | muse commit -m "Add bass line" |
| 60 | muse log --oneline |
| 61 | ``` |
| 62 | |
| 63 | ``` |
| 64 | b2c3d4e5 (HEAD -> main) Add bass line |
| 65 | a1b2c3d4 Root: initial beat |
| 66 | ``` |
| 67 | |
| 68 | --- |
| 69 | |
| 70 | ## Step 2 — Branch A |
| 71 | |
| 72 | ```bash |
| 73 | muse branch feature/keys |
| 74 | muse checkout feature/keys |
| 75 | cp ~/piano.mid state/keys.mid |
| 76 | muse commit -m "Add piano keys" |
| 77 | ``` |
| 78 | |
| 79 | --- |
| 80 | |
| 81 | ## Step 3 — Branch B (from Step 1) |
| 82 | |
| 83 | ```bash |
| 84 | # Time-travel back to the mainline |
| 85 | muse checkout main |
| 86 | muse branch feature/drums |
| 87 | muse checkout feature/drums |
| 88 | cp ~/drum-fill.mid state/drums.mid |
| 89 | muse commit -m "Add drum fill" |
| 90 | ``` |
| 91 | |
| 92 | ```bash |
| 93 | muse log --graph |
| 94 | ``` |
| 95 | |
| 96 | ``` |
| 97 | * f3e4d5c6 (HEAD -> feature/drums) Add drum fill |
| 98 | | * e4d5c6b7 (feature/keys) Add piano keys |
| 99 | |/ |
| 100 | * b2c3d4e5 (main) Add bass line |
| 101 | * a1b2c3d4 Root: initial beat |
| 102 | ``` |
| 103 | |
| 104 | --- |
| 105 | |
| 106 | ## Step 4 — Clean Three-Way Merge |
| 107 | |
| 108 | ```bash |
| 109 | muse checkout main |
| 110 | muse merge feature/keys |
| 111 | ``` |
| 112 | |
| 113 | ``` |
| 114 | Merge complete. Commit: c4d5e6f7 |
| 115 | ``` |
| 116 | |
| 117 | ```bash |
| 118 | muse merge feature/drums |
| 119 | ``` |
| 120 | |
| 121 | ``` |
| 122 | Merge complete. Commit: d5e6f7a8 |
| 123 | ``` |
| 124 | |
| 125 | Both branches touched different files — no conflicts. The merge commit has two parents. |
| 126 | |
| 127 | ```bash |
| 128 | muse log --stat |
| 129 | ``` |
| 130 | |
| 131 | ``` |
| 132 | commit d5e6f7a8 (HEAD -> main) |
| 133 | Parent: c4d5e6f7 |
| 134 | Parent: ... (merge) |
| 135 | Date: 2026-03-17 12:05:00 UTC |
| 136 | |
| 137 | Merge feature/drums |
| 138 | |
| 139 | + drums.mid |
| 140 | 1 file(s) changed |
| 141 | ``` |
| 142 | |
| 143 | --- |
| 144 | |
| 145 | ## Step 5 — Conflict Merge |
| 146 | |
| 147 | Both branches modify the same file: |
| 148 | |
| 149 | ```bash |
| 150 | # Branch left |
| 151 | muse branch conflict/left |
| 152 | muse checkout conflict/left |
| 153 | echo "version-left" > state/shared.mid |
| 154 | muse commit -m "Left changes shared.mid" |
| 155 | |
| 156 | # Branch right |
| 157 | muse checkout main |
| 158 | muse branch conflict/right |
| 159 | muse checkout conflict/right |
| 160 | echo "version-right" > state/shared.mid |
| 161 | muse commit -m "Right changes shared.mid" |
| 162 | |
| 163 | # Attempt merge |
| 164 | muse checkout main |
| 165 | muse merge conflict/left |
| 166 | muse merge conflict/right |
| 167 | ``` |
| 168 | |
| 169 | ``` |
| 170 | ❌ Merge conflict in 1 file(s): |
| 171 | CONFLICT (both modified): shared.mid |
| 172 | Resolve conflicts and run 'muse merge --continue' |
| 173 | ``` |
| 174 | |
| 175 | ```bash |
| 176 | # Manually resolve: pick one or blend both |
| 177 | cp my-resolved-shared.mid state/shared.mid |
| 178 | |
| 179 | muse merge --continue -m "Merge: resolve shared.mid conflict" |
| 180 | ``` |
| 181 | |
| 182 | ``` |
| 183 | [main e6f7a8b9] Merge: resolve shared.mid conflict |
| 184 | ``` |
| 185 | |
| 186 | --- |
| 187 | |
| 188 | ## Step 6 — Cherry-Pick |
| 189 | |
| 190 | Apply one commit's changes from a branch without merging the whole branch: |
| 191 | |
| 192 | ```bash |
| 193 | muse cherry-pick <commit-id> |
| 194 | ``` |
| 195 | |
| 196 | ``` |
| 197 | [main f7a8b9c0] Add piano keys |
| 198 | ``` |
| 199 | |
| 200 | --- |
| 201 | |
| 202 | ## Step 7 — Time-Travel Checkout |
| 203 | |
| 204 | ```bash |
| 205 | # Inspect any historical commit |
| 206 | muse show a1b2c3d4 |
| 207 | |
| 208 | # Restore working tree to that exact state |
| 209 | muse checkout a1b2c3d4 |
| 210 | ``` |
| 211 | |
| 212 | ``` |
| 213 | HEAD is now at a1b2c3d4 Root: initial beat |
| 214 | ``` |
| 215 | |
| 216 | ```bash |
| 217 | # Restore to branch tip |
| 218 | muse checkout main |
| 219 | ``` |
| 220 | |
| 221 | --- |
| 222 | |
| 223 | ## Step 8 — Revert |
| 224 | |
| 225 | Create a new commit that undoes a prior commit's changes: |
| 226 | |
| 227 | ```bash |
| 228 | muse revert b2c3d4e5 |
| 229 | ``` |
| 230 | |
| 231 | ``` |
| 232 | [main g8a9b0c1] Revert "Add bass line" |
| 233 | ``` |
| 234 | |
| 235 | The revert commit points directly to the parent snapshot — no re-scan required. |
| 236 | |
| 237 | --- |
| 238 | |
| 239 | ## Step 9 — Stash and Restore |
| 240 | |
| 241 | Temporarily set aside uncommitted work: |
| 242 | |
| 243 | ```bash |
| 244 | echo "wip" > state/idea.mid |
| 245 | muse stash |
| 246 | # state is clean — idea.mid is shelved |
| 247 | |
| 248 | muse stash pop |
| 249 | # idea.mid is back |
| 250 | ``` |
| 251 | |
| 252 | --- |
| 253 | |
| 254 | ## Step 10 — Tag a Commit |
| 255 | |
| 256 | ```bash |
| 257 | muse tag add stage:rough-mix |
| 258 | muse tag list |
| 259 | ``` |
| 260 | |
| 261 | ``` |
| 262 | d5e6f7a8 stage:rough-mix |
| 263 | ``` |
| 264 | |
| 265 | --- |
| 266 | |
| 267 | ## Full Summary Table |
| 268 | |
| 269 | | Step | Operation | Result | |
| 270 | |---|---|---| |
| 271 | | 0 | Root commit | HEAD=a1b2c3d4 | |
| 272 | | 1 | Mainline commit | HEAD moves to b2c3d4e5 | |
| 273 | | 2 | Branch feature/keys | Diverges from Step 1 | |
| 274 | | 3 | Branch feature/drums | Also diverges from Step 1 | |
| 275 | | 4 | Merge both branches | Auto-merged, two-parent commit | |
| 276 | | 5 | Conflict merge | MERGE_STATE written; resolved manually | |
| 277 | | 6 | Cherry-pick | Single commit applied | |
| 278 | | 7 | Checkout traversal | HEAD detached, then restored | |
| 279 | | 8 | Revert | New commit undoing prior commit | |
| 280 | | 9 | Stash/pop | Working tree shelved and restored | |
| 281 | | 10 | Tag | Named reference on commit | |
| 282 | |
| 283 | --- |
| 284 | |
| 285 | ## What This Proves |
| 286 | |
| 287 | Every Muse primitive works over actual files on disk with zero external |
| 288 | dependencies (no database, no HTTP server, no Docker). The full lifecycle — |
| 289 | commit, branch, merge, conflict, revert, cherry-pick, stash, checkout, tag |
| 290 | — runs from a single `pip install` and a directory. |
| 291 | |
| 292 | The same lifecycle works identically for any domain that implements |
| 293 | `MuseDomainPlugin`. Swap `music` for `genomics` in `muse init --domain` |
| 294 | and the walkthrough above applies unchanged. |