manage-version.sh

Overview

This script enables users of sunbeam to easily switch between different versions of sunbeam; automatically managing the environments and the code branches/tags. This is the preferred way to manage versions of your local installation of sunbeam >=3.1.

Tip

This script was implemented in v3.1.0, so using it to switch to any prior versions will then require referring to the manual-version-management section to switch versions again.

The most common use case will be once you’ve had sunbeam installed for a while and new versions have come out, you can easily upgrade to the latest version by running ./manage-version.sh -s stable. This will update your code, install the newest environment, and then give you instructions for how to activate it.

Options

All available options for the command line, used with ./manage-version.sh [options].

-l/–list [arg]

List all [installed] or all [available] versions of sunbeam. The [installed] argument will search your local conda environments for the prefix ‘sunbeam’. The [available] argument will list available release tags and developement branches.

-a/–active

List environment for the code currently installed (active branch tag). I.e. this will get the current git tag and display the appropriate environment.

-c/–clean

Remove all auxiliary sunbeam conda environments. These will typically be stored in $SUNBEAM_DIR/.snakemake/ and can take up space, especially if you’re a developer and make changes to environment files often.

Tip

The next time running sunbeam after ./manage-version.sh --clean will take longer because it has to remake some of the cleaned environments.

-s/–switch [arg]

Switch to a new version of sunbeam (install if not installed). This version argument can be ‘dev’, ‘stable’, any other branch name, or any version tag. A list of available versions can be listed with ./manage-version.sh -l available.

-r/–remove [arg]

Uninstall the specified version of sunbeam. A list of installed versions can be shown with ./manage-version.sh -l installed.

-v/–verbose

Show subcommand output.

-d/–debug

Run in debug mode.

-h/–help

Display help message.

Manual Version Management

Sunbeam was developed to only need one installation and still support using any of its versions. The two tools you will need to understand in order to manually switch between sunbeam versions are git and conda. Git is used to switch between versions of the code while conda is used to switch between execution environments for that code.

Tip

This is the recommended method for developers of sunbeam. While the script provides useful utilities, it can become a nuisance if you’re making a lot of updates to the code as it will keep trying to make new environments when you switch.

As an example, let’s say you’ve just installed sunbeam following the quickstart guide. At this point you should have code that is on the ‘stable’ branch and an environment called something like ‘sunbeamX.X.X’. You can verify this by running git status and echo $CONDA_DEFAULT_ENV (provided your environment is activated).

But now you want to switch to the developement branch. The first step is to git checkout dev, switching your code to the dev branch. Next, run conda deactivate, deactivating your current environment, then to create the new ‘dev’ environment run, ./install.sh -e sunbeamX.X.X-dev (you can also use the proper env name given by git describe --tag but that will change will every commit). If the install script succeeds, it should finish by giving instructions on how to activate your new environment and you’re good to go.

Tip

Check out the code for manage-version.sh if you’re ever unsure of how to do something, it can be a good reference.