logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

git-maintenance.1 (26559B)


  1. '\" t
  2. .\" Title: git-maintenance
  3. .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
  4. .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
  5. .\" Date: 2025-03-14
  6. .\" Manual: Git Manual
  7. .\" Source: Git 2.49.0
  8. .\" Language: English
  9. .\"
  10. .TH "GIT\-MAINTENANCE" "1" "2025-03-14" "Git 2\&.49\&.0" "Git Manual"
  11. .\" -----------------------------------------------------------------
  12. .\" * Define some portability stuff
  13. .\" -----------------------------------------------------------------
  14. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15. .\" http://bugs.debian.org/507673
  16. .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18. .ie \n(.g .ds Aq \(aq
  19. .el .ds Aq '
  20. .\" -----------------------------------------------------------------
  21. .\" * set default formatting
  22. .\" -----------------------------------------------------------------
  23. .\" disable hyphenation
  24. .nh
  25. .\" disable justification (adjust text to left margin only)
  26. .ad l
  27. .\" -----------------------------------------------------------------
  28. .\" * MAIN CONTENT STARTS HERE *
  29. .\" -----------------------------------------------------------------
  30. .SH "NAME"
  31. git-maintenance \- Run tasks to optimize Git repository data
  32. .SH "SYNOPSIS"
  33. .sp
  34. .nf
  35. \fIgit maintenance\fR run [<options>]
  36. \fIgit maintenance\fR start [\-\-scheduler=<scheduler>]
  37. \fIgit maintenance\fR (stop|register|unregister) [<options>]
  38. .fi
  39. .SH "DESCRIPTION"
  40. .sp
  41. Run tasks to optimize Git repository data, speeding up other Git commands and reducing storage requirements for the repository\&.
  42. .sp
  43. Git commands that add repository data, such as \fBgit\fR \fBadd\fR or \fBgit\fR \fBfetch\fR, are optimized for a responsive user experience\&. These commands do not take time to optimize the Git data, since such optimizations scale with the full size of the repository while these user commands each perform a relatively small action\&.
  44. .sp
  45. The \fBgit\fR \fBmaintenance\fR command provides flexibility for how to optimize the Git repository\&.
  46. .SH "SUBCOMMANDS"
  47. .PP
  48. run
  49. .RS 4
  50. Run one or more maintenance tasks\&. If one or more
  51. \fB\-\-task\fR
  52. options are specified, then those tasks are run in that order\&. Otherwise, the tasks are determined by which
  53. \fBmaintenance\&.\fR\fI<task>\fR\fB\&.enabled\fR
  54. config options are true\&. By default, only
  55. \fBmaintenance\&.gc\&.enabled\fR
  56. is true\&.
  57. .RE
  58. .PP
  59. start
  60. .RS 4
  61. Start running maintenance on the current repository\&. This performs the same config updates as the
  62. \fBregister\fR
  63. subcommand, then updates the background scheduler to run
  64. \fBgit\fR
  65. \fBmaintenance\fR
  66. \fBrun\fR
  67. \fB\-\-scheduled\fR
  68. on an hourly basis\&.
  69. .RE
  70. .PP
  71. stop
  72. .RS 4
  73. Halt the background maintenance schedule\&. The current repository is not removed from the list of maintained repositories, in case the background maintenance is restarted later\&.
  74. .RE
  75. .PP
  76. register
  77. .RS 4
  78. Initialize Git config values so any scheduled maintenance will start running on this repository\&. This adds the repository to the
  79. \fBmaintenance\&.repo\fR
  80. config variable in the current user\(cqs global config, or the config specified by \-\-config\-file option, and enables some recommended configuration values for
  81. \fBmaintenance\&.\fR\fI<task>\fR\fB\&.schedule\fR\&. The tasks that are enabled are safe for running in the background without disrupting foreground processes\&.
  82. .sp
  83. The
  84. \fBregister\fR
  85. subcommand will also set the
  86. \fBmaintenance\&.strategy\fR
  87. config value to
  88. \fBincremental\fR, if this value is not previously set\&. The
  89. \fBincremental\fR
  90. strategy uses the following schedule for each maintenance task:
  91. .sp
  92. .RS 4
  93. .ie n \{\
  94. \h'-04'\(bu\h'+03'\c
  95. .\}
  96. .el \{\
  97. .sp -1
  98. .IP \(bu 2.3
  99. .\}
  100. \fBgc\fR: disabled\&.
  101. .RE
  102. .sp
  103. .RS 4
  104. .ie n \{\
  105. \h'-04'\(bu\h'+03'\c
  106. .\}
  107. .el \{\
  108. .sp -1
  109. .IP \(bu 2.3
  110. .\}
  111. \fBcommit\-graph\fR: hourly\&.
  112. .RE
  113. .sp
  114. .RS 4
  115. .ie n \{\
  116. \h'-04'\(bu\h'+03'\c
  117. .\}
  118. .el \{\
  119. .sp -1
  120. .IP \(bu 2.3
  121. .\}
  122. \fBprefetch\fR: hourly\&.
  123. .RE
  124. .sp
  125. .RS 4
  126. .ie n \{\
  127. \h'-04'\(bu\h'+03'\c
  128. .\}
  129. .el \{\
  130. .sp -1
  131. .IP \(bu 2.3
  132. .\}
  133. \fBloose\-objects\fR: daily\&.
  134. .RE
  135. .sp
  136. .RS 4
  137. .ie n \{\
  138. \h'-04'\(bu\h'+03'\c
  139. .\}
  140. .el \{\
  141. .sp -1
  142. .IP \(bu 2.3
  143. .\}
  144. \fBincremental\-repack\fR: daily\&.
  145. .RE
  146. .sp
  147. \fBgit\fR
  148. \fBmaintenance\fR
  149. \fBregister\fR
  150. will also disable foreground maintenance by setting
  151. \fBmaintenance\&.auto\fR
  152. \fB=\fR
  153. \fBfalse\fR
  154. in the current repository\&. This config setting will remain after a
  155. \fBgit\fR
  156. \fBmaintenance\fR
  157. \fBunregister\fR
  158. command\&.
  159. .RE
  160. .PP
  161. unregister
  162. .RS 4
  163. Remove the current repository from background maintenance\&. This only removes the repository from the configured list\&. It does not stop the background maintenance processes from running\&.
  164. .sp
  165. The
  166. \fBunregister\fR
  167. subcommand will report an error if the current repository is not already registered\&. Use the
  168. \fB\-\-force\fR
  169. option to return success even when the current repository is not registered\&.
  170. .RE
  171. .SH "TASKS"
  172. .PP
  173. commit\-graph
  174. .RS 4
  175. The
  176. \fBcommit\-graph\fR
  177. job updates the
  178. \fBcommit\-graph\fR
  179. files incrementally, then verifies that the written data is correct\&. The incremental write is safe to run alongside concurrent Git processes since it will not expire \&.\fBgraph\fR
  180. files that were in the previous
  181. \fBcommit\-graph\-chain\fR
  182. file\&. They will be deleted by a later run based on the expiration delay\&.
  183. .RE
  184. .PP
  185. prefetch
  186. .RS 4
  187. The
  188. \fBprefetch\fR
  189. task updates the object directory with the latest objects from all registered remotes\&. For each remote, a
  190. \fBgit\fR
  191. \fBfetch\fR
  192. command is run\&. The configured refspec is modified to place all requested refs within
  193. \fBrefs/prefetch/\fR\&. Also, tags are not updated\&.
  194. .sp
  195. This is done to avoid disrupting the remote\-tracking branches\&. The end users expect these refs to stay unmoved unless they initiate a fetch\&. However, with the prefetch task, the objects necessary to complete a later real fetch would already be obtained, making the real fetch faster\&. In the ideal case, it will just become an update to a bunch of remote\-tracking branches without any object transfer\&.
  196. .sp
  197. The
  198. \fBremote\&.\fR\fI<name>\fR\fB\&.skipFetchAll\fR
  199. configuration can be used to exclude a particular remote from getting prefetched\&.
  200. .RE
  201. .PP
  202. gc
  203. .RS 4
  204. Clean up unnecessary files and optimize the local repository\&. "GC" stands for "garbage collection," but this task performs many smaller tasks\&. This task can be expensive for large repositories, as it repacks all Git objects into a single pack\-file\&. It can also be disruptive in some situations, as it deletes stale data\&. See
  205. \fBgit-gc\fR(1)
  206. for more details on garbage collection in Git\&.
  207. .RE
  208. .PP
  209. loose\-objects
  210. .RS 4
  211. The
  212. \fBloose\-objects\fR
  213. job cleans up loose objects and places them into pack\-files\&. In order to prevent race conditions with concurrent Git commands, it follows a two\-step process\&. First, it deletes any loose objects that already exist in a pack\-file; concurrent Git processes will examine the pack\-file for the object data instead of the loose object\&. Second, it creates a new pack\-file (starting with "loose\-") containing a batch of loose objects\&. The batch size is limited to 50 thousand objects to prevent the job from taking too long on a repository with many loose objects\&. The
  214. \fBgc\fR
  215. task writes unreachable objects as loose objects to be cleaned up by a later step only if they are not re\-added to a pack\-file; for this reason it is not advisable to enable both the
  216. \fBloose\-objects\fR
  217. and
  218. \fBgc\fR
  219. tasks at the same time\&.
  220. .RE
  221. .PP
  222. incremental\-repack
  223. .RS 4
  224. The
  225. \fBincremental\-repack\fR
  226. job repacks the object directory using the
  227. \fBmulti\-pack\-index\fR
  228. feature\&. In order to prevent race conditions with concurrent Git commands, it follows a two\-step process\&. First, it calls
  229. \fBgit\fR
  230. \fBmulti\-pack\-index\fR
  231. \fBexpire\fR
  232. to delete pack\-files unreferenced by the
  233. \fBmulti\-pack\-index\fR
  234. file\&. Second, it calls
  235. \fBgit\fR
  236. \fBmulti\-pack\-index\fR
  237. \fBrepack\fR
  238. to select several small pack\-files and repack them into a bigger one, and then update the
  239. \fBmulti\-pack\-index\fR
  240. entries that refer to the small pack\-files to refer to the new pack\-file\&. This prepares those small pack\-files for deletion upon the next run of
  241. \fBgit\fR
  242. \fBmulti\-pack\-index\fR
  243. \fBexpire\fR\&. The selection of the small pack\-files is such that the expected size of the big pack\-file is at least the batch size; see the
  244. \fB\-\-batch\-size\fR
  245. option for the
  246. \fBrepack\fR
  247. subcommand in
  248. \fBgit-multi-pack-index\fR(1)\&. The default batch\-size is zero, which is a special case that attempts to repack all pack\-files into a single pack\-file\&.
  249. .RE
  250. .PP
  251. pack\-refs
  252. .RS 4
  253. The
  254. \fBpack\-refs\fR
  255. task collects the loose reference files and collects them into a single file\&. This speeds up operations that need to iterate across many references\&. See
  256. \fBgit-pack-refs\fR(1)
  257. for more information\&.
  258. .RE
  259. .SH "OPTIONS"
  260. .PP
  261. \-\-auto
  262. .RS 4
  263. When combined with the
  264. \fBrun\fR
  265. subcommand, run maintenance tasks only if certain thresholds are met\&. For example, the
  266. \fBgc\fR
  267. task runs when the number of loose objects exceeds the number stored in the
  268. \fBgc\&.auto\fR
  269. config setting, or when the number of pack\-files exceeds the
  270. \fBgc\&.autoPackLimit\fR
  271. config setting\&. Not compatible with the
  272. \fB\-\-schedule\fR
  273. option\&.
  274. .RE
  275. .PP
  276. \-\-schedule
  277. .RS 4
  278. When combined with the
  279. \fBrun\fR
  280. subcommand, run maintenance tasks only if certain time conditions are met, as specified by the
  281. \fBmaintenance\&.\fR\fI<task>\fR\fB\&.schedule\fR
  282. config value for each
  283. \fI<task>\fR\&. This config value specifies a number of seconds since the last time that task ran, according to the
  284. \fBmaintenance\&.\fR\fI<task>\fR\fB\&.lastRun\fR
  285. config value\&. The tasks that are tested are those provided by the
  286. \fB\-\-task=\fR\fI<task>\fR
  287. option(s) or those with
  288. \fBmaintenance\&.\fR\fI<task>\fR\fB\&.enabled\fR
  289. set to true\&.
  290. .RE
  291. .PP
  292. \-\-quiet
  293. .RS 4
  294. Do not report progress or other information over
  295. \fBstderr\fR\&.
  296. .RE
  297. .PP
  298. \-\-task=<task>
  299. .RS 4
  300. If this option is specified one or more times, then only run the specified tasks in the specified order\&. If no
  301. \fB\-\-task=\fR\fI<task>\fR
  302. arguments are specified, then only the tasks with
  303. \fBmaintenance\&.\fR\fI<task>\fR\fB\&.enabled\fR
  304. configured as
  305. \fBtrue\fR
  306. are considered\&. See the
  307. \fITASKS\fR
  308. section for the list of accepted
  309. \fI<task>\fR
  310. values\&.
  311. .RE
  312. .PP
  313. \-\-scheduler=auto|crontab|systemd\-timer|launchctl|schtasks
  314. .RS 4
  315. When combined with the
  316. \fBstart\fR
  317. subcommand, specify the scheduler for running the hourly, daily and weekly executions of
  318. \fBgit\fR
  319. \fBmaintenance\fR
  320. \fBrun\fR\&. Possible values for
  321. \fI<scheduler>\fR
  322. are
  323. \fBauto\fR,
  324. \fBcrontab\fR
  325. (POSIX),
  326. \fBsystemd\-timer\fR
  327. (Linux),
  328. \fBlaunchctl\fR
  329. (macOS), and
  330. \fBschtasks\fR
  331. (Windows)\&. When
  332. \fBauto\fR
  333. is specified, the appropriate platform\-specific scheduler is used; on Linux,
  334. \fBsystemd\-timer\fR
  335. is used if available, otherwise
  336. \fBcrontab\fR\&. Default is
  337. \fBauto\fR\&.
  338. .RE
  339. .SH "TROUBLESHOOTING"
  340. .sp
  341. The \fBgit\fR \fBmaintenance\fR 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\&.
  342. .sp
  343. Users may find some cases where scheduled maintenance tasks do not run as frequently as intended\&. Each \fBgit\fR \fBmaintenance\fR \fBrun\fR command takes a lock on the repository\(cqs object database, and this prevents other concurrent \fBgit\fR \fBmaintenance\fR \fBrun\fR commands from running on the same repository\&. Without this safeguard, competing processes could leave the repository in an unpredictable state\&.
  344. .sp
  345. The background maintenance schedule runs \fBgit\fR \fBmaintenance\fR \fBrun\fR 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 \fBgit\fR \fBmaintenance\fR \fBrun\fR 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\&.
  346. .sp
  347. 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 \fBgc\fR task is much slower than the \fBincremental\-repack\fR task\&. However, this comes at a cost of a slightly larger object database\&. Consider moving more expensive tasks to be run less frequently\&.
  348. .sp
  349. Expert users may consider scheduling their own maintenance tasks using a different schedule than is available through \fBgit\fR \fBmaintenance\fR \fBstart\fR and Git configuration options\&. These users should be aware of the object database lock and how concurrent \fBgit\fR \fBmaintenance\fR \fBrun\fR commands behave\&. Further, the \fBgit\fR \fBgc\fR command should not be combined with \fBgit\fR \fBmaintenance\fR \fBrun\fR commands\&. \fBgit\fR \fBgc\fR modifies the object database but does not take the lock in the same way as \fBgit\fR \fBmaintenance\fR \fBrun\fR\&. If possible, use \fBgit\fR \fBmaintenance\fR \fBrun\fR \fB\-\-task=gc\fR instead of \fBgit\fR \fBgc\fR\&.
  350. .sp
  351. The following sections describe the mechanisms put in place to run background maintenance by \fBgit\fR \fBmaintenance\fR \fBstart\fR and how to customize them\&.
  352. .SH "BACKGROUND MAINTENANCE ON POSIX SYSTEMS"
  353. .sp
  354. 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 \fBcrontab\fR \fB\-l\fR\&. The schedule written by \fBgit\fR \fBmaintenance\fR \fBstart\fR is similar to this:
  355. .sp
  356. .if n \{\
  357. .RS 4
  358. .\}
  359. .nf
  360. # BEGIN GIT MAINTENANCE SCHEDULE
  361. # The following schedule was created by Git
  362. # Any edits made in this region might be
  363. # replaced in the future by a Git command\&.
  364. 0 1\-23 * * * "/<path>/git" \-\-exec\-path="/<path>" for\-each\-repo \-\-config=maintenance\&.repo maintenance run \-\-schedule=hourly
  365. 0 0 * * 1\-6 "/<path>/git" \-\-exec\-path="/<path>" for\-each\-repo \-\-config=maintenance\&.repo maintenance run \-\-schedule=daily
  366. 0 0 * * 0 "/<path>/git" \-\-exec\-path="/<path>" for\-each\-repo \-\-config=maintenance\&.repo maintenance run \-\-schedule=weekly
  367. # END GIT MAINTENANCE SCHEDULE
  368. .fi
  369. .if n \{\
  370. .RE
  371. .\}
  372. .sp
  373. 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 \fBgit\fR \fBmaintenance\fR \fBstop\fR or overwritten by \fBgit\fR \fBmaintenance\fR \fBstart\fR\&.
  374. .sp
  375. The \fBcrontab\fR entry specifies the full path of the \fBgit\fR executable to ensure that the executed \fBgit\fR command is the same one with which \fBgit\fR \fBmaintenance\fR \fBstart\fR was issued independent of \fBPATH\fR\&. If the same user runs \fBgit\fR \fBmaintenance\fR \fBstart\fR with multiple Git executables, then only the latest executable is used\&.
  376. .sp
  377. These commands use \fBgit\fR \fBfor\-each\-repo\fR \fB\-\-config=maintenance\&.repo\fR to run \fBgit\fR \fBmaintenance\fR \fBrun\fR \fB\-\-schedule=\fR\fI<frequency>\fR on each repository listed in the multi\-valued \fBmaintenance\&.repo\fR config option\&. These are typically loaded from the user\-specific global config\&. The \fBgit\fR \fBmaintenance\fR process then determines which maintenance tasks are configured to run on each repository with each \fI<frequency>\fR using the \fBmaintenance\&.\fR\fI<task>\fR\fB\&.schedule\fR config options\&. These values are loaded from the global or repository config values\&.
  378. .sp
  379. If the config values are insufficient to achieve your desired background maintenance schedule, then you can create your own schedule\&. If you run \fBcrontab\fR \fB\-e\fR, then an editor will load with your user\-specific \fBcron\fR schedule\&. In that editor, you can add your own schedule lines\&. You could start by adapting the default schedule listed earlier, or you could read the crontab(5) documentation for advanced scheduling techniques\&. Please do use the full path and \fB\-\-exec\-path\fR techniques from the default schedule to ensure you are executing the correct binaries in your schedule\&.
  380. .SH "BACKGROUND MAINTENANCE ON LINUX SYSTEMD SYSTEMS"
  381. .sp
  382. While Linux supports \fBcron\fR, depending on the distribution, \fBcron\fR may be an optional package not necessarily installed\&. On modern Linux distributions, systemd timers are superseding it\&.
  383. .sp
  384. If user systemd timers are available, they will be used as a replacement of \fBcron\fR\&.
  385. .sp
  386. In this case, \fBgit\fR \fBmaintenance\fR \fBstart\fR will create user systemd timer units and start the timers\&. The current list of user\-scheduled tasks can be found by running \fBsystemctl\fR \fB\-\-user\fR \fBlist\-timers\fR\&. The timers written by \fBgit\fR \fBmaintenance\fR \fBstart\fR are similar to this:
  387. .sp
  388. .if n \{\
  389. .RS 4
  390. .\}
  391. .nf
  392. $ systemctl \-\-user list\-timers
  393. NEXT LEFT LAST PASSED UNIT ACTIVATES
  394. Thu 2021\-04\-29 19:00:00 CEST 42min left Thu 2021\-04\-29 18:00:11 CEST 17min ago git\-maintenance@hourly\&.timer git\-maintenance@hourly\&.service
  395. Fri 2021\-04\-30 00:00:00 CEST 5h 42min left Thu 2021\-04\-29 00:00:11 CEST 18h ago git\-maintenance@daily\&.timer git\-maintenance@daily\&.service
  396. Mon 2021\-05\-03 00:00:00 CEST 3 days left Mon 2021\-04\-26 00:00:11 CEST 3 days ago git\-maintenance@weekly\&.timer git\-maintenance@weekly\&.service
  397. .fi
  398. .if n \{\
  399. .RE
  400. .\}
  401. .sp
  402. One timer is registered for each \fB\-\-schedule=\fR\fI<frequency>\fR option\&.
  403. .sp
  404. The definition of the systemd units can be inspected in the following files:
  405. .sp
  406. .if n \{\
  407. .RS 4
  408. .\}
  409. .nf
  410. ~/\&.config/systemd/user/git\-maintenance@\&.timer
  411. ~/\&.config/systemd/user/git\-maintenance@\&.service
  412. ~/\&.config/systemd/user/timers\&.target\&.wants/git\-maintenance@hourly\&.timer
  413. ~/\&.config/systemd/user/timers\&.target\&.wants/git\-maintenance@daily\&.timer
  414. ~/\&.config/systemd/user/timers\&.target\&.wants/git\-maintenance@weekly\&.timer
  415. .fi
  416. .if n \{\
  417. .RE
  418. .\}
  419. .sp
  420. \fBgit\fR \fBmaintenance\fR \fBstart\fR will overwrite these files and start the timer again with \fBsystemctl\fR \fB\-\-user\fR, so any customization should be done by creating a drop\-in file, i\&.e\&. a \&.\fBconf\fR suffixed file in the \fB~/\&.config/systemd/user/git\-maintenance@\&.service\&.d\fR directory\&.
  421. .sp
  422. \fBgit\fR \fBmaintenance\fR \fBstop\fR will stop the user systemd timers and delete the above mentioned files\&.
  423. .sp
  424. For more details, see \fBsystemd\&.timer\fR(\fB5\fR)\&.
  425. .SH "BACKGROUND MAINTENANCE ON MACOS SYSTEMS"
  426. .sp
  427. While macOS technically supports \fBcron\fR, using \fBcrontab\fR \fB\-e\fR requires elevated privileges and the executed process does not have a full user context\&. Without a full user context, Git and its credential helpers cannot access stored credentials, so some maintenance tasks are not functional\&.
  428. .sp
  429. Instead, \fBgit\fR \fBmaintenance\fR \fBstart\fR interacts with the \fBlaunchctl\fR tool, which is the recommended way to schedule timed jobs in macOS\&. Scheduling maintenance through \fBgit\fR \fBmaintenance\fR (\fBstart\fR|\fBstop\fR) requires some \fBlaunchctl\fR features available only in macOS 10\&.11 or later\&.
  430. .sp
  431. Your user\-specific scheduled tasks are stored as XML\-formatted \&.\fBplist\fR files in \fB~/Library/LaunchAgents/\fR\&. You can see the currently\-registered tasks using the following command:
  432. .sp
  433. .if n \{\
  434. .RS 4
  435. .\}
  436. .nf
  437. $ ls ~/Library/LaunchAgents/org\&.git\-scm\&.git*
  438. org\&.git\-scm\&.git\&.daily\&.plist
  439. org\&.git\-scm\&.git\&.hourly\&.plist
  440. org\&.git\-scm\&.git\&.weekly\&.plist
  441. .fi
  442. .if n \{\
  443. .RE
  444. .\}
  445. .sp
  446. One task is registered for each \fB\-\-schedule=\fR\fI<frequency>\fR option\&. To inspect how the XML format describes each schedule, open one of these \&.\fBplist\fR files in an editor and inspect the \fI<array>\fR element following the \fI<key>\fR\fBStartCalendarInterval\fR</key> element\&.
  447. .sp
  448. \fBgit\fR \fBmaintenance\fR \fBstart\fR will overwrite these files and register the tasks again with \fBlaunchctl\fR, so any customizations should be done by creating your own \&.\fBplist\fR files with distinct names\&. Similarly, the \fBgit\fR \fBmaintenance\fR \fBstop\fR command will unregister the tasks with \fBlaunchctl\fR and delete the \&.\fBplist\fR files\&.
  449. .sp
  450. To create more advanced customizations to your background tasks, see launchctl\&.plist(5) for more information\&.
  451. .SH "BACKGROUND MAINTENANCE ON WINDOWS SYSTEMS"
  452. .sp
  453. Windows does not support \fBcron\fR and instead has its own system for scheduling background tasks\&. The \fBgit\fR \fBmaintenance\fR \fBstart\fR command uses the \fBschtasks\fR command to submit tasks to this system\&. You can inspect all background tasks using the Task Scheduler application\&. The tasks added by Git have names of the form \fBGit\fR \fBMaintenance\fR (\fI<frequency>\fR)\&. The Task Scheduler GUI has ways to inspect these tasks, but you can also export the tasks to XML files and view the details there\&.
  454. .sp
  455. Note that since Git is a console application, these background tasks create a console window visible to the current user\&. This can be changed manually by selecting the "Run whether user is logged in or not" option in Task Scheduler\&. This change requires a password input, which is why \fBgit\fR \fBmaintenance\fR \fBstart\fR does not select it by default\&.
  456. .sp
  457. If you want to customize the background tasks, please rename the tasks so future calls to \fBgit\fR \fBmaintenance\fR (\fBstart\fR|\fBstop\fR) do not overwrite your custom tasks\&.
  458. .SH "CONFIGURATION"
  459. .sp
  460. Everything below this line in this section is selectively included from the \fBgit-config\fR(1) documentation\&. The content is the same as what\(cqs found there:
  461. .PP
  462. maintenance\&.auto
  463. .RS 4
  464. This boolean config option controls whether some commands run
  465. \fBgit\fR
  466. \fBmaintenance\fR
  467. \fBrun\fR
  468. \fB\-\-auto\fR
  469. after doing their normal work\&. Defaults to true\&.
  470. .RE
  471. .PP
  472. maintenance\&.autoDetach
  473. .RS 4
  474. Many Git commands trigger automatic maintenance after they have written data into the repository\&. This boolean config option controls whether this automatic maintenance shall happen in the foreground or whether the maintenance process shall detach and continue to run in the background\&.
  475. .sp
  476. If unset, the value of
  477. \fBgc\&.autoDetach\fR
  478. is used as a fallback\&. Defaults to true if both are unset, meaning that the maintenance process will detach\&.
  479. .RE
  480. .PP
  481. maintenance\&.strategy
  482. .RS 4
  483. This string config option provides a way to specify one of a few recommended schedules for background maintenance\&. This only affects which tasks are run during
  484. \fBgit\fR
  485. \fBmaintenance\fR
  486. \fBrun\fR
  487. \fB\-\-schedule=X\fR
  488. commands, provided no
  489. \fB\-\-task=\fR\fI<task>\fR
  490. arguments are provided\&. Further, if a
  491. \fBmaintenance\&.\fR\fI<task>\fR\fB\&.schedule\fR
  492. config value is set, then that value is used instead of the one provided by
  493. \fBmaintenance\&.strategy\fR\&. The possible strategy strings are:
  494. .sp
  495. .RS 4
  496. .ie n \{\
  497. \h'-04'\(bu\h'+03'\c
  498. .\}
  499. .el \{\
  500. .sp -1
  501. .IP \(bu 2.3
  502. .\}
  503. \fBnone\fR: This default setting implies no tasks are run at any schedule\&.
  504. .RE
  505. .sp
  506. .RS 4
  507. .ie n \{\
  508. \h'-04'\(bu\h'+03'\c
  509. .\}
  510. .el \{\
  511. .sp -1
  512. .IP \(bu 2.3
  513. .\}
  514. \fBincremental\fR: This setting optimizes for performing small maintenance activities that do not delete any data\&. This does not schedule the
  515. \fBgc\fR
  516. task, but runs the
  517. \fBprefetch\fR
  518. and
  519. \fBcommit\-graph\fR
  520. tasks hourly, the
  521. \fBloose\-objects\fR
  522. and
  523. \fBincremental\-repack\fR
  524. tasks daily, and the
  525. \fBpack\-refs\fR
  526. task weekly\&.
  527. .RE
  528. .RE
  529. .PP
  530. maintenance\&.<task>\&.enabled
  531. .RS 4
  532. This boolean config option controls whether the maintenance task with name
  533. \fI<task>\fR
  534. is run when no
  535. \fB\-\-task\fR
  536. option is specified to
  537. \fBgit\fR
  538. \fBmaintenance\fR
  539. \fBrun\fR\&. These config values are ignored if a
  540. \fB\-\-task\fR
  541. option exists\&. By default, only
  542. \fBmaintenance\&.gc\&.enabled\fR
  543. is true\&.
  544. .RE
  545. .PP
  546. maintenance\&.<task>\&.schedule
  547. .RS 4
  548. This config option controls whether or not the given
  549. \fI<task>\fR
  550. runs during a
  551. \fBgit\fR
  552. \fBmaintenance\fR
  553. \fBrun\fR
  554. \fB\-\-schedule=\fR\fI<frequency>\fR
  555. command\&. The value must be one of "hourly", "daily", or "weekly"\&.
  556. .RE
  557. .PP
  558. maintenance\&.commit\-graph\&.auto
  559. .RS 4
  560. This integer config option controls how often the
  561. \fBcommit\-graph\fR
  562. task should be run as part of
  563. \fBgit\fR
  564. \fBmaintenance\fR
  565. \fBrun\fR
  566. \fB\-\-auto\fR\&. If zero, then the
  567. \fBcommit\-graph\fR
  568. task will not run with the
  569. \fB\-\-auto\fR
  570. option\&. A negative value will force the task to run every time\&. Otherwise, a positive value implies the command should run when the number of reachable commits that are not in the commit\-graph file is at least the value of
  571. \fBmaintenance\&.commit\-graph\&.auto\fR\&. The default value is 100\&.
  572. .RE
  573. .PP
  574. maintenance\&.loose\-objects\&.auto
  575. .RS 4
  576. This integer config option controls how often the
  577. \fBloose\-objects\fR
  578. task should be run as part of
  579. \fBgit\fR
  580. \fBmaintenance\fR
  581. \fBrun\fR
  582. \fB\-\-auto\fR\&. If zero, then the
  583. \fBloose\-objects\fR
  584. task will not run with the
  585. \fB\-\-auto\fR
  586. option\&. A negative value will force the task to run every time\&. Otherwise, a positive value implies the command should run when the number of loose objects is at least the value of
  587. \fBmaintenance\&.loose\-objects\&.auto\fR\&. The default value is 100\&.
  588. .RE
  589. .PP
  590. maintenance\&.incremental\-repack\&.auto
  591. .RS 4
  592. This integer config option controls how often the
  593. \fBincremental\-repack\fR
  594. task should be run as part of
  595. \fBgit\fR
  596. \fBmaintenance\fR
  597. \fBrun\fR
  598. \fB\-\-auto\fR\&. If zero, then the
  599. \fBincremental\-repack\fR
  600. task will not run with the
  601. \fB\-\-auto\fR
  602. option\&. A negative value will force the task to run every time\&. Otherwise, a positive value implies the command should run when the number of pack\-files not in the multi\-pack\-index is at least the value of
  603. \fBmaintenance\&.incremental\-repack\&.auto\fR\&. The default value is 10\&.
  604. .RE
  605. .SH "GIT"
  606. .sp
  607. Part of the \fBgit\fR(1) suite