🎯 The Problem

You're about to start coding. You open your project, dive into the code, make changes... then realize you forgot to git pull. Now you're dealing with merge conflicts, rebasing headaches, and lost time. Sound familiar?

When you're juggling multiple projects, working across different machines, or collaborating with a team, keeping every repository up-to-date becomes a mental burden. One forgotten git pull can derail your entire workflow.

✨ The Solution

Gitty Up is your automated Git guardian. Point it at your projects directory, and it intelligently scans every repository, pulling the latest changes while keeping your work safe. It documents everything it does, so you always know exactly what changed. No more forgotten pulls. No more merge conflict surprises. No more wondering what happened. Just smooth, up-to-date repositories ready for action—with complete accountability.

Think of it as your morning coffee routine for your codebase—one command, and everything's fresh, safe, and fully documented.

🚀 Features

📦 Installation

Prerequisites

• Python 3.13+ installed on your system
• Git available in your PATH
• uv package manager (recommended) or pip

Method 1: Install from PyPI (Recommended) ⭐

Install directly from PyPI as a global CLI tool—no virtual environment needed!

# Install as a global tool with uv
uv tool install gittyup

# That's it! Use from anywhere without activating venv
gittyup --version

Benefits: ✅ No venv activation • ✅ Available system-wide • ✅ Isolated environment • ✅ Easy updates

Method 2: Install from Source

For development or contributing to the project:

# Clone and navigate to the project
git clone https://github.com/mikeckennedy/gittyup
cd gittyup

# Install in editable mode with uv
uv tool install --editable .

⚡ Quick Start

Basic Commands

# Update all repos in current directory
gittyup

# Update repos in a specific location
gittyup ~/dev/projects

# Preview what would happen (dry run)
gittyup --dry-run

# Get detailed output
gittyup --verbose

Common Workflows

The Monday Morning Refresh 🌅

gittyup ~/projects

Start your week with every project up-to-date.

The Quick Check 👀

gittyup --dry-run --verbose

See what's outdated without touching anything.

The Deep Dive 🔎

gittyup ~/dev --max-depth 3 --exclude archive --verbose

Scan thoroughly but skip archived projects.

The Safe Update with Work in Progress 🔧

gittyup --ignore-all-changes

Update repos even when you have uncommitted changes, but only if no merge conflict would occur.

The Accountability Check 🔍

gittyup --explain

Review your guardian's detailed report: see exactly what commits were pulled, which files changed, and why any repos were skipped. Perfect for Monday morning catch-up or debugging unexpected changes.

The Performance Mode ⚡

gittyup ~/projects --batch-size 5

Update multiple repositories concurrently for maximum speed. Adjust batch size based on your system resources and network connection. Careful you don't over do it and get rate limited at GitHub.

The Safe and Sequential 🎯

gittyup --sync --verbose

Process repositories one at a time for careful monitoring or when debugging issues. Perfect for troubleshooting or conservative workflows.

📖 Documentation

Command Reference

gittyup [DIRECTORY] [OPTIONS]

Output Guide

Gitty Up uses clear visual indicators to communicate status:

Example Output

╔════════════════════════════════════════════════════════════════════════════╗
║                              Gitty Up                                       ║
╚════════════════════════════════════════════════════════════════════════════╝

✓ Scanning directory: /Users/dev/projects
✓ Found 9 git repositories

Updating: project-alpha, project-beta, project-gamma
✓ project-alpha - Already up-to-date
↓ project-beta - Pulled 3 commits
⊙ project-gamma - Uncommitted changes

Updating: project-delta, project-epsilon, project-zeta
✓ project-delta - Already up-to-date
✗ project-epsilon - Network timeout
↓ project-zeta - Pulled 1 commit

Updating: project-omega, project-sigma, project-theta
✓ project-omega - Already up-to-date
✓ project-sigma - Already up-to-date
✓ project-theta - Already up-to-date

════════════════════════════════════════════════════════════════════════════
Summary
════════════════════════════════════════════════════════════════════════════
Total repositories found: 9
  ✓ Up to date: 5
  ↓ Updated: 2
  ⊙ Skipped: 1
  ✗ Errors: 1

Completed in 4.23 seconds
════════════════════════════════════════════════════════════════════════════

Note: The example shows default batch processing (3 repos at a time). Use --sync for sequential updates with individual progress indicators.

Using --explain to Review History

Your Git guardian keeps detailed records of every operation. Need to know what changed? Just ask:

$ cd ~/projects
$ gittyup --explain

═══════════════════════════════════════════════════════════════════════════
                    Gitty Up - Operation History
═══════════════════════════════════════════════════════════════════════════

═══════════════════════════════════════════════════════════════════════════
Operation Details
═══════════════════════════════════════════════════════════════════════════
  📅 Run Date: 2025-10-15 14:23:45
  📂 Directory: /Users/dev/projects
  ⏱️  Duration: 2.34 seconds
  🔧 Gittyup Version: 1.0.0
  🐙 Git Version: 2.39.0

═══════════════════════════════════════════════════════════════════════════
Summary
═══════════════════════════════════════════════════════════════════════════
  Total repositories: 5
  ✅ Updated: 1
  💤 Already up-to-date: 3
  ⏭️  Skipped: 1
  ❌ Errors: 0

═══════════════════════════════════════════════════════════════════════════
Repository Details
═══════════════════════════════════════════════════════════════════════════

✅ project-alpha
   Path: /Users/dev/projects/project-alpha
   Duration: 487ms
   Branch: main
   Changes pulled successfully
   Commits: 3
   Files changed: 5
   Insertions: +127
   Deletions: -43

   📝 Commits:
      a7f2c3d - Add new feature for user authentication
         John Doe • 2025-10-15T10:23:00
      b8e1d4f - Fix bug in login validation
         Jane Smith • 2025-10-15T09:15:00
      c9f2e5g - Update dependencies to latest versions
         John Doe • 2025-10-14T16:45:00

   📁 Files:
      ~ src/auth.py
         (+45/-12)
      + src/validators.py
         (+32/-0)
      ~ tests/test_auth.py
         (+28/-8)

💤 project-beta
   Path: /Users/dev/projects/project-beta
   Duration: 123ms
   Branch: develop
   Already up-to-date

⏭️  project-gamma
   Path: /Users/dev/projects/project-gamma
   Duration: 89ms
   Branch: main
   Skipped
   Reason: Repository has uncommitted changes
   Details: Pull would conflict with local modifications

═══════════════════════════════════════════════════════════════════════════

What --explain shows:

• Complete operation metadata: When it ran, how long it took, tool versions
• Summary statistics: Overall results across all repositories
• Detailed repository information:
  • Every commit that was pulled (who wrote it, when, what changed)
  • Exactly which files changed with insertion/deletion counts
  • Why any repos were skipped with specific reasons
  • Full error details for debugging failed operations
  • Branch information and precise timing data

Perfect for:

• Debugging issues or understanding unexpected changes
• Auditing what happened during automated runs
• Reviewing what you missed while away from your desk
• Team accountability and change tracking

Where logs are stored: Your guardian keeps records in OS-specific cache directories:

• macOS: ~/Library/Caches/gittyup/logs
• Linux: ~/.cache/gittyup/logs
• Windows: C:\Users\<user>\AppData\Local\gittyup\logs

Each directory you scan gets its own log, automatically updated with each run. Storage is minimal (10-50 KB per log).

🛡️ Safety Features

Gitty Up protects your work with intelligent safety checks. It will skip updating a repository if it detects:

Your local work is always safe. Gitty Up never forces changes or overwrites uncommitted work.

🧠 Smart Filtering

Gitty Up automatically skips common directories that aren't your code:

Development Environments:
node_modules, venv, .venv, env, .env, vendor

Build Artifacts:
dist, build, target, .eggs, eggs

Caches:
__pycache__, .pytest_cache, .mypy_cache, .ruff_cache, htmlcov

Tools:
.tox, .nox, .idea, .vscode

Version Control:
.git, .svn, .hg

Want to exclude more? Use --exclude:

gittyup --exclude temp --exclude backup --exclude old-stuff

🧹 Always-Ignored Files

GittyUp knows the difference between real changes and desktop clutter. These common system and cache files are automatically ignored when checking for uncommitted changes:

• .DS_Store - macOS metadata that clutters every directory
• Thumbs.db - Windows thumbnail caches you never asked for
• __pycache__ - Python bytecode that regenerates anyway

Why this matters: Repositories with only these files are treated as clean and can be updated automatically. No more "uncommitted changes" blocks just because your OS left metadata files lying around.

📚 Learn more: See Always-Ignored Files Documentation for detailed examples and implementation details.

❓ FAQ

gittyup --exclude archive --exclude temp --exclude old-projects

# Example: Daily at 9 AM
0 9 * * * cd ~/projects && ~/.local/bin/gittyup --quiet

# Default: 3 repos at a time
gittyup ~/projects

# High performance: 5 repos at a time
gittyup ~/projects --batch-size 5

# Sequential (old behavior): 1 repo at a time
gittyup ~/projects --sync

🚨 Troubleshooting

Git Not Found

Error: Git is not installed or not found in PATH

Fix: Install Git and ensure it's in your system PATH:

# macOS
brew install git

# Linux (Debian/Ubuntu)  
sudo apt-get install git

# Verify
git --version

Authentication Issues

Error: Authentication failed

Fix: Configure your Git credentials:

# SSH keys (recommended)
ssh-keygen -t ed25519 -C "your@email.com"
# Then add to GitHub/GitLab/etc.

# Or use credential helper
git config --global credential.helper store

Permission Denied

Error: Permission denied

Fix: Ensure you have read access to the directories being scanned. Check file permissions or run with appropriate privileges.

Network Timeouts

Error: Network error

Fix:

• Check your internet connection
• Verify remote URLs: git remote -v
• Check firewall settings
• Consider using --max-depth to reduce scope

Log History Not Found

⚠️  No history found for: /path/to/directory

Fix:

• Run gittyup in this directory first (your guardian needs something to record!)
• Remember: logs are only created for actual operations (non-dry-run)
• Verify you're in the same directory where you previously ran gittyup
• Check that the cache directory has write permissions

Cache Permission Errors

Error: Failed to save operation log

Fix:

• Ensure write access to cache directory:
  • macOS: ~/Library/Caches/gittyup/logs
  • Linux: ~/.cache/gittyup/logs
  • Windows: C:\Users\<user>\AppData\Local\gittyup\logs
• Check directory permissions: ls -la ~/.cache/gittyup (Unix/macOS)
• Create directory manually if needed: mkdir -p ~/.cache/gittyup/logs

🔧 Development & Contributing

Interested in contributing to Gitty Up or running it locally for development?

📚 See the Development Guide for:

• Development setup instructions
• Testing and code quality guidelines
• Contributing guidelines and PR process
• Project architecture and design decisions
• Release process and versioning

We welcome contributions of all kinds—bug reports, feature requests, documentation improvements, and code contributions!

📊 Project Stats

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with ❤️ for developers who juggle too many projects and forget to git pull.

Powered by:

• Click - Command-line interface magic
• Colorama - Cross-platform colored output
• platformdirs - OS-specific directory paths
• diskcache - Fast persistent caching
• Ruff - Lightning-fast Python linting

📌 Version

Current Release: 1.0.0

See change-log.md for complete version history and release notes.