git-maintenance

Register the current repository in the user's list of repositories to daily have maintenance run

$ git maintenance register

$ git maintenance start

$ git maintenance stop

$ git maintenance unregister

$ git maintenance run --task [commit-graph|gc|incremental-repack|loose-objects|pack-refs|prefetch]

git maintenance <subcommand> [<options>]

git maintenance run [--[no-]auto] [--[no-]fetch] [--[no-]gc] [--[no-]commit-graph] [--[no-]loose-objects]
git maintenance start [--auto | --manual]
git maintenance stop
git maintenance status
git maintenance list
git maintenance register
git maintenance unregister

run
    Executes maintenance tasks immediately based on the current configuration. You can specify which tasks to run using individual task options.

start
    Begins periodic background maintenance. By default, it attempts to use automatic system scheduling (like systemd or launchd). Use --manual for a simple background process.

stop
    Halts periodic background maintenance and unregisters it from system schedulers if it was started automatically.

status
    Shows the current status of background maintenance, indicating whether it's running and its configuration.

list
    Lists the maintenance tasks that are currently enabled or configured to run automatically.

register
    Registers git-maintenance with system-level schedulers (e.g., systemd timers, launchd agents) to enable automatic background maintenance. This is often done implicitly by start.

unregister
    Unregisters git-maintenance from system-level schedulers. This is often done implicitly by stop.

--auto
    Used with start or run to indicate that automatic system scheduling mechanisms should be used or considered. This is the default for start.

--manual
    Used with start to indicate that git-maintenance should not try to use system schedulers, but instead run as a simple background process which relies on a manual scheduling (e.g., a cron job or a continuously running daemon that checks schedule internally).

--[no-]fetch
    Enables or disables the prefetch task (fetching objects from remotes) during run or in the auto-maintenance configuration.

--[no-]gc
    Enables or disables the garbage collection task (repacking and pruning) during run or in the auto-maintenance configuration.

--[no-]commit-graph
    Enables or disables the commit-graph update task during run or in the auto-maintenance configuration.

--[no-]loose-objects
    Enables or disables the loose-objects pruning task during run or in the auto-maintenance configuration.

git-maintenance is a command introduced in Git 2.37 designed to automate common Git repository maintenance tasks. Its primary goal is to keep your Git repositories performing optimally and reduce disk usage without requiring manual intervention.

It handles tasks like: garbage collection (pruning loose objects and repacking), updating the commit graph for faster history traversal, and prefetching objects from remote repositories to keep them up-to-date. By regularly performing these operations in the background, git-maintenance helps improve the speed of common Git commands (like git status, git log) and ensures data integrity. Users can start, stop, or manually run these maintenance operations, as well as configure their frequency and behavior.

git-maintenance requires Git version 2.37 or later. Its automatic scheduling mechanism (--auto) relies on OS-specific features (like systemd timers on Linux, launchd agents on macOS, or a custom background process), which might require appropriate permissions for setup and can behave differently across platforms. Running maintenance tasks, especially garbage collection (gc), can be resource-intensive (CPU, disk I/O) and might impact performance during execution. The prefetch task can also generate network traffic. Ensure your system's scheduling services are operational for reliable automatic maintenance.

The behavior of git-maintenance, especially in --auto mode, is controlled by Git configuration variables. These include: maintenance.auto (boolean, enables/disables auto maintenance for a repository), maintenance.strategy (determines how auto-maintenance is scheduled, e.g., 'auto' for system services, 'manual' for a simple background process), maintenance.schedule (e.g., 'hourly', 'daily', 'weekly', 'monthly', 'never' to set frequency).

Individual task settings like maintenance.auto.gc, maintenance.auto.commit-graph, maintenance.auto.prefetch, and maintenance.auto.loose-objects (all booleans) allow enabling or disabling specific tasks within the automatic maintenance schedule.

git-maintenance performs several key tasks:
gc: Runs garbage collection, which includes repacking loose objects into packfiles and pruning unreferenced objects, reducing disk space and improving performance.
commit-graph: Updates the commit-graph file, which significantly speeds up operations that traverse commit history, such as git log and git blame.
prefetch: Fetches objects from configured remotes, keeping the local repository's branches and references up-to-date with remote changes.
loose-objects: Specifically prunes loose objects that are no longer referenced, an important part of overall garbage collection.

git-maintenance was introduced in Git 2.37 (released in Q3 2022). Prior to this, Git lacked an integrated, cross-platform solution for automating routine repository maintenance. Users had to manually set up cron jobs or similar schedulers to run commands like git gc. The introduction of git-maintenance aimed to simplify this process, providing a built-in mechanism that could intelligently manage background tasks, adapt to different operating system scheduling paradigms, and ensure repositories remained optimized without constant user oversight. Subsequent Git versions have refined its capabilities, notably adding the prefetch task and improving its scheduling robustness.

git gc(1), git repack(1), git prune(1), git commit-graph(1), cron(8), systemd.timer(5), launchd.plist(5)