### Manage Gitty Up installation with uv

Source: https://github.com/mikeckennedy/gittyup/blob/main/INSTALLATION.md

Commands to manage the Gitty Up installation when installed via uv, including updating to the latest version, uninstalling, and listing installed tools.

```bash
# Update to latest version
uv tool upgrade gittyup

# Uninstall
uv tool uninstall gittyup

# List installed tools
uv tool list
```

--------------------------------

### Install Gitty Up from Source for Development

Source: https://github.com/mikeckennedy/gittyup/blob/main/INSTALLATION.md

Instructions for installing Gitty Up from its source code repository, suitable for development or contributing. It covers cloning the repo and installing in editable mode using uv or a virtual environment with pip.

```bash
# 1. Clone the repository
git clone https://github.com/mikeckennedy/gittyup
cd gittyup

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

# Or install in a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
uv pip install -e .
```

--------------------------------

### Clone and Set Up Development Environment

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/development.md

Commands to clone the Gitty Up repository, create and activate a Python virtual environment, and install development dependencies using uv.

```bash
git clone https://github.com/mikeckennedy/gittyup
cd gittyup

python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# or: venv\Scripts\activate  # Windows

uv pip install -e .
uv pip install -r requirements-development.txt
```

--------------------------------

### Verify Gitty Up Installation: View Help Text

Source: https://github.com/mikeckennedy/gittyup/blob/main/INSTALLATION.md

Display the help message for the Gitty Up CLI to ensure it's functioning and displaying its available commands and options correctly.

```bash
gittyup --help

# Expected output:
# Usage: gittyup [OPTIONS] [DIRECTORY]
# 
#   Gitty Up - Automatically discover and update all git repositories in a
#   directory tree.
# ...
```

--------------------------------

### Check Prerequisites for Gitty Up Installation

Source: https://github.com/mikeckennedy/gittyup/blob/main/INSTALLATION.md

Verify that the necessary prerequisites for installing Gitty Up are met. This includes checking the Python version (3.13+), Git installation, and the uv package manager.

```bash
# Check Python version (should be 3.13+)
python --version

# Check Git installation
git --version

# Check if uv is installed (optional but recommended)
uv --version
```

--------------------------------

### Bash Command Examples for Gittyup CLI

Source: https://github.com/mikeckennedy/gittyup/blob/main/plans/project-plan.md

Provides example bash commands demonstrating how to use the Gittyup CLI for various operations. Includes examples for updating all repos, specifying a path, performing a dry run, and enabling verbose or quiet modes.

```bash
# Update all repos in the current directory
gittyup

# Update repos in a specific path
gittyup --path ~/projects

# Perform a dry run to see planned actions
gittyup --dry-run

# Enable verbose output for detailed logs
gittyup -v

# Enable quiet mode to show only errors
gittyup -q

# Exclude specific directories from scanning
gittyup --exclude node_modules vendor

```

--------------------------------

### Install Gittyup from PyPI

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/PROJECT_SUMMARY.md

Installs the Gittyup tool from the Python Package Index (PyPI). This is the recommended method for most users.

```bash
uv tool install gittyup
```

--------------------------------

### Install Gitty Up from PyPI using uv

Source: https://github.com/mikeckennedy/gittyup/blob/main/INSTALLATION.md

Install Gitty Up as a global CLI tool using the uv package manager from PyPI. This method makes the 'gittyup' command available system-wide without needing a virtual environment.

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

# That's it! The gittyup command is now available globally
gittyup --version
```

--------------------------------

### Verify Gitty Up Installation: Check Version

Source: https://github.com/mikeckennedy/gittyup/blob/main/INSTALLATION.md

Check the installed version of Gitty Up to confirm a successful installation. This command should output the version number if the tool is working correctly.

```bash
gittyup --version

# Expected output:
# Gitty Up version 1.0.0
```

--------------------------------

### Install Gitty Up using pipx

Source: https://github.com/mikeckennedy/gittyup/blob/main/INSTALLATION.md

An alternative method to install Gitty Up as a Python CLI tool using pipx, which is recommended for managing such applications.

```bash
# Using pipx (recommended for Python CLI tools)
pipx install gittyup
```

--------------------------------

### Install Gittyup from Source

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/PROJECT_SUMMARY.md

Installs Gittyup from its source code repository. This is useful for development or when needing the latest unreleased changes.

```bash
git clone https://github.com/mikeckennedy/gittyup
cd gittyup
uv pip install -e .
```

--------------------------------

### Verify Gitty Up Installation: Check Command Availability

Source: https://github.com/mikeckennedy/gittyup/blob/main/INSTALLATION.md

Confirm that the 'gittyup' command is accessible in your system's PATH after installation. This step checks if the executable can be found.

```bash
# Verify the gittyup command is available
which gittyup

# Expected output (will vary by system):
# /Users/yourname/path/to/venv/bin/gittyup
```

--------------------------------

### Create Release Artifacts and Publish to PyPI

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/development.md

Commands to build distribution packages and publish them to PyPI. This process requires `uv` to be installed and PyPI credentials to be configured. It's typically performed by maintainers after tagging a release.

```bash
# Build distribution packages
uv build

# Publish to PyPI (requires credentials)
uv publish
```

--------------------------------

### Gittyup Explain Command Output Example

Source: https://github.com/mikeckennedy/gittyup/blob/main/plans/logging-explain-feature.md

An example of the detailed output generated by the `gittyup --explain` command. This output includes run date, directory, duration, Gittyup and Git versions, a summary of the operation, and detailed information for each repository, including commits and file changes.

```bash
$ cd ~/projects
$ gittyup --explain
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
               Gitty Up - Operation History                       
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Operation Details
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  📅 Run Date: 2025-10-15 14:23:45
  📂 Directory: /Users/user/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/user/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)
      ~ requirements.txt (+12/-15)
      ~ README.md (+10/-8)

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

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

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

--------------------------------

### Install Gitty Up (Bash)

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/RELEASE_NOTES.md

Provides commands for installing or upgrading the Gitty Up tool using 'uv tool'. It includes instructions for a fresh installation and for upgrading an existing local copy.

```bash
uv tool install gittyup
```

```bash
cd gittyup
git pull
uv tool install --force .
```

--------------------------------

### Troubleshoot Gitty Up: Command Not Found

Source: https://github.com/mikeckennedy/gittyup/blob/main/INSTALLATION.md

Provides solutions for the 'gittyup: command not found' error. This includes ensuring the virtual environment is activated, checking the package installation, reinstalling, and verifying the Python scripts directory is in the system's PATH.

```bash
# Example symptom:
gittyup --version
# zsh: command not found: gittyup

# Solution 1: Activate virtual environment
source venv/bin/activate
# On Windows: venv\Scripts\activate

# Solution 2: Check if package is installed
uv pip list | grep gittyup
# Should show: gittyup 1.0.0

# Solution 3: Reinstall the package
cd /path/to/gittyup
uv pip install -e .

# Solution 4: Check Python's scripts directory is in PATH
echo $PATH
# Should include something like: /path/to/venv/bin
```

--------------------------------

### Gittyup Normal Operation Output Example

Source: https://github.com/mikeckennedy/gittyup/blob/main/plans/logging-explain-feature.md

An example of the standard output when Gittyup runs on a directory. It shows the scanning process, found repositories, their status (Updated, Skipped), and a summary of the operation including duration.

```bash
$ gittyup ~/projects
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                        Gitty Up                                   
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ℹ️  Scanning directory: /Users/user/projects

✅ Found 5 git repositories

✅ project-alpha         Updated (3 commits)
⏭️  project-beta          Skipped (uncommitted changes)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Summary:
  Total repositories: 5
  Updated: 1
  Up-to-date: 3
  Skipped: 1
  Errors: 0
  Duration: 2.34s
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

--------------------------------

### Google-Style Python Docstring Example

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/development.md

An example of a Python function adhering to Google-style docstrings. This format includes sections for arguments, return values, and raised exceptions, promoting clear and consistent documentation.

```python
def function_name(param1: str, param2: int) -> bool:
    """Brief description of function. 
    
    More detailed description if needed. 
    
    Args:
        param1: Description of param1
        param2: Description of param2
    
    Returns:
        Description of return value
    
    Raises:
        ValueError: When and why this is raised
    """
    pass
```

--------------------------------

### Manage Dependencies with uv

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/development.md

Commands to manage project dependencies using `uv`. This includes compiling requirements files and installing dependencies. Ensure `uv` is installed and requirements files (`.piptools`) are present.

```bash
# Update runtime dependencies
uv pip-compile requirements.piptools -o requirements.txt

# Update development dependencies
uv pip-compile requirements-development.piptools -o requirements-development.txt

# Install updated dependencies
uv pip install -r requirements.txt
uv pip install -r requirements-development.txt
```

--------------------------------

### Install Gittyup from Local Source

Source: https://github.com/mikeckennedy/gittyup/blob/main/plans/project-plan.md

This command installs the Gittyup package in editable mode from the local source directory. This is useful for development and testing, allowing changes to the code to be reflected immediately without reinstallation.

```bash
cd gittyup
uv pip install -e .
```

--------------------------------

### Gittyup CLI Usage Examples

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/RELEASE_NOTES.md

Demonstrates various command-line interface (CLI) use cases for Gittyup. These examples cover daily development workflows, project management tasks, and system maintenance operations, showcasing different flags and arguments.

```bash
# Start your day by updating all projects
cd ~/
projects
gittyup
```

```bash
# Check status of all client projects
gittyup ~/clients --verbose

# Preview what would be updated
gittyup ~/work --dry-run
```

```bash
# Update repos but skip deep node_modules
gittyup --max-depth 3 --exclude cache
```

--------------------------------

### Gittyup Installation with uv

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/RELEASE_NOTES.md

Provides instructions for installing Gittyup as a global CLI tool using the 'uv' package manager. This method ensures the command is available system-wide without needing virtual environment activation.

```bash
# Install as a global CLI tool (no venv needed!)
uv tool install gittyup

# Use from anywhere
gittyup --version
```

--------------------------------

### Gittyup Installation with pip and venv

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/RELEASE_NOTES.md

Details an alternative installation method for Gittyup using pip within a Python virtual environment. This includes installing from PyPI or directly from source, and activating the environment.

```bash
# Install from PyPI
pip install gittyup

# Or install from source
git clone https://github.com/mikeckennedy/gittyup
cd gittyup
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
uv pip install -e .
```

--------------------------------

### Gittyup Example: Dry Run Preview

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/RELEASE_NOTES.md

Demonstrates the use of the `--dry-run` flag with Gittyup. This option allows users to see which repositories would be updated without actually performing any Git operations.

```bash
$ gittyup ~/projects --dry-run

# Shows what would be updated without actually pulling
```

--------------------------------

### Install Gitty Up CLI with uv

Source: https://github.com/mikeckennedy/gittyup/blob/main/readme.md

Installs the Gitty Up command-line interface tool globally using the uv package manager. This method makes the tool available system-wide without needing to activate a virtual environment.

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

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

--------------------------------

### Install Git on macOS

Source: https://github.com/mikeckennedy/gittyup/blob/main/readme.md

Instructions to install Git on macOS using Homebrew. This is a prerequisite for using Gittyup and other Git-related tools.

```bash
brew install git

# Verify
git --version
```

--------------------------------

### Gittyup Example: Quiet Mode

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/RELEASE_NOTES.md

Shows how to use Gittyup in quiet mode (`-q`). This mode is useful for scripting as it suppresses normal output and only displays error messages.

```bash
$ gittyup -q

# Only shows errors, perfect for scripting
```

--------------------------------

### Install Git on Linux (Debian/Ubuntu)

Source: https://github.com/mikeckennedy/gittyup/blob/main/readme.md

Instructions to install Git on Debian/Ubuntu-based Linux distributions using apt-get. This ensures Git is available in the system's PATH.

```bash
sudo apt-get install git

# Verify
git --version
```

--------------------------------

### Basic Gittyup Usage

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/PROJECT_SUMMARY.md

Demonstrates basic commands for using Gittyup. It shows how to update repositories in the current directory, specify a target directory, and use preview or verbose modes.

```bash
# Update all repos in current directory
gittyup

# Update repos in specific directory
gittyup ~/projects

# Preview without updating
gittyup --dry-run

# Verbose output
gittyup --verbose

# Quiet mode (errors only)
gittyup --quiet
```

--------------------------------

### Gitty Up Usage Example (Bash)

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/RELEASE_NOTES.md

Illustrates a typical workflow for using Gitty Up, first to update repositories and then to review the detailed history of that operation using the --explain flag. This helps in understanding commits, file changes, and skipped repositories.

```bash
$ gittyup ~/projects
# ... updates repositories ...

$ gittyup --explain
# Shows detailed history including:
# - Which commits were pulled
# - What files changed
# - Why repos were skipped
# - Full error details
```

--------------------------------

### Clean Up Gitty Up Test Environment

Source: https://github.com/mikeckennedy/gittyup/blob/main/INSTALLATION.md

Remove the temporary test directory and its contents created during the Gitty Up dry run verification step.

```bash
# Remove test directory
rm -rf /tmp/gittyup-test
```

--------------------------------

### Example Test Structure in Python

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/development.md

A Python code snippet demonstrating a typical test function structure using the Arrange-Act-Assert pattern, including docstrings for clarity.

```python
def test_feature_name():
    """Test description explaining what's being tested."""
    # Arrange - set up test data
    test_data = create_test_data()
    
    # Act - perform the operation
    result = function_under_test(test_data)
    
    # Assert - verify the results
    assert result.status == expected_status
    assert result.message == expected_message
```

--------------------------------

### Schedule Daily Git Updates

Source: https://github.com/mikeckennedy/gittyup/blob/main/readme.md

This cron job example demonstrates how to schedule Gittyup to run daily at 9 AM to update repositories quietly. It assumes Gittyup is installed in ~/.local/bin and repositories are located in ~/projects.

```cron
0 9 * * * cd ~/projects && ~/.local/bin/gittyup --quiet
```

--------------------------------

### Test Gitty Up with Dry Run

Source: https://github.com/mikeckennedy/gittyup/blob/main/INSTALLATION.md

Perform a dry run of Gitty Up to simulate its operation without making any changes. This involves creating a test directory with a Git repository and running Gitty Up to see its expected output.

```bash
# Create test directory structure
mkdir -p /tmp/gittyup-test/test-repo
cd /tmp/gittyup-test/test-repo

# Initialize a git repository
git init
git config user.email "test@example.com"
git config user.name "Test User"
echo "# Test" > README.md
git add README.md
git commit -m "Initial commit"

# Go back to parent directory and run gittyup
cd /tmp/gittyup-test
gittyup --dry-run
```

--------------------------------

### Install Gitty Up CLI Tool (Bash)

Source: https://context7.com/mikeckennedy/gittyup/llms.txt

Provides instructions for installing the Gitty Up command-line interface tool using `uv` or `pip`. It also includes steps for installing from source and verifying the installation.

```bash
# Recommended: Install as global tool with uv
uv tool install gittyup

# Alternative: Install with pip
pip install gittyup

# Install from source for development
git clone https://github.com/mikeckennedy/gittyup
cd gittyup
uv tool install --editable .

# Verify installation
gittyup --version
# Output: Gitty Up version 1.2.0
```

--------------------------------

### Run Gitty Up and Explain Operation (Bash)

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/RELEASE_NOTES.md

Demonstrates how to run the gittyup command to update repositories and then use the --explain flag to view detailed history of the last operation. This is useful for debugging and understanding past actions.

```bash
$ cd ~/projects
$ gittyup --explain
```

--------------------------------

### Gittyup Example: Update Current Directory

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/RELEASE_NOTES.md

Illustrates the output of running Gittyup in the current directory without any arguments. It shows the scanning process, repository status updates, and a final summary including any errors encountered.

```bash
$ gittyup

🐴 Gitty Up!
════════════════════════════════════════
Scanning directory: /Users/mike/projects
✓ Found 5 git repositories

[1/5 - 20%] project-alpha
✓ project-alpha - Already up-to-date

[2/5 - 40%] project-beta
↓ project-beta - Pulled changes successfully

[3/5 - 60%] project-gamma
⊙ project-gamma - Uncommitted changes

[4/5 - 80%] project-delta
✓ project-delta - Already up-to-date

[5/5 - 100%] project-epsilon
✗ project-epsilon - Network timeout
  Error: Git pull timed out after 300 seconds

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

Completed in 3.45 seconds
════════════════════════════════════════
```

--------------------------------

### Determine Cross-Platform Cache Directory with platformdirs

Source: https://github.com/mikeckennedy/gittyup/blob/main/plans/logging-explain-feature.md

Demonstrates how to use the `platformdirs` library to find the appropriate cache directory for the application across different operating systems. This ensures consistent storage of log data regardless of the user's OS.

```python
from platformdirs import user_cache_dir

# Cache location examples:
# macOS:   ~/Library/Caches/gittyup/logs
# Linux:   ~/.cache/gittyup/logs
# Windows: C:\Users\<user>\AppData\Local\gittyup\logs
```

--------------------------------

### Gittyup Verification Commands

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/RELEASE_NOTES.md

Commands to verify that Gittyup has been installed correctly. It shows how to check the installed version and display the help information for usage.

```bash
gittyup --version
# Output: Gitty Up version 1.0.0

gittyup --help
# Shows complete usage information
```

--------------------------------

### Gittyup Example: Verbose Output

Source: https://github.com/mikeckennedy/gittyup/blob/main/docs/RELEASE_NOTES.md

Illustrates the usage of Gittyup in verbose mode (`-v`). This mode provides detailed output, including all repositories (even skipped ones), full Git output, and detailed status information.

```bash
$ gittyup -v

# Shows all repositories including skipped ones
# Shows full git output and detailed status
```