Projects FAQs


What happens to my existing namespaces hosted in Unison Share if they are not in a project?

They will continue to be hosted in Unison Share without changes, but if you want your library to be shown in the Catalog for others to use, you may want to migrate your namespace to a project. Follow this guide for migrating your namespace.

Do I have to write my Unison code within a project?

At present, you can still create free-form namespaces. You'll still need a lib directory for your dependencies, but you don't need to be in a project to write in Unison.

You really should use projects though. Our ecosystem will be moving towards projects as the primary way to organize and package code.

What's the difference between projects and namespaces?

Namespaces are used for organizing your source code whereas projects are for managing your code as a shareable package. Think about namespaces as a directory tree and projects as a git repository.

Can I create a project within a project?

No, you can only create projects at the root of your codebase.

How do projects relate to the codebase reflog history?

The global reflog history is currently not separated by projects. All your projects use the global reflog history, so if you are working on multiple projects at once, you should be careful when rewinding state in one project as it will effect interleaved work in other projects. In the future, we're interested in separating the reflog history by project.

How do I contribute to an organization's project as a member of the organization? Organizations are coming in the future! As a member of the organization, you'll be able to push to the main branch of the project but it's more common to create a feature branch for your work and merge it in. Currently, you can contribute to another persons project by cloning it and creating a contributor branch. See making a pull request for more details.

How do I get to the root of a project quickly? Is it still .?

Currently, . is the root of the codebase, not the project. We're still working on the syntax to get to root of the project. In the meantime, you can use up to go back up a level, or cd .. or back to get to the previous prompt location.

Can I push and pull from more than one remote branch?

Yes, one local branch can push and pull from many remote branches, but only one will be remembered by the UCM as the remote mapping shortcut.

How can I see all the remote contributor branches for my project from the UCM command line?

Currently, this is not possible. In the future we're hoping to add tab completion to the clone command so you can enter the name of the project or branch and quickly find a specific remote branch. However, you can see all the contributor branches from the project's homepage by navigating to the branch name dropdown.

Should I maintain both a namespace version of my library and a project version of my library?

Nope, no need to maintain both a namespace and a project version of your library in the long run. Projects are the way forward, so we're hoping folks will migrate to depending upon projects instead of namespaces.

How should I version my project?

We recommend you use a semantic versioning scheme with digits to represent major, minor, and patch versions. Currently, Unison Share enforces that new releases are greater than the last released version by exactly one major, minor, or patch version. If your existing versioning scheme is not expressed in this format, when you migrate to a project, pick 1.0.0 as your first release version and increment by one from there.

Support for hotfixes and pre-release versions is incoming.

How do I rename a branch or project on Unison share?

Renaming a remote branch or project is a forthcoming feature! Currently you can push your local project or branch to a new name and delete the old one.