From 384083e190a8e1896c113e81212d2e623413e5f8 Mon Sep 17 00:00:00 2001 From: Chris Penner Date: Thu, 27 Jun 2024 10:25:16 -0700 Subject: [PATCH] Revive strangely deleted bits of merge.md --- unison-src/transcripts/merge.md | 137 ++++++++++++++++++ unison-src/transcripts/merge.output.md | 188 +++++++++++++++++++++++++ 2 files changed, 325 insertions(+) diff --git a/unison-src/transcripts/merge.md b/unison-src/transcripts/merge.md index c2c632c03..66f2497e8 100644 --- a/unison-src/transcripts/merge.md +++ b/unison-src/transcripts/merge.md @@ -928,6 +928,143 @@ We will resolve this situation automatically in a future version. project/main> builtins.mergeio lib.builtins ``` +```ucm:hide +project/main> branch alice +``` + +Alice's additions: +```unison:hide +unique type Foo = Bar + +alice : Foo -> Nat +alice _ = 18 +``` + +```ucm:hide +project/alice> add +project/main> branch bob +``` + +Bob's additions: +```unison:hide +unique type Foo = Bar + +bob : Foo -> Nat +bob _ = 19 +``` + +```ucm:hide +project/bob> add +``` + +```ucm:error +project/alice> merge bob +``` + +```ucm:hide +.> project.delete project +``` + +## `merge.commit` example (success) + +After merge conflicts are resolved, you can use `merge.commit` rather than `switch` + `merge` + `branch.delete` to +"commit" your changes. + +```ucm:hide +.> project.create-empty project +project/main> builtins.mergeio lib.builtins +``` + +Original branch: +```unison:hide +foo : Text +foo = "old foo" +``` + +```ucm:hide +project/main> add +project/main> branch alice +``` + +Alice's changes: +```unison:hide +foo : Text +foo = "alices foo" +``` + +```ucm:hide +project/alice> update +project/main> branch bob +``` + +Bob's changes: + +```unison:hide +foo : Text +foo = "bobs foo" +``` + +Attempt to merge: + +```ucm:hide +project/bob> update +``` +```ucm:error +project/alice> merge /bob +``` + +Resolve conflicts and commit: + +```unison +foo : Text +foo = "alice and bobs foo" +``` + +```ucm +project/merge-bob-into-alice> update +project/merge-bob-into-alice> merge.commit +project/alice> view foo +project/alice> branches +``` + +```ucm:hide +.> project.delete project +``` + +## `merge.commit` example (failure) + +`merge.commit` can only be run on a "merge branch". + +```ucm:hide +.> project.create-empty project +project/main> builtins.mergeio lib.builtins +``` + +```ucm +project/main> branch topic +``` + +```ucm:error +project/topic> merge.commit +``` + +```ucm:hide +.> project.delete project +``` + + +## Precondition violations + +There are a number of conditions under which we can't perform a merge, and the user will have to fix up the namespace(s) manually before attempting to merge again. + +### Conflicted aliases + +If `foo` and `bar` are aliases in the nearest common ancestor, but not in Alice's branch, then we don't know whether to update Bob's dependents to Alice's `foo` or Alice's `bar` (and vice-versa). + +```ucm:hide +project/main> builtins.mergeio lib.builtins +``` + Original branch: ```unison:hide foo : Nat diff --git a/unison-src/transcripts/merge.output.md b/unison-src/transcripts/merge.output.md index 1207a123c..258413502 100644 --- a/unison-src/transcripts/merge.output.md +++ b/unison-src/transcripts/merge.output.md @@ -1030,6 +1030,194 @@ which is a parse error. We will resolve this situation automatically in a future version. +Alice's additions: +```unison +unique type Foo = Bar + +alice : Foo -> Nat +alice _ = 18 +``` + +Bob's additions: +```unison +unique type Foo = Bar + +bob : Foo -> Nat +bob _ = 19 +``` + +```ucm +project/alice> merge bob + + I couldn't automatically merge project/bob into project/alice. + However, I've added the definitions that need attention to the + top of scratch.u. + + When you're done, you can run + + merge.commit + + to merge your changes back into alice and delete the temporary + branch. Or, if you decide to cancel the merge instead, you can + run + + delete.branch /merge-bob-into-alice + + to delete the temporary branch and switch back to alice. + +``` +```unison:added-by-ucm scratch.u +-- project/alice +type Foo + = Bar + +-- project/bob +type Foo + = Bar + +-- The definitions below are not conflicted, but they each depend on one or more +-- conflicted definitions above. + +alice : Foo -> Nat +alice _ = 18 + +bob : Foo -> Nat +bob _ = 19 + + +``` + +## `merge.commit` example (success) + +After merge conflicts are resolved, you can use `merge.commit` rather than `switch` + `merge` + `branch.delete` to +"commit" your changes. + +Original branch: +```unison +foo : Text +foo = "old foo" +``` + +Alice's changes: +```unison +foo : Text +foo = "alices foo" +``` + +Bob's changes: + +```unison +foo : Text +foo = "bobs foo" +``` + +Attempt to merge: + +```ucm +project/alice> merge /bob + + I couldn't automatically merge project/bob into project/alice. + However, I've added the definitions that need attention to the + top of scratch.u. + + When you're done, you can run + + merge.commit + + to merge your changes back into alice and delete the temporary + branch. Or, if you decide to cancel the merge instead, you can + run + + delete.branch /merge-bob-into-alice + + to delete the temporary branch and switch back to alice. + +``` +```unison:added-by-ucm scratch.u +-- project/alice +foo : Text +foo = "alices foo" + +-- project/bob +foo : Text +foo = "bobs foo" + + +``` + +Resolve conflicts and commit: + +```unison +foo : Text +foo = "alice and bobs foo" +``` + +```ucm + + Loading changes detected in scratch.u. + + I found and typechecked these definitions in scratch.u. If you + do an `add` or `update`, here's how your codebase would + change: + + ⍟ These new definitions are ok to `add`: + + foo : Text + +``` +```ucm +project/merge-bob-into-alice> update + + Okay, I'm searching the branch for code that needs to be + updated... + + Done. + +project/merge-bob-into-alice> merge.commit + + I fast-forward merged project/merge-bob-into-alice into + project/alice. + +project/alice> view foo + + foo : Text + foo = "alice and bobs foo" + +project/alice> branches + + Branch Remote branch + 1. alice + 2. bob + 3. main + +``` +## `merge.commit` example (failure) + +`merge.commit` can only be run on a "merge branch". + +```ucm +project/main> branch topic + + Done. I've created the topic branch based off of main. + + Tip: To merge your work back into the main branch, first + `switch /main` then `merge /topic`. + +``` +```ucm +project/topic> merge.commit + + It doesn't look like there's a merge in progress. + +``` +## Precondition violations + +There are a number of conditions under which we can't perform a merge, and the user will have to fix up the namespace(s) manually before attempting to merge again. + +### Conflicted aliases + +If `foo` and `bar` are aliases in the nearest common ancestor, but not in Alice's branch, then we don't know whether to update Bob's dependents to Alice's `foo` or Alice's `bar` (and vice-versa). + Original branch: ```unison foo : Nat