Skip to content

README.md

Latest commit

 

History

History
155 lines (107 loc) · 3.54 KB

README.md

File metadata and controls

155 lines (107 loc) · 3.54 KB

git-submodules-tui

npm version License: MIT

Interactive terminal UI for managing Git repositories with submodules. Built with Ink.

Features

  • 📊 Visual Status Dashboard - See all repos and submodules at a glance
  • 🎨 4 Color Themes - Dark, Light, Nord, and Minimal
  • ⌨️ Vim-style Navigation - hjkl or arrow keys
  • 🔄 Auto-refresh - Real-time updates every 2 seconds
  • 🎯 Status Indicators - Visual icons for clean/dirty/conflicts
  • 📈 Tracking Info - Ahead/behind commit counts
  • 🚀 Fast - Built with React/Ink for smooth performance

Installation

NPM Global Install (Recommended)

npm install -g git-submodules-tui

Zsh Plugin

Part of the git-submodules Oh My Zsh plugin:

git clone https://github.com/adishM98/git-submodules.git ~/.oh-my-zsh/custom/plugins/git-submodules
# Add 'git-submodules' to plugins in ~/.zshrc

Requirements

  • Node.js 14 or higher
  • zsh shell
  • Git 2.0 or higher

Usage

Navigate to any git repository with submodules:

cd /path/to/repo/with/submodules
gsm-tui

Keyboard Shortcuts

  • ↑ / k - Move selection up
  • ↓ / j - Move selection down
  • r - Refresh data manually
  • t - Cycle themes (dark → light → nord → minimal)
  • h / ? - Toggle help panel
  • q / Esc - Quit

Display

The TUI shows:

  • Repository tree - Base repository + all submodules
  • Branch information - Current branch per repository
  • Status icons:
    • ✓ Clean (no changes)
    • ● Dirty (uncommitted changes)
    • ✗ Conflicts
  • Change counts - Staged + unstaged + untracked files
  • Tracking indicators:
    • ▲3 Ahead by 3 commits
    • ▼2 Behind by 2 commits

Themes

Press t to cycle through themes:

  • Dark - Bright colors on dark background (default)
  • Light - Dark colors on light background
  • Nord - Nord color palette
  • Minimal - Monochrome ASCII-only

Troubleshooting

"bridge.zsh not found"

Ensure you installed via npm or the zsh plugin method:

npm uninstall -g git-submodules-tui
npm install -g git-submodules-tui

"zsh is required"

Install zsh:

"Not a git repository"

Make sure you're in a git repository:

git status
# Should not show "fatal: not a git repository"

Development

git clone https://github.com/adishM98/git-submodules.git
cd git-submodules/tui
npm install
npm run dev

Build

npm run build

Test Locally

npm link
gsm-tui

Related Projects

This TUI is part of the larger git-submodules Oh My Zsh plugin, which provides:

  • 25+ git submodule commands
  • Smart commit message generation
  • Parallel operations
  • Interactive branch management
  • And much more

License

MIT © adishM98

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support