Git Maintenance Troubleshooting and Background Maintenance

`crontab`. Default is `auto`. TROUBLESHOOTING --------------- The `git maintenance` command is designed to simplify the repository maintenance patterns while minimizing user wait time during Git commands. A variety of configuration options are available to allow customizing this process. The default maintenance options focus on operations that complete quickly, even on large repositories. Users may find some cases where scheduled maintenance tasks do not run as frequently as intended. Each `git maintenance run` command takes a lock on the repository's object database, and this prevents other concurrent `git maintenance run` commands from running on the same repository. Without this safeguard, competing processes could leave the repository in an unpredictable state. The background maintenance schedule runs `git maintenance run` processes on an hourly basis. Each run executes the "hourly" tasks. At midnight, that process also executes the "daily" tasks. At midnight on the first day of the week, that process also executes the "weekly" tasks. A single process iterates over each registered repository, performing the scheduled tasks for that frequency. The processes are scheduled to a random minute of the hour per client to spread out the load that multiple clients might generate (e.g. from prefetching). Depending on the number of registered repositories and their sizes, this process may take longer than an hour. In this case, multiple `git maintenance run` commands may run on the same repository at the same time, colliding on the object database lock. This results in one of the two tasks not running. If you find that some maintenance windows are taking longer than one hour to complete, then consider reducing the complexity of your maintenance tasks. For example, the `gc` task is much slower than the `incremental-repack` task. However, this comes at a cost of a slightly larger object database. Consider moving more expensive tasks to be run less frequently. Expert users may consider scheduling their own maintenance tasks using a different schedule than is available through `git maintenance start` and Git configuration options. These users should be aware of the object database lock and how concurrent `git maintenance run` commands behave. Further, the `git gc` command should not be combined with `git maintenance run` commands. `git gc` modifies the object database but does not take the lock in the same way as `git maintenance run`. If possible, use `git maintenance run --task=gc` instead of `git gc`. The following sections describe the mechanisms put in place to run background maintenance by `git maintenance start` and how to customize them. BACKGROUND MAINTENANCE ON POSIX SYSTEMS --------------------------------------- The standard mechanism for scheduling background tasks on POSIX systems is cron(8). This tool executes commands based on a given schedule. The current list of user-scheduled tasks can be found by running `crontab -l`. The schedule written by `git maintenance start` is similar to this: ----------------------------------------------------------------------- # BEGIN GIT MAINTENANCE SCHEDULE # The following schedule was created by Git # Any edits made in this region might be # replaced in the future by a Git command. 0 1-23 * * * "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=hourly 0 0 * * 1-6 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=daily 0 0 * * 0 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=weekly # END GIT MAINTENANCE SCHEDULE ----------------------------------------------------------------------- The comments are used as a region to mark the schedule as written by Git. Any modifications within this region will be completely deleted by `git maintenance stop` or overwritten by `git maintenance start`. The `crontab` entry specifies

The git maintenance command may encounter issues with scheduled tasks not running as frequently as intended due to object database locks, and users can troubleshoot by adjusting maintenance tasks or schedules, and expert users can customize their own maintenance tasks using cron or other scheduling tools.