1GIT-MAINTENANCE(1) Git Manual GIT-MAINTENANCE(1)
2
6 git-maintenance - Run tasks to optimize Git repository data
7
9 git maintenance run [<options>]
10 git maintenance start [--scheduler=<scheduler>]
11 git maintenance (stop|register|unregister) [<options>]
12
14 Run tasks to optimize Git repository data, speeding up other Git
15 commands and reducing storage requirements for the repository.
16 Git commands that add repository data, such as git add or git fetch,
18 are optimized for a responsive user experience. These commands do not
19 take time to optimize the Git data, since such optimizations scale with
20 the full size of the repository while these user commands each perform
21 a relatively small action.
22 The git maintenance command provides flexibility for how to optimize
24 the Git repository.
25
27 run
28 Run one or more maintenance tasks. If one or more --task options
29 are specified, then those tasks are run in that order. Otherwise,
30 the tasks are determined by which maintenance.<task>.enabled config
31 options are true. By default, only maintenance.gc.enabled is true.
32 start
34 Start running maintenance on the current repository. This performs
35 the same config updates as the register subcommand, then updates
36 the background scheduler to run git maintenance run --scheduled on
37 an hourly basis.
38 stop
40 Halt the background maintenance schedule. The current repository is
41 not removed from the list of maintained repositories, in case the
42 background maintenance is restarted later.
43 register
45 Initialize Git config values so any scheduled maintenance will
46 start running on this repository. This adds the repository to the
47 maintenance.repo config variable in the current user’s global
48 config, or the config specified by --config-file option, and
49 enables some recommended configuration values for
50 maintenance.<task>.schedule. The tasks that are enabled are safe
51 for running in the background without disrupting foreground
52 processes.
53 The register subcommand will also set the maintenance.strategy
55 config value to incremental, if this value is not previously set.
56 The incremental strategy uses the following schedule for each
57 maintenance task:
58 • gc: disabled.
60 • commit-graph: hourly.
62 • prefetch: hourly.
64 • loose-objects: daily.
66 • incremental-repack: daily.
68 git maintenance register will also disable foreground maintenance
70 by setting maintenance.auto = false in the current repository. This
71 config setting will remain after a git maintenance unregister
72 command.
73 unregister
75 Remove the current repository from background maintenance. This
76 only removes the repository from the configured list. It does not
77 stop the background maintenance processes from running.
78 The unregister subcommand will report an error if the current
80 repository is not already registered. Use the --force option to
81 return success even when the current repository is not registered.
82
84 commit-graph
85 The commit-graph job updates the commit-graph files incrementally,
86 then verifies that the written data is correct. The incremental
87 write is safe to run alongside concurrent Git processes since it
88 will not expire .graph files that were in the previous
89 commit-graph-chain file. They will be deleted by a later run based
90 on the expiration delay.
91 prefetch
93 The prefetch task updates the object directory with the latest
94 objects from all registered remotes. For each remote, a git fetch
95 command is run. The configured refspec is modified to place all
96 requested refs within refs/prefetch/. Also, tags are not updated.
97 This is done to avoid disrupting the remote-tracking branches. The
99 end users expect these refs to stay unmoved unless they initiate a
100 fetch. However, with the prefetch task, the objects necessary to
101 complete a later real fetch would already be obtained, making the
102 real fetch faster. In the ideal case, it will just become an update
103 to a bunch of remote-tracking branches without any object transfer.
104 gc
106 Clean up unnecessary files and optimize the local repository. "GC"
107 stands for "garbage collection," but this task performs many
108 smaller tasks. This task can be expensive for large repositories,
109 as it repacks all Git objects into a single pack-file. It can also
110 be disruptive in some situations, as it deletes stale data. See
111 git-gc(1) for more details on garbage collection in Git.
112 loose-objects
114 The loose-objects job cleans up loose objects and places them into
115 pack-files. In order to prevent race conditions with concurrent Git
116 commands, it follows a two-step process. First, it deletes any
117 loose objects that already exist in a pack-file; concurrent Git
118 processes will examine the pack-file for the object data instead of
119 the loose object. Second, it creates a new pack-file (starting with
120 "loose-") containing a batch of loose objects. The batch size is
121 limited to 50 thousand objects to prevent the job from taking too
122 long on a repository with many loose objects. The gc task writes
123 unreachable objects as loose objects to be cleaned up by a later
124 step only if they are not re-added to a pack-file; for this reason
125 it is not advisable to enable both the loose-objects and gc tasks
126 at the same time.
127 incremental-repack
129 The incremental-repack job repacks the object directory using the
130 multi-pack-index feature. In order to prevent race conditions with
131 concurrent Git commands, it follows a two-step process. First, it
132 calls git multi-pack-index expire to delete pack-files unreferenced
133 by the multi-pack-index file. Second, it calls git multi-pack-index
134 repack to select several small pack-files and repack them into a
135 bigger one, and then update the multi-pack-index entries that refer
136 to the small pack-files to refer to the new pack-file. This
137 prepares those small pack-files for deletion upon the next run of
138 git multi-pack-index expire. The selection of the small pack-files
139 is such that the expected size of the big pack-file is at least the
140 batch size; see the --batch-size option for the repack subcommand
141 in git-multi-pack-index(1). The default batch-size is zero, which
142 is a special case that attempts to repack all pack-files into a
143 single pack-file.
144 pack-refs
146 The pack-refs task collects the loose reference files and collects
147 them into a single file. This speeds up operations that need to
148 iterate across many references. See git-pack-refs(1) for more
149 information.
150
152 --auto
153 When combined with the run subcommand, run maintenance tasks only
154 if certain thresholds are met. For example, the gc task runs when
155 the number of loose objects exceeds the number stored in the
156 gc.auto config setting, or when the number of pack-files exceeds
157 the gc.autoPackLimit config setting. Not compatible with the
158 --schedule option.
159 --schedule
161 When combined with the run subcommand, run maintenance tasks only
162 if certain time conditions are met, as specified by the
163 maintenance.<task>.schedule config value for each <task>. This
164 config value specifies a number of seconds since the last time that
165 task ran, according to the maintenance.<task>.lastRun config value.
166 The tasks that are tested are those provided by the --task=<task>
167 option(s) or those with maintenance.<task>.enabled set to true.
168 --quiet
170 Do not report progress or other information over stderr.
171 --task=<task>
173 If this option is specified one or more times, then only run the
174 specified tasks in the specified order. If no --task=<task>
175 arguments are specified, then only the tasks with
176 maintenance.<task>.enabled configured as true are considered. See
177 the TASKS section for the list of accepted <task> values.
178 --scheduler=auto|crontab|systemd-timer|launchctl|schtasks
180 When combined with the start subcommand, specify the scheduler for
181 running the hourly, daily and weekly executions of git maintenance
182 run. Possible values for <scheduler> are auto, crontab (POSIX),
183 systemd-timer (Linux), launchctl (macOS), and schtasks (Windows).
184 When auto is specified, the appropriate platform-specific scheduler
185 is used; on Linux, systemd-timer is used if available, otherwise
186 crontab. Default is auto.
187
189 The git maintenance command is designed to simplify the repository
190 maintenance patterns while minimizing user wait time during Git
191 commands. A variety of configuration options are available to allow
192 customizing this process. The default maintenance options focus on
193 operations that complete quickly, even on large repositories.
194 Users may find some cases where scheduled maintenance tasks do not run
196 as frequently as intended. Each git maintenance run command takes a
197 lock on the repository’s object database, and this prevents other
198 concurrent git maintenance run commands from running on the same
199 repository. Without this safeguard, competing processes could leave the
200 repository in an unpredictable state.
201 The background maintenance schedule runs git maintenance run processes
203 on an hourly basis. Each run executes the "hourly" tasks. At midnight,
204 that process also executes the "daily" tasks. At midnight on the first
205 day of the week, that process also executes the "weekly" tasks. A
206 single process iterates over each registered repository, performing the
207 scheduled tasks for that frequency. Depending on the number of
208 registered repositories and their sizes, this process may take longer
209 than an hour. In this case, multiple git maintenance run commands may
210 run on the same repository at the same time, colliding on the object
211 database lock. This results in one of the two tasks not running.
212 If you find that some maintenance windows are taking longer than one
214 hour to complete, then consider reducing the complexity of your
215 maintenance tasks. For example, the gc task is much slower than the
216 incremental-repack task. However, this comes at a cost of a slightly
217 larger object database. Consider moving more expensive tasks to be run
218 less frequently.
219 Expert users may consider scheduling their own maintenance tasks using
221 a different schedule than is available through git maintenance start
222 and Git configuration options. These users should be aware of the
223 object database lock and how concurrent git maintenance run commands
224 behave. Further, the git gc command should not be combined with git
225 maintenance run commands. git gc modifies the object database but does
226 not take the lock in the same way as git maintenance run. If possible,
227 use git maintenance run --task=gc instead of git gc.
228 The following sections describe the mechanisms put in place to run
230 background maintenance by git maintenance start and how to customize
231 them.
232
234 The standard mechanism for scheduling background tasks on POSIX systems
235 is cron(8). This tool executes commands based on a given schedule. The
236 current list of user-scheduled tasks can be found by running crontab
237 -l. The schedule written by git maintenance start is similar to this:
238 # BEGIN GIT MAINTENANCE SCHEDULE
240 # The following schedule was created by Git
241 # Any edits made in this region might be
242 # replaced in the future by a Git command.
243 0 1-23 * * * "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=hourly
245 0 0 * * 1-6 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=daily
246 0 0 * * 0 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=weekly
247 # END GIT MAINTENANCE SCHEDULE
249 The comments are used as a region to mark the schedule as written by
251 Git. Any modifications within this region will be completely deleted by
252 git maintenance stop or overwritten by git maintenance start.
253 The crontab entry specifies the full path of the git executable to
255 ensure that the executed git command is the same one with which git
256 maintenance start was issued independent of PATH. If the same user runs
257 git maintenance start with multiple Git executables, then only the
258 latest executable is used.
259 These commands use git for-each-repo --config=maintenance.repo to run
261 git maintenance run --schedule=<frequency> on each repository listed in
262 the multi-valued maintenance.repo config option. These are typically
263 loaded from the user-specific global config. The git maintenance
264 process then determines which maintenance tasks are configured to run
265 on each repository with each <frequency> using the
266 maintenance.<task>.schedule config options. These values are loaded
267 from the global or repository config values.
268 If the config values are insufficient to achieve your desired
270 background maintenance schedule, then you can create your own schedule.
271 If you run crontab -e, then an editor will load with your user-specific
272 cron schedule. In that editor, you can add your own schedule lines. You
273 could start by adapting the default schedule listed earlier, or you
274 could read the crontab(5) documentation for advanced scheduling
275 techniques. Please do use the full path and --exec-path techniques from
276 the default schedule to ensure you are executing the correct binaries
277 in your schedule.
278
280 While Linux supports cron, depending on the distribution, cron may be
281 an optional package not necessarily installed. On modern Linux
282 distributions, systemd timers are superseding it.
283 If user systemd timers are available, they will be used as a
285 replacement of cron.
286 In this case, git maintenance start will create user systemd timer
288 units and start the timers. The current list of user-scheduled tasks
289 can be found by running systemctl --user list-timers. The timers
290 written by git maintenance start are similar to this:
291 $ systemctl --user list-timers
293 NEXT LEFT LAST PASSED UNIT ACTIVATES
294 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
295 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
296 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
297 One timer is registered for each --schedule=<frequency> option.
299 The definition of the systemd units can be inspected in the following
301 files:
302 ~/.config/systemd/user/git-maintenance@.timer
304 ~/.config/systemd/user/git-maintenance@.service
305 ~/.config/systemd/user/timers.target.wants/git-maintenance@hourly.timer
306 ~/.config/systemd/user/timers.target.wants/git-maintenance@daily.timer
307 ~/.config/systemd/user/timers.target.wants/git-maintenance@weekly.timer
308 git maintenance start will overwrite these files and start the timer
310 again with systemctl --user, so any customization should be done by
311 creating a drop-in file, i.e. a .conf suffixed file in the
312 ~/.config/systemd/user/git-maintenance@.service.d directory.
313 git maintenance stop will stop the user systemd timers and delete the
315 above mentioned files.
316 For more details, see systemd.timer(5).
318
320 While macOS technically supports cron, using crontab -e requires
321 elevated privileges and the executed process does not have a full user
322 context. Without a full user context, Git and its credential helpers
323 cannot access stored credentials, so some maintenance tasks are not
324 functional.
325 Instead, git maintenance start interacts with the launchctl tool, which
327 is the recommended way to schedule timed jobs in macOS. Scheduling
328 maintenance through git maintenance (start|stop) requires some
329 launchctl features available only in macOS 10.11 or later.
330 Your user-specific scheduled tasks are stored as XML-formatted .plist
332 files in ~/Library/LaunchAgents/. You can see the currently-registered
333 tasks using the following command:
334 $ ls ~/Library/LaunchAgents/org.git-scm.git*
336 org.git-scm.git.daily.plist
337 org.git-scm.git.hourly.plist
338 org.git-scm.git.weekly.plist
339 One task is registered for each --schedule=<frequency> option. To
341 inspect how the XML format describes each schedule, open one of these
342 .plist files in an editor and inspect the <array> element following the
343 <key>StartCalendarInterval</key> element.
344 git maintenance start will overwrite these files and register the tasks
346 again with launchctl, so any customizations should be done by creating
347 your own .plist files with distinct names. Similarly, the git
348 maintenance stop command will unregister the tasks with launchctl and
349 delete the .plist files.
350 To create more advanced customizations to your background tasks, see
352 launchctl.plist(5) for more information.
353
355 Windows does not support cron and instead has its own system for
356 scheduling background tasks. The git maintenance start command uses the
357 schtasks command to submit tasks to this system. You can inspect all
358 background tasks using the Task Scheduler application. The tasks added
359 by Git have names of the form Git Maintenance (<frequency>). The Task
360 Scheduler GUI has ways to inspect these tasks, but you can also export
361 the tasks to XML files and view the details there.
362 Note that since Git is a console application, these background tasks
364 create a console window visible to the current user. This can be
365 changed manually by selecting the "Run whether user is logged in or
366 not" option in Task Scheduler. This change requires a password input,
367 which is why git maintenance start does not select it by default.
368 If you want to customize the background tasks, please rename the tasks
370 so future calls to git maintenance (start|stop) do not overwrite your
371 custom tasks.
372
374 Everything below this line in this section is selectively included from
375 the git-config(1) documentation. The content is the same as what’s
376 found there:
377 maintenance.auto
379 This boolean config option controls whether some commands run git
380 maintenance run --auto after doing their normal work. Defaults to
381 true.
382 maintenance.strategy
384 This string config option provides a way to specify one of a few
385 recommended schedules for background maintenance. This only affects
386 which tasks are run during git maintenance run --schedule=X
387 commands, provided no --task=<task> arguments are provided.
388 Further, if a maintenance.<task>.schedule config value is set, then
389 that value is used instead of the one provided by
390 maintenance.strategy. The possible strategy strings are:
391 • none: This default setting implies no tasks are run at any
393 schedule.
394 • incremental: This setting optimizes for performing small
396 maintenance activities that do not delete any data. This does
397 not schedule the gc task, but runs the prefetch and
398 commit-graph tasks hourly, the loose-objects and
399 incremental-repack tasks daily, and the pack-refs task weekly.
400 maintenance.<task>.enabled
402 This boolean config option controls whether the maintenance task
403 with name <task> is run when no --task option is specified to git
404 maintenance run. These config values are ignored if a --task option
405 exists. By default, only maintenance.gc.enabled is true.
406 maintenance.<task>.schedule
408 This config option controls whether or not the given <task> runs
409 during a git maintenance run --schedule=<frequency> command. The
410 value must be one of "hourly", "daily", or "weekly".
411 maintenance.commit-graph.auto
413 This integer config option controls how often the commit-graph task
414 should be run as part of git maintenance run --auto. If zero, then
415 the commit-graph task will not run with the --auto option. A
416 negative value will force the task to run every time. Otherwise, a
417 positive value implies the command should run when the number of
418 reachable commits that are not in the commit-graph file is at least
419 the value of maintenance.commit-graph.auto. The default value is
420 100.
421 maintenance.loose-objects.auto
423 This integer config option controls how often the loose-objects
424 task should be run as part of git maintenance run --auto. If zero,
425 then the loose-objects task will not run with the --auto option. A
426 negative value will force the task to run every time. Otherwise, a
427 positive value implies the command should run when the number of
428 loose objects is at least the value of
429 maintenance.loose-objects.auto. The default value is 100.
430 maintenance.incremental-repack.auto
432 This integer config option controls how often the
433 incremental-repack task should be run as part of git maintenance
434 run --auto. If zero, then the incremental-repack task will not run
435 with the --auto option. A negative value will force the task to run
436 every time. Otherwise, a positive value implies the command should
437 run when the number of pack-files not in the multi-pack-index is at
438 least the value of maintenance.incremental-repack.auto. The default
439 value is 10.
440
442 Part of the git(1) suite
443Git 2.43.0 11/20/2023 GIT-MAINTENANCE(1)