shadow-git

A secondary git repository for tracking files excluded from your main repo.

Shadow-git (sgit) creates a .sgit/ repository alongside your .git/ directory. Files tracked by sgit are invisible to your main git repo and vice versa. This is useful for personal notes, local configs, scratch files, or anything you want versioned but not in the main repo.

Installation

npm install -g shadow-git

Optionally, install shell completions (bash, zsh, or fish):

sgit track completion install

Quick Start

sgit track init                        # Initialize shadow repo
sgit track add notes/todo.md           # Start tracking a file
sgit track add --adopt config.local    # Move a main-git file to shadow tracking
sgit track list                        # List tracked paths
sgit status                            # Git status in shadow repo
sgit commit -m "update notes"          # Commit to shadow repo

Commands

| Command | Description | |---|---| | sgit track init | Initialize shadow repository | | sgit track clone <url> | Clone a shadow repository from a remote URL | | sgit track add <paths...> | Start shadow-tracking paths | | sgit track add --adopt <paths...> | Move main-git-tracked files to shadow tracking | | sgit track remove <paths...> | Stop shadow-tracking paths | | sgit track list | List all shadow-tracked paths | | sgit track sync | Regenerate exclude files from manifest | | sgit track verify | Validate staged files against manifest | | sgit track ignore <paths...> | Ignore paths within tracked directories | | sgit track unignore <paths...> | Stop ignoring paths within tracked directories | | sgit track destroy | Remove shadow repository entirely | | sgit track completion [install] | Print or install shell completion scripts |

Any non-track command is forwarded to git using the shadow repository (e.g. sgit status, sgit log, sgit diff).

How It Works

• .sgit/ — A git repository with core.worktree pointing to your project root
• .sgit.json — Manifest listing all shadow-tracked paths
• .git/info/exclude — Updated to hide shadow-tracked files from main git
• .sgit/info/exclude — Configured to only see shadow-tracked files
• Pre-commit hooks — Verify that staged files belong to the correct repository

License

MIT