nut 🔩

A workspace manager for working with multiple GitHub repositories simultaneously.

Overview

nut creates isolated workspaces for organizing and managing clones of GitHub repositories. The import command uses a local cache reduce cloning time to a minimum.

This package is experimental and not feature complete.

Installation

Cargo

Install cargo by following the instructions in the cargo book, then install the nut-workspace crate:

cargo install nut-workspace

Usage

nut --help

Create a workspace

nut create --description "Description of your workspace"

This creates a new workspace and starts a shell session within it.

List workspaces

nut list

Enter an existing workspace

nut enter <workspace-id>

Import GitHub repositories

Import a single repository:

nut import <owner>/<repository>

Import all repositories from a user:

nut import --user <username>

Import all repositories from an organization:

nut import --org <organization>

Parallelized import:

nut import --dry-run --org <organization> | xargs -n1 -P8 nut import

Nut will automatically discover a GitHub token if you have the official GitHub CLI gh installed and ran gh auth login before. It will respect other decisions you made when configuring gh, for instance will use the configured git clone protocol (ssh or http).

Status command

Check the status of all repositories in the workspace:

nut status

Apply command

Run a command across all repositories in the workspace:

nut apply git commit -m "fix: foo bar"

You can also run a script in each repository:

nut apply --script path/to/script.sh

Scripts must be executable (use chmod +x script.sh to make them executable).

You can pass arguments to scripts as well:

nut apply --script path/to/script.sh arg1 arg2

In case options for your script clash with nut options, use the double dash to tell nut to stop parsing options:

nut apply --script path/to/script.sh -- --option1 --option2

Other commands

• nut cache-dir - Print git cache directory path
• nut data-dir - Print data directory path that contains workspaces
• nut workspace-dir - Print absolute path to a specific workspace

Tutorial

Follow the tutorials to learn how you can use nut to manage changes across multiple repositories in your org.

How it works

nut maintains two directories:

• Cache directory: Stores bare git repositories as mirrors for fast cloning
• Data directory: Contains individual workspaces, each with their own repository clones

When importing repositories, nut first creates or updates a cached bare clone, then uses git clone --local to create fast workspace copies. Workspaces are identified by ULID timestamps. nut is smart and just knows when the cache repositories need updating.

Feedback

I've built nut for myself, but if you find it interesting and you feel like you would like it to behave differently, you're welcome to open a GitHub issue.

I'd also be happy if you simply reach out because you've found it helpful.

Development

Running Tests

The project includes integration tests that verify the CLI behavior:

cargo test

Building

cargo build --release

License

The code in this repository is licensed under the MIT license.

See the LICENSE file for details.