gittyup 1.2.0

Automatically discover and update all git repositories in a directory tree

🐴 Gitty Up!

Never forget to pull again

Automatically discover and update all your Git repositories with one command

Features • Installation • Quick Start • Documentation • FAQ

---

🎯 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

🛡️ Safety First Smart checks prevent data loss. Skips repos with uncommitted changes, detached HEADs, or missing upstreams. Your local work is always protected. 🔍 Complete Transparency Your Git guardian keeps detailed records. Every operation is automatically logged with commit details, file changes, and timing data. Use --explain to review exactly what happened—perfect for debugging, auditing, or understanding what changed. 🎨 Visual Clarity Beautiful, color-coded output with intuitive symbols. Green for success, red for errors—know exactly what's happening at a glance. 🔎 Intelligent Discovery Recursively finds every Git repository in your directory tree, no matter how deeply nested.

⚡ Lightning Fast Concurrent batch processing updates multiple repositories simultaneously. Configurable batch sizes optimize performance for your workflow. Auto-excludes common junk directories. 🎯 Flexible Control Dry-run mode, depth limits, custom exclusions, verbosity levels—you're in complete control of every operation. ✅ Battle-Tested 91.93% test coverage with 216 comprehensive tests. Production-ready and reliable with every release.

---

📦 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]

Argument/Option	Description	Default
DIRECTORY	Path to scan for repositories	Current directory
-n, --dry-run	Preview changes without updating	Disabled
-b, --batch-size N	Number of repos to update concurrently	3
-s, --sync	Force sequential updates (batch size = 1)	Concurrent
-d, --max-depth N	Maximum directory depth to scan	Unlimited
-e, --exclude PATTERN	Skip directories matching pattern	None
-v, --verbose	Show all repos, including up-to-date	Normal
-q, --quiet	Only show errors	Normal
--ignore-untracked	Allow updates even when untracked files present	Disabled
--ignore-all-changes	Allow updates with uncommitted changes (if safe)	Disabled
--explain	Show detailed history of last run	Disabled
--version	Display version information	-
--help	Show help message	-

Output Guide

Gitty Up uses clear visual indicators to communicate status:

✓ Green	Repository is up-to-date or successfully updated
↓ Cyan	Repository pulled new commits
⊙ Yellow	Repository skipped (safety check failed)
✗ Red	Error occurred during update
→ White	Processing repository

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:

Condition	Why it's Skipped	What to Do
🔒 Uncommitted changes	Prevents losing your work	Commit, stash, or discard changes first
🔗 No remote configured	Nothing to pull from	Add a remote: git remote add origin <url>
📍 Detached HEAD state	Not on a branch	Checkout a branch: git checkout main
🎯 No upstream branch	Branch not tracking remote	Set upstream: git push -u origin <branch>
🌐 Network errors	Can't reach remote	Check connection and remote URL
🔐 Authentication failed	Credentials missing	Configure Git credentials

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

Will Gitty Up overwrite my local changes?

Absolutely not. By default, Gitty Up includes comprehensive safety checks and will skip any repository with uncommitted changes. Your local work is always protected.

If you want more control, use:

• --ignore-untracked: Allows updates when only untracked files are present (with safety checks)
• --ignore-all-changes: Allows updates even with modified files, but only if no merge conflict would occur

What's the difference between --ignore-untracked and --ignore-all-changes?

• --ignore-untracked: Only works when you have untracked files (new files not in git). It checks if those files would conflict with incoming changes and only proceeds if safe.

• --ignore-all-changes: Works with any uncommitted changes (modified, staged, or untracked files). It performs a more comprehensive safety check—fetches from origin and verifies that none of your uncommitted files would conflict with incoming changes. Only proceeds if the pull can be done safely.

When to use which:

• Use --ignore-untracked if you often have temporary/working files that aren't tracked
• Use --ignore-all-changes if you need to pull updates even when you have work in progress, but want assurance you won't get merge conflicts

Both flags are mutually exclusive—use the one that fits your workflow.

What happens if I have a merge conflict?

Gitty Up will detect the conflict, report it as an error, and move on to the next repository. You'll need to resolve conflicts manually—Gitty Up never forces merges.

Can I use this with private repositories?

Yes! As long as your Git credentials are properly configured (SSH keys or credential helper), Gitty Up will work seamlessly with private repos.

How do I exclude specific directories?

Use the --exclude option (multiple times if needed):

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

Does it work with Git submodules?

Gitty Up treats the parent repository as a single unit and doesn't traverse into submodules. This prevents confusion and duplicate updates.

Can I run this on a schedule?

Absolutely! Set up a cron job (Unix) or Task Scheduler (Windows):

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

What if one repository fails?

Gitty Up continues processing all other repositories. Failures are clearly reported at the end, and you can address them individually.

Does it support SVN or Mercurial?

No, Gitty Up is specifically designed for Git repositories. It's Git all the way down. 🐴

What information does --explain show?

Think of --explain as your guardian's detailed report card. It shows:

• Every commit that was pulled: Who wrote it, when they committed it, and the commit message
• Exactly which files changed: File paths with insertion/deletion counts
• Why any repos were skipped: Specific reasons like uncommitted changes or detached HEAD
• Full error details: Complete diagnostics for debugging any issues
• Operation metadata: When it ran, how long it took, versions used

Perfect when you need to understand what happened, debug an issue, or provide accountability for automated runs. No need to re-run the operation—your guardian remembers everything.

Where are logs stored and how much space do they use?

Your guardian stores logs in OS-specific cache directories using efficient key-value storage:

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

Storage impact is minimal: each log is typically 10-50 KB. Even with 100 directories logged, total storage is only 1-5 MB. Each directory gets one log that's updated with each run, so space doesn't grow unbounded.

Do dry runs create logs?

No, dry runs (--dry-run) do not save logs. Your guardian only records actual operations that modify repositories. This keeps your history clean and focused on real changes, not "what if" scenarios.

How does concurrent batch processing work?

By default, Gitty Up updates repositories in batches of 3 simultaneously using async I/O operations. This dramatically improves performance when updating many repositories:

# 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

Benefits:

• Faster updates: Network I/O happens concurrently while waiting for git operations
• Controlled resources: Batch size prevents overwhelming your system
• Clear output: Results are displayed in order after each batch completes

When to adjust batch size:

• Increase (--batch-size 5-10): Fast internet, powerful system, many repos
• Decrease (--batch-size 1 or --sync): Debugging issues, slow connection, conservative approach

The concurrent processing is safe and respects all the same safety checks as sequential mode.

---

🚨 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 "[e-mail]"
# 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

Metric	Value
Test Coverage	91.93%
Total Tests	216 passing
Code Quality	Zero linting issues
Python Version	3.13+
Dependencies	Minimal (click, colorama, platformdirs, diskcache)
Lines of Code	~2,100

---

📄 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.

---

Made with 🐴 by developers, for developers

⬆ Back to Top