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 [options]

start
    Schedules automatic maintenance using systemd timers.

stop
    Stops the scheduled maintenance.

run
    Manually executes the maintenance tasks.

register-repo
    Registers the current repository for maintenance using systemd timers. Takes additional arguments: --schedule to specify daily or weekly maintenance schedule.

unregister-repo
    Unregisters the current repository from scheduled maintenance. Removes systemd timers associated with the repository.

--schedule
    Specifies the schedule for the maintenance tasks when registering a repository.

--system
    Install maintenance system wide.

The `git maintenance` command family provides tools for optimizing and maintaining the health of a Git repository. It helps ensure that repositories remain performant over time by performing routine tasks like repacking, garbage collection, and commit-graph writing. These operations can become necessary as a repository grows and accumulates more objects and history. This command allows for scheduling such maintenance tasks to run automatically using systemd timers or similar schedulers. By automating these tasks, repository performance can be improved and potential issues prevented. It’s crucial for large or frequently-updated repositories where performance degradation can become noticeable. Essentially, `git maintenance` is about proactive repository health management, preventing performance bottlenecks, and ensuring that Git operations remain fast and efficient.

Requires systemd for automatic scheduling. Not all Git hosting services may support running custom scripts or timers.

The `git maintenance start` command creates and enables systemd timer units. These units define the schedule and execution of the maintenance tasks. The timers are typically configured to run daily or weekly, and they execute the `git maintenance run` command.

The maintenance tasks typically include repacking the repository, pruning unreachable objects, and updating the commit graph. These tasks help reduce disk space usage, improve Git operation performance, and prevent repository corruption.

Register a repository for daily maintenance:
git maintenance register-repo --schedule daily

Start the scheduled maintenance:
git maintenance start

Manually run the maintenance tasks:
git maintenance run

Stop the scheduled maintenance:
git maintenance stop

The `git maintenance` command was introduced to provide a more structured and automated approach to Git repository maintenance. Previously, administrators had to manually run maintenance tasks or create custom scripts to schedule them. This command simplifies this process by integrating with systemd timers and providing a standard interface for scheduling and running maintenance tasks. It addresses the challenges of maintaining large and actively developed Git repositories where performance can degrade over time due to the accumulation of garbage objects and a fragmented object database. It aims to shift maintenance from a reactive to a proactive approach, ensuring repositories remain healthy and performant.

git gc(1), git repack(1), git commit-graph(1)