# 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`)

```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 .
```
