check-projects

README

check-projects

A fast, cross-platform CLI tool to check the git status of multiple projects organized by categories.

Run check-projects to see which of your projects have uncommitted changes, are ahead of remote, or have other git status indicators.

Output Example

x mozilla
  * M firefox
  ✱ ✚ thunderbird

✔ godot

x gamedev
  ⬆ flying-ones
  * M avindi

Git Status Symbols

• ✔ - Clean (synced with remote)
• ⬆ - Ahead of remote
• ⬆⬆ - Diverged from remote
• * M - Modified files
• * D - Deleted files
• ✱ ✚ - Untracked files
• ❌ - Error

Features

• Multi-category organization: Group your projects by team, client, or any category
• Nested project discovery: Automatically scan nested folder structures
• Concurrent scanning: Fast parallel git status checks
• Flexible configuration: YAML-based config with local and global support
• Smart filtering: Hide clean projects by default, show only what needs attention
• Cross-platform: Single binary for macOS, Linux, and Windows

Installation

Quick Install (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/uralys/check-projects/main/install.sh | sh

This will download the latest release and install it to ~/.local/bin/check-projects.

show manual Installation

1. Download the latest release for your platform from GitHub Releases

2. Extract and install:

# macOS/Linux
tar -xzf check-projects-*.tar.gz
chmod +x check-projects
sudo mv check-projects /usr/local/bin/

# Or install to user directory (no sudo required)
mkdir -p ~/.local/bin
mv check-projects ~/.local/bin/
# Add ~/.local/bin to your PATH if not already done

# Windows (PowerShell as Administrator)
Move-Item check-projects.exe C:\Windows\System32\

From Source

git clone https://github.com/uralys/check-projects.git
cd check-projects
make install

Quick Start

1. Create a configuration file:

cp check-projects.example.yml ~/check-projects.yml

1. Edit ~/check-projects.yml to match your project structure

2. Run the tool:

check-projects

Configuration

Configuration files are searched in this order:

1. Path specified with --config flag
2. ./check-projects.yml (current directory)
3. ~/check-projects.yml (home directory)

Example Configuration

categories:
  # Mode 1: Explicit project list (using 'projects' field)
  # Use full paths to specific git repositories
  - name: core
    projects:
      - ~/fox
      - ~/cherry

  # Mode 2: Auto-scan directory (using 'root' field)
  # Recursively scans for all git repositories in the directory
  - name: godot
    root: ~/Projects/godot

  - name: uralys
    root: ~/Projects/uralys

Usage

# Check all projects
check-projects

# Show all projects including clean ones
check-projects --verbose
check-projects -v

# Check only specific category
check-projects --category gamedev

# Use custom config file
check-projects --config /path/to/config.yml

Development

# Install dependencies
make deps

# Run without building
make dev

# Build binary
make build

# Run tests
make test

# Build for all platforms
make release