maintenance Git Command Guide

The git maintenance command runs tasks to optimize Git repository data, speeding up Git commands and reducing storage requirements. It provides flexible scheduling for repository optimization tasks that user-facing commands defer for performance reasons.

git maintenance Syntax:

git maintenance run [<options>]
git maintenance start [--scheduler=<scheduler>]
git maintenance (stop|register|unregister) [<options>]

Subcommands:

Repository Management:

Subcommand	Description
run [<options>]	Run one or more maintenance tasks
start [--scheduler=<scheduler>]	Start background maintenance scheduling
stop	Halt background maintenance schedule
register	Add repository to maintenance schedule
unregister	Remove repository from maintenance schedule

Maintenance Options:

Option	Description
--task=<task>	Specify maintenance task to run
--schedule=<frequency>	Set maintenance frequency
--scheduler=<type>	Scheduler type (launchd
--quiet	Suppress output

Maintenance Tasks:

Data Optimization Tasks:

Task	Description
gc	Clean up unnecessary files and optimize repository
commit-graph	Write commit-graph file for faster commit lookup
prefetch	Download objects from configured remotes
incremental-repack	Repack objects incrementally
loose-objects	Consolidate loose objects into pack files
pack-refs	Pack references for better performance

Automatic Task Selection:

# Run default enabled tasks (gc only)
git maintenance run

# Run specific tasks
git maintenance run --task=commit-graph --task=pack-refs

# Run scheduled tasks (for background jobs)
git maintenance run --schedule=daily

Basic Usage Examples:

One-time Maintenance:

# Run default maintenance (gc by default)
git maintenance run

# Run multiple specific tasks
git maintenance run --task=commit-graph --task=pack-refs --task=gc

# Run all available tasks
git maintenance run --task=commit-graph --task=pack-refs --task=gc --task=prefetch --task=incremental-repack

Background Scheduling:

# Start automatic maintenance
git maintenance start

# Stop automatic maintenance
git maintenance stop

# Register repository for maintenance (without scheduling)
git maintenance register

# Unregister repository
git maintenance unregister

Custom Schedules:

# Start with custom scheduler
git maintenance start --scheduler=launchd

# Configure maintenance frequency
git config maintenance.strategy incremental

git config maintenance.gc.enabled true
git config maintenance.commit-graph.enabled true

Advanced Maintenance Configuration:

Task Configuration:

# Enable specific tasks
git config maintenance.gc.enabled true
git config maintenance.commit-graph.enabled true
git config maintenance.prefetch.enabled true

# Disable tasks
git config maintenance.gc.enabled false

# Configure task schedules
git config maintenance.gc.schedule "30 2 * * *"  # Daily at 2:30 AM
git config maintenance.commit-graph.schedule "0 3 * * *"  # Daily at 3:00 AM

Repository-Specific Settings:

# Per-repository maintenance settings
git config maintenance.repo "/path/to/repo"

# Multiple repository maintenance
git maintenance register --repo=/path/to/repo1
git maintenance register --repo=/path/to/repo2

# Bulk maintenance
for repo in ~/projects/*; do
    if [ -d "$repo/.git" ]; then
        git maintenance register --repo="$repo"
    fi
done

Maintenance Strategies:

Incremental Strategy (Default):

# Config for incremental maintenance
git config maintenance.strategy incremental

# Incremental configuration benefits:
# - Runs smaller, faster operations
# - Reduces I/O load
# - Better for frequent runs

Scheduled Maintenance Approaches:

# Daily maintenance tasks
git config maintenance.daily.enabled true
git config maintenance.daily.schedule "30 2 * * *,45 14 * * *"

# Weekly maintenance tasks
git config maintenance.weekly.enabled true
git config maintenance.weekly.schedule "0 3 * * 0"  # Sundays at 3 AM

# Monthly maintenance tasks
git config maintenance.monthly.enabled true
git config maintenance.monthly.schedule "0 4 1 * *"  # First day at 4 AM

Platform-Specific Schedulers:

Systemd (Linux):

# Enable systemd scheduler
git maintenance start --scheduler=systemd

# Systemd service configuration
systemctl --user enable git-maintenance@hourly.timer
systemctl --user start git-maintenance@hourly.timer

Launchd (macOS):

# Enable launchd scheduler
git maintenance start --scheduler=launchd

# Manual launchd configuration
launchctl load ~/Library/LaunchAgents/git-maintenance-hourly.plist

Cron (Linux/Unix):

# Standard cron setup
echo "@hourly git maintenance run --schedule=hourly" | crontab -

# Advanced cron configuration
# Add to crontab:
# 30 2 * * * /usr/bin/git maintenance run --schedule=daily
# 0 3 * * 0 /usr/bin/git maintenance run --schedule=weekly

Task Scheduler (Windows):

# Enable scheduled task (Windows)
git maintenance start --scheduler=schtasks

# Manual task creation
schtasks /create /tn "Git Maintenance" /tr "git maintenance run" /sc hourly

Monitoring and Debugging:

Status Monitoring:

# Check maintenance status
git maintenance run --dry-run

# View maintenance logs
git config maintenance.log.file
tail -f ~/.git-maintenance.log

# Check task states
git config --list | grep maintenance

Performance Monitoring:

# Time maintenance operations
time git maintenance run

# Monitor repository size changes
du -sh .git/before-maintenance
git maintenance run
du -sh .git/after-maintenance

# Track optimization improvements
git log --oneline -10 --stat > before.txt
git maintenance run --task=commit-graph
git log --oneline -10 --stat > after.txt
diff before.txt after.txt

Maintenance Task Details:

Garbage Collection (gc):

# Manual garbage collection
git gc

# Through maintenance
git maintenance run --task=gc

# Aggressive garbage collection
git gc --aggressive --prune=now

# Configuration
git config gc.auto 0  # Disable auto-gc
git config gc.autoDetach false  # Run gc in foreground

Commit Graph Generation:

# Generate commit graph
git commit-graph write

# Through maintenance
git maintenance run --task=commit-graph

# Verify commit graph
git commit-graph verify

# Configuration for large repositories
git config core.commitGraph true
git config commitGraph.generationVersion 2

Reference Packing:

# Pack loose references
git pack-refs

# Through maintenance
git maintenance run --task=pack-refs

# Check packed refs
ls -la .git/packed-refs
cat .git/packed-refs | wc -l

Incremental Repack:

# Repack incrementally
git repack -d --write-bitmap-index

# Through maintenance
git maintenance run --task=incremental-repack

# Full repack (occasional)
git repack -a -d -f --write-bitmap-index

Integration with Workflows:

Development Environment Setup:

#!/bin/bash
# Configure maintenance for development repository

# Enable essential tasks
git config maintenance.gc.enabled true
git config maintenance.commit-graph.enabled true
git config maintenance.prefetch.enabled true

# Set maintenance strategy
git config maintenance.strategy incremental

# Start background maintenance
git maintenance start

# Verify configuration
echo "Maintenance configuration:"
git config --list | grep maintenance

CI/CD Pipeline Integration:

#!/bin/bash
# Maintenance in CI pipeline

# Check if maintenance is needed
if [ "$(du -s .git | awk '{print $1}')" -gt 1000000 ]; then
    echo "Repository large, running maintenance"
    git maintenance run --task=incremental-repack --task=commit-graph
else
    echo "Repository size OK, light maintenance"
    git maintenance run --task=commit-graph
fi

# Performance optimization
git config core.commitGraph true
git config pack.threads 0  # Auto-detect CPU count

Repository Health Monitoring:

#!/bin/bash
# Monitor repository health and run maintenance

# Check for loose objects
loose_count=$(find .git/objects -type f -name '[0-9a-f]*' | wc -l)
if [ "$loose_count" -gt 1000 ]; then
    echo "High loose object count: $loose_count"
    git maintenance run --task=loose-objects
fi

# Check repository size
repo_size=$(du -sh .git | awk '{print $1}')
echo "Repository size: $repo_size"

# Check commit count for commit-graph benefit
commit_count=$(git rev-list --all --count)
if [ "$commit_count" -gt 10000 ]; then
    echo "Large commit count: $commit_count, enabling commit-graph"
    git maintenance run --task=commit-graph
fi

Troubleshooting Common Issues:

Maintenance Not Starting:

# Check scheduler support
git maintenance start --scheduler=auto

# Manual scheduler detection
if command -v systemctl >/dev/null; then
    git maintenance start --scheduler=systemd
elif command -v launchctl >/dev/null; then
    git maintenance start --scheduler=launchd
else
    echo "No supported scheduler found"
fi

Task Execution Errors:

# Debug maintenance runs
GIT_TRACE=1 git maintenance run

# Check specific task
git maintenance run --task=gc 2>&1 | tee maintenance.log

# Verify repository integrity first
git fsck --unreachable | head -10

Performance Issues:

# Monitor long-running tasks
timeout 300 git maintenance run || echo "Maintenance timed out"

# Split large maintenance tasks
git maintenance run --task=commit-graph
git maintenance run --task=gc --task=pack-refs

# Resource limiting
ulimit -v 1000000  # Memory limit
nice -n 10 git maintenance run  # Lower priority

Configuration Conflicts:

# Reset maintenance config
git config --unset-regexp ^maintenance\.

# Check for conflicting settings
git config --list | grep -E "(gc|commit)"

# Clean restart
git maintenance stop
git maintenance unregister
git maintenance register
git maintenance start

Caution

Maintenance tasks can take significant time on large repositories. Run during low-activity periods. Some tasks require exclusive repository access.

Real-World Usage Examples:

After Large Import:

#!/bin/bash
# Repository optimization after massive import

echo "Running comprehensive maintenance after large import"

# Step 1: Initial cleanup
git maintenance run --task=loose-objects

# Step 2: Generate optimizations
git maintenance run --task=commit-graph --task=pack-refs

# Step 3: Full garbage collection
git maintenance run --task=gc

# Step 4: Final incremental repack
git maintenance run --task=incremental-repack

# Verification
echo "Repository size after maintenance:"
du -sh .git/
echo "Loose objects remaining:"
find .git/objects -type f -name '[0-9a-f]*' | wc -l

Regular Development Workflow:

# Nightly maintenance script
#!/bin/bash
# Scheduled development repository maintenance

LOG_FILE="/var/log/git-maintenance.log"

{
    echo "=== Git Maintenance Run: $(date) ==="

    # Check if repository needs maintenance
    if ! git diff --quiet HEAD 2>/dev/null; then
        echo "Working directory not clean, skipping maintenance"
        exit 0
    fi

    # Run light maintenance
    echo "Running daily maintenance"
    time git maintenance run --task=commit-graph --task=pack-refs

    # Conditional garbage collection (weekly)
    if [ $(date +%u) = 7 ]; then
        echo "Running weekly garbage collection"
        time git maintenance run --task=gc
    fi

    # Monthly full repack
    if [ $(date +%d) = 1 ]; then
        echo "Running monthly repack"
        time git maintenance run --task=incremental-repack
    fi

    echo "Maintenance completed successfully"

} >> "$LOG_FILE" 2>&1

Server Repository Management:

#!/bin/bash
# Multi-repository server maintenance

SERVER_REPOS="/srv/git/repositories"
LOG_FILE="/var/log/git-server-maintenance.log"

echo "Starting server-wide maintenance: $(date)" >> "$LOG_FILE"

for repo in "$SERVER_REPOS"/*; do
    if [ ! -d "$repo/.git" ]; then continue; fi

    echo "Maintaining $repo" >> "$LOG_FILE"

    # Enter repository
    cd "$repo" || continue

    # Run maintenance based on repo size
    repo_size=$(du -s .git | awk '{print $1}')

    if [ "$repo_size" -gt 10000000 ]; then  # 10GB+
        echo "Heavy maintenance for large repo" >> "$LOG_FILE"
        git maintenance run --task=incremental-repack --task=commit-graph >> "$LOG_FILE" 2>&1
    else
        echo "Light maintenance for small repo" >> "$LOG_FILE"
        git maintenance run --task=commit-graph --task=pack-refs >> "$LOG_FILE" 2>&1
    fi

    # Weekly full GC
    if [ $(date +%u) = 7 ]; then
        echo "Running GC for $repo" >> "$LOG_FILE"
        git maintenance run --task=gc >> "$LOG_FILE" 2>&1
    fi

done

echo "Server maintenance completed: $(date)" >> "$LOG_FILE"

Tip

Start background maintenance with git maintenance start. Configure tasks based on repository size and activity. Monitor maintenance logs for issues.

What’s the relationship between maintenance and git gc?

git maintenance run —task=gc calls git gc internally with optimized settings. Maintenance provides scheduling and selective task execution.

How do I disable automatic maintenance?

Run git maintenance stop to stop background scheduling, or git maintenance unregister to remove repository from maintenance tracking.

What’s the impact on repository users during maintenance?

Most tasks (except gc) allow concurrent access. GC requires exclusive repository access. Schedule during low-activity periods.

Can maintenance work on bare repositories?

Yes, all maintenance tasks work on bare repositories. Useful for optimizing server-side repositories where gc alone runs traditionally.

How do I troubleshoot failing maintenance tasks?

Run with GIT_TRACE=1 for debugging output. Check repository integrity with git fsck. Test individual tasks manually before automation.

What’s the difference between incremental and aggressive maintenance?

Incremental runs smaller optimizations frequently; aggressive (like gc —aggressive) does thorough optimization but takes longer and should run less often.

Can maintenance tasks be run manually without scheduling?

Yes, use git maintenance run —task= for manual execution. Useful for testing maintenance before background automation.

How do I monitor maintenance effectiveness?

Compare repository size, object counts, and git log performance before/after maintenance. Use time command to measure task duration.

What happens if maintenance is interrupted?

Most tasks are atomic - partial completion doesn’t corrupt repository. Restart maintenance to continue. Loose object consolidation may need retry.

Can maintenance be configured per-branch or per-user?

Maintenance is repository-level, not branch-specific. User-specific configuration through global git config. Per-branch optimization through commit-graph generation.

How frequently should maintenance run?

Light tasks (commit-graph, pack-refs): Daily. GC: Weekly. Incremental repack: Monthly or every 1000 commits. Adjust based on repository size/activity.

What’s the storage impact of maintenance tasks?

Maintenance typically reduces storage through packing and garbage collection, though commit-graph adds small overhead for better performance.

Can maintenance work with Git LFS repositories?

Works normally - LFS pointers are Git objects like any other. Maintenance optimizes the Git repository structure, not LFS server storage.

How do I handle maintenance in shared repository scenarios?

For shared repositories, coordinate maintenance windows with users. Use git gc —auto or background maintenance during low-activity periods.

What’s the relationship between maintenance and git gc —auto?

git gc —auto triggers based on operation counts; maintenance provides scheduled optimization. Use both: auto for immediate response, scheduled for thorough maintenance.

Applications of the git maintenance command

1. Repository Performance Optimization: Speed up Git commands through data structure optimization
2. Storage Space Reduction: Clean up unnecessary files and repack objects efficiently
3. Automated Background Tasks: Set up scheduled maintenance for unattended repository care
4. Large Repository Management: Handle optimization of massive repositories with controlled resource usage
5. Server Repository Administration: Manage maintenance across multiple server-hosted repositories
6. Development Workflow Enhancement: Maintain repository health as part of development processes