diff --git a/unison-src/transcripts/help.md b/unison-src/transcripts/help.md index 7a2ffa290..79ffa1846 100644 --- a/unison-src/transcripts/help.md +++ b/unison-src/transcripts/help.md @@ -1,6 +1,6 @@ # Shows `help` output -```ucm:error +```ucm scratch/main> help scratch/main> help-topics scratch/main> help-topic filestatus diff --git a/unison-src/transcripts/help.output.md b/unison-src/transcripts/help.output.md index 2044217df..27a6d7489 100644 --- a/unison-src/transcripts/help.output.md +++ b/unison-src/transcripts/help.output.md @@ -846,13 +846,15 @@ scratch/main> help-topics remotes testcache - Example: use `help filestatus` to learn more about that topic. + Example: use `help-topics filestatus` to learn more about that topic. scratch/main> help-topic filestatus - Sorry, I wasn’t sure how to process your request. 📓 + 📓 + Here's a list of possible status messages you might see for definitions in a .u file. + needs update A definition with the same name as an existing definition. Doing `update` instead of `add` will turn this failure @@ -867,54 +869,60 @@ scratch/main> help-topic filestatus constructor that's named the same as an existing term. Rename that term or your constructor before trying again to `add` - or `update`. + or `update`. + blocked This definition was blocked because it dependended on a definition with a failed - status. + status. + extra dependency This definition was added because it was a dependency of a definition explicitly selected. - - You can run `help help-topic` for more information on using `help-topic` - `help-topics` lists all topics and `help-topics ` shows an explanation of that topic. scratch/main> help-topic messages.disallowedAbsolute - Sorry, I wasn’t sure how to process your request. 🤖 + 🤖 + Although I can understand absolute (ex: .foo.bar) or relative (ex: util.math.sqrt) references to existing definitions (help namespaces to learn more), I can't yet handle giving new definitions with absolute names in a .u file. + As a workaround, you can give definitions with a relative name temporarily (like `exports.blah.foo`) and then use `move.*`. - - You can run `help help-topic` for more information on using `help-topic` - `help-topics` lists all topics and `help-topics ` shows an explanation of that topic. scratch/main> help-topic namespaces - Sorry, I wasn’t sure how to process your request. 🧐 + 🧐 + There are two kinds of namespaces, absolute, such as (.foo.bar or .base.math.+) and relative, such as (math.sqrt or util.List.++). + Relative names are converted to absolute names by prepending the current namespace. For example, if your Unison prompt - reads: .foo.bar> and your .u file looks like: x = 41 + reads: + + .foo.bar> + + and your .u file looks like: + + x = 41 + then doing an add will create the definition with the absolute name .foo.bar.x = 41 + and you can refer to x by its absolute name .foo.bar.x elsewhere in your code. For instance: - answerToLifeTheUniverseAndEverything = .foo.bar.x + 1 - You can run `help help-topic` for more information on using `help-topic` - `help-topics` lists all topics and `help-topics ` shows an explanation of that topic. + answerToLifeTheUniverseAndEverything = .foo.bar.x + 1 scratch/main> help-topic projects - Sorry, I wasn’t sure how to process your request. A project is a versioned collection of code that can be edited, published, and depended on other projects. Unison projects are analogous to Git repositories. + project.create create a new project projects list all your projects branch create a new workstream @@ -924,40 +932,37 @@ scratch/main> help-topic projects push upload your changes to Unison Share pull download code(/changes/updates) from Unison Share clone download a Unison Share project or branch for contribution + Tip: Use `help project.create` to learn more. + For full documentation, see https://unison-lang.org/learn/projects - - You can run `help help-topic` for more information on using `help-topic` - `help-topics` lists all topics and `help-topics ` shows an explanation of that topic. scratch/main> help-topic remotes - Sorry, I wasn’t sure how to process your request. 🤖 + 🤖 + Local projects may be associated with at most one remote project on Unison Share. When this relationship is established, it becomes the default argument for a number of share commands. For example, running `push` or `pull` in a project with no arguments will push to or pull from the associated remote, if it exists. + This association is created automatically on when a project is created by `clone`. If the project was created locally then the relationship will be established on the first `push`. - - You can run `help help-topic` for more information on using `help-topic` - `help-topics` lists all topics and `help-topics ` shows an explanation of that topic. scratch/main> help-topic testcache - Sorry, I wasn’t sure how to process your request. 🎈 + 🎈 + Unison caches the results of test> watch expressions. Since these expressions are pure and always yield the same result when evaluated, there's no need to run them more than once! + A test is rerun only if it has changed, or if one of the definitions it depends on has changed. - - You can run `help help-topic` for more information on using `help-topic` - `help-topics` lists all topics and `help-topics ` shows an explanation of that topic. ``` We should add a command to show help for hidden commands also. diff --git a/unison-src/transcripts/input-parse-errors.output.md b/unison-src/transcripts/input-parse-errors.output.md index 35718aea3..ad6efd02d 100644 --- a/unison-src/transcripts/input-parse-errors.output.md +++ b/unison-src/transcripts/input-parse-errors.output.md @@ -8,12 +8,19 @@ x = 55 ```ucm scratch/main> add . - Sorry, I wasn’t sure how to process your request. 1:2: | 1 | . - | ^ unexpected end of input expecting '`' or operator (valid - characters: !$%&*+-/:<=>\^|~) +⚠️ + +Sorry, I wasn’t sure how to process your request. + + 1:2: + | + 1 | . + | ^ + unexpected end of input + expecting '`' or operator (valid characters: !$%&*+-/:<=>\^|~) - You can run `help add` for more information on using `add` - `add` adds to the codebase all the definitions from the most recently typechecked file. + +You can run `help add` for more information on using `add`. scratch/main> ls @@ -57,16 +64,14 @@ aliasMany: skipped -- similar to `add` ```ucm scratch/main> update arg - Sorry, I wasn’t sure how to process your request. I expected - no arguments, but received 1. - - You can run `help update` for more information on using `update` - Adds everything in the most recently typechecked file to the - namespace, replacing existing definitions having the same - name, and attempts to update all the existing dependents - accordingly. If the process can't be completed - automatically, the dependents will be added back to the - scratch file for your review. +⚠️ + +Sorry, I wasn’t sure how to process your request. + + I expected no arguments, but received 1. + +You can run `help update` for more information on using +`update`. ``` aliasTerm diff --git a/unison-src/transcripts/merge.md b/unison-src/transcripts/merge.md index d2f1105a2..f95175689 100644 --- a/unison-src/transcripts/merge.md +++ b/unison-src/transcripts/merge.md @@ -3,7 +3,7 @@ The `merge` command merges together two branches in the same project: the current branch (unspecificed), and the target branch. For example, to merge `topic` into `main`, switch to `main` and run `merge topic`: -```ucm:error +```ucm .> help merge .> help merge.commit ``` diff --git a/unison-src/transcripts/merge.output.md b/unison-src/transcripts/merge.output.md index 46280da17..63a4f852b 100644 --- a/unison-src/transcripts/merge.output.md +++ b/unison-src/transcripts/merge.output.md @@ -6,26 +6,22 @@ branch. For example, to merge `topic` into `main`, switch to `main` and run `mer ```ucm .> help merge - Sorry, I wasn’t sure how to process your request. merge + merge `merge /branch` merges `branch` into the current branch - - You can run `help help` for more information on using `help` - `help` shows general help and `help ` shows help for one command. .> help merge.commit - Sorry, I wasn’t sure how to process your request. merge.commit - (or commit.merge) + merge.commit (or commit.merge) `merge.commit` merges a temporary branch created by the `merge` command back into its parent branch, and removes the temporary branch. - For example, if you've done `merge topic` from main, then - `merge.commit` is equivalent to doing * switch /main * - merge /merge-topic-into-main * - delete.branch /merge-topic-into-main - You can run `help help` for more information on using `help` - `help` shows general help and `help ` shows help for one command. + For example, if you've done `merge topic` from main, then + `merge.commit` is equivalent to doing + + * switch /main + * merge /merge-topic-into-main + * delete.branch /merge-topic-into-main ``` Let's see a simple unconflicted merge in action: Alice (us) and Bob (them) add different terms. The merged result diff --git a/unison-src/transcripts/pull-errors.output.md b/unison-src/transcripts/pull-errors.output.md index 13731c20f..14ca55ad6 100644 --- a/unison-src/transcripts/pull-errors.output.md +++ b/unison-src/transcripts/pull-errors.output.md @@ -12,69 +12,32 @@ test/main> pull @aryairani/test-almost-empty/main lib.base_latest test/main> pull @aryairani/test-almost-empty/main a.b - Sorry, I wasn’t sure how to process your request. I think you - want to merge @aryairani/test-almost-empty/main into the a.b - namespace, but the `pull` command only supports merging into - the top level of a local project branch. - - You can run `help pull` for more information on using `pull` - The `pull` command merges a remote namespace into a local - branch - - `pull @unison/base/main` merges the branch - `main` of the Unison - Share hosted project - `@unison/base` into - the current branch - `pull @unison/base/main my-base/topic` merges the branch - `main` of the Unison - Share hosted project - `@unison/base` into - the branch `topic` - of the local - `my-base` project - - where `remote` is a project or project branch, such as: - Project (defaults to the /main branch) `@unison/base` - Project Branch `@unison/base/feature` - Contributor Branch `@unison/base/@johnsmith/feature` - Project Release `@unison/base/releases/1.0.0` +⚠️ + +Sorry, I wasn’t sure how to process your request. + + I think you want to merge @aryairani/test-almost-empty/main + into the a.b namespace, but the `pull` command only supports + merging into the top level of a local project branch. + +You can run `help pull` for more information on using `pull`. test/main> pull @aryairani/test-almost-empty/main a - I think you're wanting to merge - @aryairani/test-almost-empty/main into the a branch, but it - doesn't exist. If you want, you can create it with - `branch.empty a`, and then `pull` again. + I think you want to merge @aryairani/test-almost-empty/main + into the a branch, but it doesn't exist. If you want, you can + create it with `branch.empty a`, and then `pull` again. test/main> pull @aryairani/test-almost-empty/main .a - Sorry, I wasn’t sure how to process your request. I think you - want to merge @aryairani/test-almost-empty/main into the .a - namespace, but the `pull` command only supports merging into - the top level of a local project branch. - - You can run `help pull` for more information on using `pull` - The `pull` command merges a remote namespace into a local - branch - - `pull @unison/base/main` merges the branch - `main` of the Unison - Share hosted project - `@unison/base` into - the current branch - `pull @unison/base/main my-base/topic` merges the branch - `main` of the Unison - Share hosted project - `@unison/base` into - the branch `topic` - of the local - `my-base` project - - where `remote` is a project or project branch, such as: - Project (defaults to the /main branch) `@unison/base` - Project Branch `@unison/base/feature` - Contributor Branch `@unison/base/@johnsmith/feature` - Project Release `@unison/base/releases/1.0.0` +⚠️ + +Sorry, I wasn’t sure how to process your request. + + I think you want to merge @aryairani/test-almost-empty/main + into the .a namespace, but the `pull` command only supports + merging into the top level of a local project branch. + +You can run `help pull` for more information on using `pull`. ```