Unison Shareis Unison's own code hosting service. Unison's unique code format and tooling enables different strategies for remote repositories. We created Unison Share to support code hosting, library discovery, collaboration, source code viewing, and documentation rendering.
🏗️This document describes how to perform common interactions with Unison Share. We'll add more here as more functionality gets added to the platform.
Pushing and pulling code
First, You'll want to make sure you're logged in to the Unison Share platform. Run
auth.loginin the UCM locally.
This will open your default web browser and prompt you to log into Unison Share.
To push a project, use the
pushcommand from inside the project and branch you're hoping to share. This pushes the
mainbranch to @username/myProject/main.
To push a namespace, use the
pushcommand from inside the namespace you're hoping to share, or use a fully qualified name (one which starts with a dot,
.)as the second argument to the command.
.> push myUser.public.myCode .myCode
To bring a remote namespace into your local codebase, issue the
pullcommand in the UCM.
myProject> pull myUser.public.myProject.main .myProject
Library structure conventions
For the best experience hosting a library on Unison Share, we recommendcreating a projectwhere the
mainbranch represents the latest work in progress, feature branches are used for concurrent workstreams, and release branches or release drafts are snapshots of the
mainbranch at a given point in time.
myProject /main README ReleaseNotes lib dependencies /featureBranch -- fork of main /releases/draft/X.Y.Z -- snapshots of main
mainbranch of your project, located just under the project root, you should have a
libnamespace to contain your library's dependencies. Optionally you can include a
READMEdocumentat the root of your project code. If present, Unison Share will automatically render the README as the landing page of the project.
Another special document you can include at the root of your project is
ReleaseNotes,which will be rendered as the release notes for the latest release of your library. This is a good place to include information about how to upgrade from previous versions, or any other information you'd like to convey to users of your library. If Unison Share detects a
ReleaseNotesterm in your project, it will automatically render it as the release notes for the latest release of your library.
Consumers of your library hoping to obtain the most recent released version of the library would pull
@user/project/releases/X.Y.Z,whereas fellow maintainers would likely choose to
mainbranch to keep in sync with active development. Once a new release is ready, you can hit the "release" button in the Unison Share UI to create a release from
main.Read more about creating library releases here.
In Unison, a namespace is a mapping of names to their underlying definitions.
We often think of these names as forming a tree, much like a directory of files, and names are like file paths in this tree.