mistletoe

Mistletoe is a command-line tool for managing multiple Git repositories using a central JSON configuration file. It simplifies operations like cloning, switching branches, status checking, and syncing across multiple projects concurrently.

This project provides two binaries:

mstl: The core tool for standard Git operations (init, status, switch, push, sync, snapshot, reset, fire).
mstl-gh: An extended version that includes all mstl features plus GitHub integration (via gh CLI) for managing Pull Requests across multiple repositories.

Installation

You can install mistletoe via Homebrew:

brew tap keiji/tap
brew install mistletoe

How to build

This project requires Go 1.24.3 or higher.

To build the project, run:

go build -v ./...

This will produce the mstl and mstl-gh binaries in the cmd/mstl and cmd/mstl-gh directories respectively (or in your current directory depending on your go environment setup, e.g. go build -o mstl ./cmd/mstl and go build -o mstl-gh ./cmd/mstl-gh).

Configuration File Format

The core of Mistletoe is the configuration file (usually config.json) containing a list of repositories.

Example config.json:

{
  "jobs": 4,
  "repositories": [
    {
      "url": "https://github.com/example/repo1.git",
      "branch": "main",
      "id": "my-repo-1"
    },
    {
      "url": "https://github.com/example/repo2.git",
      "revision": "a1b2c3d4",
      "branch": "feature/new-ui",
      "base-branch": "develop"
    }
  ]
}

jobs (Optional): The default number of concurrent jobs to use.
url (Required): The remote URL of the Git repository.
id (Optional): The directory name to clone into. If omitted, the name is derived from the URL.
branch (Optional): The branch to checkout or switch to.
revision (Optional): A specific commit hash to checkout (primarily used by init and reset).
base-branch (Optional): The base branch for Pull Requests and reset operations. If omitted, it defaults to the value of branch.

Usage

Both mstl and mstl-gh follow the same basic usage pattern:

mstl <command> [options] [arguments]
mstl-gh <command> [options] [arguments]

Global options for most commands:

-f, --file <path>: Path to the configuration file (e.g., config.json).
-j, --jobs <int>: Number of concurrent jobs to use (default: 1, or value from config).
-y, --yes: Automatically answer "yes" to all prompts.
-v, --verbose: Enable verbose output (shows executed git/gh commands).

Configuration loading priority:

Standard Input (stdin): If standard input is provided, it takes precedence over any file specified.
File Option: If standard input is not provided and -f / --file is specified, the file is used.
Default: If neither is specified, .mstl/config.json is used.

Example using pipe (prioritized over file):

cat config.json | mstl init

If you have Base64 encoded input, decode it before piping:

echo "Base64String" | base64 -d | mstl init

Common Commands (`mstl` & `mstl-gh`)

`init`

Initializes repositories defined in the configuration file. It clones repositories if they don't exist and checks out the specified revision or branch.

Usage:

mstl init -f <config_file> [options]

Options:

--dest <path>: Destination directory (default: current directory).
--dependencies <path>: Path to a Markdown file containing a Mermaid dependency graph.
--depth <int>: Create a shallow clone with a history truncated to the specified number of commits.
-j, --jobs <int>: Number of concurrent jobs to use (default: 1).
-y, --yes: Automatically answer "yes" to all prompts (e.g. parent config confirmation).
-v, --verbose: Enable verbose output.

`status`

Displays a status table for all configured repositories, showing the current branch, remote status, and synchronization state.

Usage:

mstl status -f <config_file> [options]

Options:

-j, --jobs <int>: Number of concurrent jobs to use (default: 1).
-y, --yes: Automatically answer "yes" to all prompts.
-v, --verbose: Enable verbose output.

Status Indicators:

> (Green): Local branch has unpushed commits.
< (Yellow): Remote branch has updates (pullable, fast-forward/merge).
! (Yellow): Remote branch has updates, but there are conflicts.
-: Clean (synchronized).

`push`

Checks for unpushed commits in all repositories and pushes them to the remote origin. It prompts for confirmation before executing the push.

Usage:

mstl push -f <config_file> [options]

Options:

-j, --jobs <int>: Number of concurrent jobs to use (default: 1).
-y, --yes: Automatically answer "yes" to all prompts (skip confirmation).
-v, --verbose: Enable verbose output.

`sync`

Updates repositories by pulling changes from the remote origin.

If conflicts are detected in any repository, the process aborts.
If updates are available, it prompts the user to choose a strategy: merge, rebase, or abort.

Usage:

mstl sync -f <config_file> [options]

Options:

-j, --jobs <int>: Number of concurrent jobs to use (default: 1).
-y, --yes: Skip strategy prompt and use default (merge).
-v, --verbose: Enable verbose output.

`switch`

Switches the active branch for all configured repositories. It verifies that the branch exists (or can be created) in all repositories before performing the switch.

Usage:

# Switch to an existing branch
mstl switch -f <config_file> [options] <branch_name>

# Create and switch to a new branch
mstl switch -f <config_file> -c <branch_name>

Options:

-c, --create <branch_name>: Create a new branch with the specified name and switch to it.
-j, --jobs <int>: Number of concurrent jobs to use (default: 1).
-y, --yes: Automatically answer "yes" to all prompts.
-v, --verbose: Enable verbose output.

`reset`

Resets the current branch to the specific target defined in the configuration. The target is resolved in the following priority:

revision (Commit Hash)
base-branch
branch

It performs a mixed reset, meaning changes in the working directory are preserved.

Usage:

mstl reset -f <config_file> [options]

Options:

-j, --jobs <int>: Number of concurrent jobs to use (default: 1).
-y, --yes: Automatically answer "yes" to all prompts (skip confirmation).
-v, --verbose: Enable verbose output.

`fire`

Emergency Backup. Immediately stages, commits, and pushes all changes in all repositories to a unique branch. This command is designed for emergency situations (e.g., machine failure) to save work quickly.

It searches for the configuration file in the current or parent directories.
It creates branches named mstl-fire-[repo]-[user]-[uuid].
It commits with --no-gpg-sign to avoid prompt delays.
It runs without confirmation prompts.

Usage:

mstl fire

`snapshot`

Scans the current directory for subdirectories that are Git repositories and generates a configuration file representing the current state (URL, Branch/Revision).

Usage:

mstl snapshot [options]

Options:

-o, --output-file <path>: Path for the output configuration file. (Default: mistletoe-snapshot-[id].json)
-f, --file <path>: Optional configuration file path. Used to resolve the base-branch field in the generated snapshot.
-j, --jobs <int>: Number of concurrent jobs to use (default: 1).
-v, --verbose: Enable verbose output.

`version`

Prints the version of the tool and the path to the git executable being used.

Usage:

mstl version

`help`

Shows usage information and the list of available commands.

Usage:

mstl help

GitHub Extension Commands (`mstl-gh` Only)

The mstl-gh binary includes all the commands above, plus the pr command for managing Pull Requests.

`pr create`

Creates Pull Requests for all repositories defined in the configuration file.

It checks for unpushed commits and pushes them.
It creates a PR targeting the configured base branch (or default).
It generates a snapshot of the current state and appends it to the PR body.
It cross-references other PRs created in the same batch.

Usage:

mstl-gh pr create -f <config_file> [options]

Options:

-t, --title <string>: Title of the Pull Request.
-b, --body <string>: Body content of the Pull Request.
--dependencies <path>: Path to a Markdown file containing a Mermaid dependency graph.
--draft: Create the Pull Request as a draft if supported by the repository.
-w, --overwrite: Overwrite existing Pull Request description if creator matches or forced.
-j, --jobs <int>: Number of concurrent jobs to use (default: 1).
-y, --yes: Automatically answer "yes" to all prompts.
-v, --verbose: Enable verbose output.
If title/body are omitted, the default editor is opened.

If --dependencies is provided, the graph content is embedded in the PR body (hidden in a details block with a Mermaid preview), and related PRs are categorized based on the graph.

Example dependencies file (dependency-graph.md):

```mermaid
graph TD
    repo-a --> repo-b
    repo-b --> repo-c
    repo-a -.-> repo-c
```

Visualization:

graph TD
    repo-a --> repo-b
    repo-b --> repo-c
    repo-a -.-> repo-c

You can define dependencies as a Mermaid graph.

`pr update`

Updates existing Pull Requests (Open or Draft) for the configured repositories.

It pushes any unpushed commits if the local branch is ahead of remote.
It updates the Mistletoe block (snapshot and dependency graph) in the PR description.
It does not create new Pull Requests.
It aborts if any repository is behind remote or has conflicts.

Usage:

mstl-gh pr update -f <config_file> [options]

Options:

--dependencies <path>: Path to a Markdown file containing a Mermaid dependency graph.
-w, --overwrite: Overwrite existing Pull Request description if creator matches or forced.
-j, --jobs <int>: Number of concurrent jobs to use (default: 1).
-y, --yes: Automatically answer "yes" to all prompts.
-v, --verbose: Enable verbose output.

`pr checkout`

Restores the state of repositories based on the snapshot embedded in a Mistletoe-managed Pull Request.

It parses the Mistletoe block from the PR body.
It clones missing repositories and checks out the recorded branches or revisions.
It saves the configuration from the snapshot to .mstl/config.json.

Usage:

mstl-gh pr checkout -u <PR_URL> [options]

Options:

-u, --url <string>: The URL of the Pull Request containing the snapshot (Required).
--dest <path>: Destination directory (default: current directory).
--depth <int>: Create a shallow clone with a history truncated to the specified number of commits.
-j, --jobs <int>: Number of concurrent jobs to use (default: 1).
-y, --yes: Automatically answer "yes" to all prompts.
-v, --verbose: Enable verbose output.

`pr status`

Displays the status of Pull Requests associated with the current branches of the configured repositories.

Usage:

mstl-gh pr status -f <config_file> [options]

Options:

-j, --jobs <int>: Number of concurrent jobs to use (default: 1).
-v, --verbose: Enable verbose output.

Manual Tests

This project includes a suite of interactive manual tests for verifying functionality, especially GitHub integration (mstl-gh), in a safe, isolated environment.

These tests are located in the manual_tests/ directory.

For detailed instructions on how to run these tests, including how to build the Docker image with pre-configured authentication, please refer to manual_tests/README.md.

License

Copyright 2025-2026 ARIYAMA Keiji

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Name		Name	Last commit message	Last commit date
Latest commit History 900 Commits
.github		.github
cmd		cmd
docs		docs
internal		internal
manual_tests		manual_tests
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
VERSION		VERSION
go.mod		go.mod
go.sum		go.sum
revive.toml		revive.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

mistletoe

Installation

How to build

Configuration File Format

Usage

Common Commands (`mstl` & `mstl-gh`)

`init`

`status`

`push`

`sync`

`switch`

`reset`

`fire`

`snapshot`

`version`

`help`

GitHub Extension Commands (`mstl-gh` Only)

`pr create`

`pr update`

`pr checkout`

`pr status`

Manual Tests

License

About

Uh oh!

Releases 7

Contributors 3

Uh oh!

Languages

License

keiji/mistletoe

Folders and files

Latest commit

History

Repository files navigation

mistletoe

Installation

How to build

Configuration File Format

Usage

Common Commands (mstl & mstl-gh)

init

status

push

sync

switch

reset

fire

snapshot

version

help

GitHub Extension Commands (mstl-gh Only)

pr create

pr update

pr checkout

pr status

Manual Tests

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 7

Contributors 3

Uh oh!

Languages

Common Commands (`mstl` & `mstl-gh`)

`init`

`status`

`push`

`sync`

`switch`

`reset`

`fire`

`snapshot`

`version`

`help`

GitHub Extension Commands (`mstl-gh` Only)

`pr create`

`pr update`

`pr checkout`

`pr status`