South

South is a tool for managing dependencies in multiple Git repositories for your project. This tool was inspired in parts by Zephyr RTOS's west, albeit much simpler and agnostic to what the project is for.

Concepts

A south workspace is a directory that contains your main project repository alongside all of its dependency repositories. Your main project repository contains a south.yaml manifest file that describes the dependency repositories.

my-workspace/                    <- workspace root
    my-project/                  <- project repo (contains south.yaml)
        south.yaml
    avrman/                      <- dependency repo
    libs/
        some-lib/                <- dependency repo with custom path

The workspace root is the parent directory of your project repository. South clones dependency repos into the workspace root by name, or at a custom path if specified in the manifest.

Usage

The Manifest (south.yaml)

repos:
  - name: avrman
    url: git@github.com:stephenkingston/avrman.git
    revision: main
  - name: some-lib
    url: https://github.com/example/lib.git
    revision: v1.2.3
    path: libs/some-lib

Each entry has:

• name — directory name for the repository
• url — git remote URL (SSH or HTTPS)
• revision — branch, tag, or commit hash to checkout
• path — (optional) custom clone path relative to workspace root

south new

Create a new south workspace with a fresh south.yaml manifest:

south new                              # create in current directory
south new -p /path/to/my-project       # create in given directory

south init

Initialize a south workspace from an existing project directory that already contains a south.yaml:

south init                              # use current directory
south init -p /path/to/existing-project

south add-repo

Add a repository dependency. Clones the repository and updates your manifest:

south add-repo -u git@github.com:user/repo.git

south clone

Clone an existing south project from a remote URL and fetch all its dependencies:

south clone -u git@github.com:user/project.git

south update

Update all dependency repositories to the revision specified in south.yaml. Clones repos that don't exist yet, fetches and checks out existing ones:

south update

south for-all

Run a shell command across all repositories (including the project repo):

south for-all -c "git status"
south for-all -c "git pull"

south config

Manage registered south workspaces. South stores workspace registrations in a config file so it knows which workspace is active:

south config list                # list all workspaces ([*] = active)
south config set-active -n foo   # switch active workspace
south config remove -n foo       # remove a workspace registration
south config show-config-path    # show config file location

Building

cargo build
cargo install --path .