git-shadow

Run git commands against shadow repositories that live inside your working directory.

A shadow repo is a separate git repository checked out inside another project — useful for keeping vendored code, generated outputs, or loosely related projects alongside your main repo without making them submodules.

Installation

cargo install git-shadow

This installs the git-shad binary. Git automatically treats any git-<name> binary on your PATH as a subcommand, so it becomes available as git shad.

Configuration

Configuration is stored outside the project, under your OS config directory:

• Linux: $XDG_CONFIG_HOME/git-shadow, or ~/.config/git-shadow when XDG_CONFIG_HOME is not set
• macOS: ~/Library/Application Support/git-shadow
• Windows: %APPDATA%\git-shadow

git-shad identifies the current project from the nearest Git repository's remote.origin.url. The remote URL is normalized into a repo-shaped config path. For example, a parent repo with this origin:

git@github.com:andre-a-alves/git-shadow.git

uses this config file on Linux when XDG_CONFIG_HOME is not set:

~/.config/git-shadow/github.com/andre-a-alves/git-shadow/config.toml

The config file must use version 1:

version = 1

[shadows.foobar]
repo = "git@github.com:example/foobar.git"
mapping = ".vendor/foobar/"

• version — the config file version; currently only 1 is supported
• shadows.foobar — the nickname you use on the command line
• repo — the remote URL for the shadow repository
• mapping — path to the directory containing the shadow git repository, relative to the parent repo root

You can define as many [shadows.<nickname>] entries as you need.

Usage

git shad <shadow-name> <git-command> [args...]

git-shad finds the nearest Git repository, loads its OS config file, then runs the given git command inside the shadow's mapping directory. You can run it from anywhere inside your project.

# List branches of the shadow repo
git shad foobar branch

# Pull latest changes
git shad foobar pull

# View recent commits
git shad foobar log --oneline

# Check status
git shad foobar status

Any git command and its arguments are passed through as-is.

License

This project is licensed under either the MIT License or the Apache License, Version 2.0, at your option.