Souko is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install souko

It will make the souko command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall souko uninstalls.

Adding `souko` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add souko

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

souko = "0.2.2"

The souko library will be automatically available globally. Read the souko library documentation.

Back to the crate overview.

Readme

souko

Souko is a simple command line utility that provides an easy way to organize clones of remote git repositories.

VS Code extension souko-vscode is also available.

When you clone a remote repository with souko, souko creates a directory under a specific root directory (~/.local/share/souko/root by default) containing the hostname and path of the remote repository's URL.

$ souko clone https://github.com/gifnksm/souko
# => creates local clone at ~/.local/share/souko/root/github.com/gifnksm/souko

You can also list all repositories that have been cloned.

$ souko list
# => list of absolute paths of all repositories cloned with souko

By combining souko, fuzzy finder, and shell functions, you can easily jump between repositories (TODO: add shell script example).

Configuration

Configuration is done via a TOML file located at ~/.config/souko/config.toml by default.

[[root]]
name = "default"
path = "~/.local/share/souko/root"

[[root]]
name = "repos"
path = "~/repos"

[query]
default_scheme = "github"

[query.scheme_alias]
gh = "github"
gl = "gitlab"

[query.custom_scheme]
github = "https://github.com/{path}.git"
gitlab = "https://gitlab.com/{path}.git"

Installation

There are multiple ways to install souko. Choose any one of the methods below that best suits your needs.

Distribution packages

Following packages are available:

Arch Linux (AUR): souko or souko-bin

Pre-built binaries

Executable binaries are available for download on the GitHub Release page.

You can also install the binary with cargo-binstall command.

# Install pre-built binary
$ cargo binstall souko

Build from source using Rust

To build souko executable from the source, you must have the Rust toolchain installed. To install the rust toolchain, follow this guide.

Once you have installed Rust, the following command can be used to build and install souko:

# Install released version
$ cargo install souko

# Install latest version
$ cargo install --git https://github.com/gifnksm/souko.git souko

Minimum supported Rust version (MSRV)

The minimum supported Rust version is Rust 1.78.0. At least the last 3 versions of stable Rust are supported at any given time.

While a crate is a pre-release status (0.x.x) it may have its MSRV bumped in a patch release. Once a crate has reached 1.x, any MSRV bump will be accompanied by a new minor version.

License

This project is licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

See CONTRIBUTING.md.

Installing the command-line executable

Adding souko library as a dependency

Adding `souko` library as a dependency