gstree scans a workspace directory for Git repositories and shows their status as a compact tree.
projects
├── aurora [main] ~2 ?1
├── bonsai [main] +3 ~1
├── cedar [main] clean
│ └── roots [main] ↓2
└── drift [feat/glow] ~1 ↑1
- Tree view of all Git repos in a directory, including submodules
- Compact status tokens for staged, modified, untracked, ahead, and behind state
--dirtyflag to show only repositories with uncommitted changes- JSON output for downstream scripting
- Zero runtime dependencies beyond Python stdlib and
git - Built-in
--upgradeflow for publishedpipanduvinstalls plus source checkouts
| Token | Meaning |
|---|---|
+N |
N staged changes |
~N |
N modified tracked files |
?N |
N untracked files |
↑N |
N commits ahead of upstream |
↓N |
N commits behind upstream |
clean |
Nothing to do |
Published release (PyPI):
pip install gstreePublished release with uv tool install:
uv tool install gstreePublished release with uvx (no install):
uvx gstree ~/sourceFrom source (current checkout / unreleased main):
git clone https://github.com/tmsjngx0/gstree.git ~/.local/share/gstree
uv tool install ~/.local/share/gstree# Show all repos
gstree ~/source
# Show only repos with changes
gstree --dirty ~/source
# Fetch remotes before showing status
gstree --fetch ~/source
# JSON output for scripting
gstree --json ~/source
gstree -j ~/source
# Limit scan depth (default: 2)
gstree --depth 3 ~/source
# Check version
gstree --versionIf gstree was installed with pip install gstree, upgrade in place:
gstree --upgradeIf gstree was installed with uv tool install gstree, the same command delegates to uv tool upgrade gstree:
gstree --upgradeIf you run gstree via uvx, request the latest published version explicitly:
uvx gstree@latest ~/sourceFor source installs from a cloned checkout, gstree --upgrade pulls the repo and reinstalls the tool:
gstree --upgradeOverride the repo path with GSTREE_REPO_PATH if you cloned elsewhere:
GSTREE_REPO_PATH=/custom/path/gstree gstree --upgradeTagged releases publish to PyPI through GitHub Actions Trusted Publishing. Use the publish workflow's manual dispatch to test against TestPyPI before pushing a release tag.
See CONTRIBUTING.md.