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
12 Run tasks to optimize Git repository data, speeding up other Git
13 commands and reducing storage requirements for the repository.
14 Git commands that add repository data, such as git add or git fetch,
16 are optimized for a responsive user experience. These commands do not
17 take time to optimize the Git data, since such optimizations scale with
18 the full size of the repository while these user commands each perform
19 a relatively small action.
20 The git maintenance command provides flexibility for how to optimize
22 the Git repository.
23
25 register
26 Initialize Git config values so any scheduled maintenance will
27 start running on this repository. This adds the repository to the
28 maintenance.repo config variable in the current user’s global
29 config and enables some recommended configuration values for
30 maintenance.<task>.schedule. The tasks that are enabled are safe
31 for running in the background without disrupting foreground
32 processes.
33 The register subcommand will also set the maintenance.strategy
35 config value to incremental, if this value is not previously set.
36 The incremental strategy uses the following schedule for each
37 maintenance task:
38 • gc: disabled.
40 • commit-graph: hourly.
42 • prefetch: hourly.
44 • loose-objects: daily.
46 • incremental-repack: daily.
48 git maintenance register will also disable foreground maintenance
50 by setting maintenance.auto = false in the current repository. This
51 config setting will remain after a git maintenance unregister
52 command.
53 run
55 Run one or more maintenance tasks. If one or more --task options
56 are specified, then those tasks are run in that order. Otherwise,
57 the tasks are determined by which maintenance.<task>.enabled config
58 options are true. By default, only maintenance.gc.enabled is true.
59 start
61 Start running maintenance on the current repository. This performs
62 the same config updates as the register subcommand, then updates
63 the background scheduler to run git maintenance run --scheduled on
64 an hourly basis.
65 stop
67 Halt the background maintenance schedule. The current repository is
68 not removed from the list of maintained repositories, in case the
69 background maintenance is restarted later.
70 unregister
72 Remove the current repository from background maintenance. This
73 only removes the repository from the configured list. It does not
74 stop the background maintenance processes from running.
75
77 commit-graph
78 The commit-graph job updates the commit-graph files incrementally,
79 then verifies that the written data is correct. The incremental
80 write is safe to run alongside concurrent Git processes since it
81 will not expire .graph files that were in the previous
82 commit-graph-chain file. They will be deleted by a later run based
83 on the expiration delay.
84 prefetch
86 The prefetch task updates the object directory with the latest
87 objects from all registered remotes. For each remote, a git fetch
88 command is run. The configured refspec is modified to place all
89 requested refs within refs/prefetch/. Also, tags are not updated.
90 This is done to avoid disrupting the remote-tracking branches. The
92 end users expect these refs to stay unmoved unless they initiate a
93 fetch. With prefetch task, however, the objects necessary to
94 complete a later real fetch would already be obtained, so the real
95 fetch would go faster. In the ideal case, it will just become an
96 update to a bunch of remote-tracking branches without any object
97 transfer.
98 gc
100 Clean up unnecessary files and optimize the local repository. "GC"
101 stands for "garbage collection," but this task performs many
102 smaller tasks. This task can be expensive for large repositories,
103 as it repacks all Git objects into a single pack-file. It can also
104 be disruptive in some situations, as it deletes stale data. See
105 git-gc(1) for more details on garbage collection in Git.
106 loose-objects
108 The loose-objects job cleans up loose objects and places them into
109 pack-files. In order to prevent race conditions with concurrent Git
110 commands, it follows a two-step process. First, it deletes any
111 loose objects that already exist in a pack-file; concurrent Git
112 processes will examine the pack-file for the object data instead of
113 the loose object. Second, it creates a new pack-file (starting with
114 "loose-") containing a batch of loose objects. The batch size is
115 limited to 50 thousand objects to prevent the job from taking too
116 long on a repository with many loose objects. The gc task writes
117 unreachable objects as loose objects to be cleaned up by a later
118 step only if they are not re-added to a pack-file; for this reason
119 it is not advisable to enable both the loose-objects and gc tasks
120 at the same time.
121 incremental-repack
123 The incremental-repack job repacks the object directory using the
124 multi-pack-index feature. In order to prevent race conditions with
125 concurrent Git commands, it follows a two-step process. First, it
126 calls git multi-pack-index expire to delete pack-files unreferenced
127 by the multi-pack-index file. Second, it calls git multi-pack-index
128 repack to select several small pack-files and repack them into a
129 bigger one, and then update the multi-pack-index entries that refer
130 to the small pack-files to refer to the new pack-file. This
131 prepares those small pack-files for deletion upon the next run of
132 git multi-pack-index expire. The selection of the small pack-files
133 is such that the expected size of the big pack-file is at least the
134 batch size; see the --batch-size option for the repack subcommand
135 in git-multi-pack-index(1). The default batch-size is zero, which
136 is a special case that attempts to repack all pack-files into a
137 single pack-file.
138 pack-refs
140 The pack-refs task collects the loose reference files and collects
141 them into a single file. This speeds up operations that need to
142 iterate across many references. See git-pack-refs(1) for more
143 information.
144
146 --auto
147 When combined with the run subcommand, run maintenance tasks only
148 if certain thresholds are met. For example, the gc task runs when
149 the number of loose objects exceeds the number stored in the
150 gc.auto config setting, or when the number of pack-files exceeds
151 the gc.autoPackLimit config setting. Not compatible with the
152 --schedule option.
153 --schedule
155 When combined with the run subcommand, run maintenance tasks only
156 if certain time conditions are met, as specified by the
157 maintenance.<task>.schedule config value for each <task>. This
158 config value specifies a number of seconds since the last time that
159 task ran, according to the maintenance.<task>.lastRun config value.
160 The tasks that are tested are those provided by the --task=<task>
161 option(s) or those with maintenance.<task>.enabled set to true.
162 --quiet
164 Do not report progress or other information over stderr.
165 --task=<task>
167 If this option is specified one or more times, then only run the
168 specified tasks in the specified order. If no --task=<task>
169 arguments are specified, then only the tasks with
170 maintenance.<task>.enabled configured as true are considered. See
171 the TASKS section for the list of accepted <task> values.
172
174 The git maintenance command is designed to simplify the repository
175 maintenance patterns while minimizing user wait time during Git
176 commands. A variety of configuration options are available to allow
177 customizing this process. The default maintenance options focus on
178 operations that complete quickly, even on large repositories.
179 Users may find some cases where scheduled maintenance tasks do not run
181 as frequently as intended. Each git maintenance run command takes a
182 lock on the repository’s object database, and this prevents other
183 concurrent git maintenance run commands from running on the same
184 repository. Without this safeguard, competing processes could leave the
185 repository in an unpredictable state.
186 The background maintenance schedule runs git maintenance run processes
188 on an hourly basis. Each run executes the "hourly" tasks. At midnight,
189 that process also executes the "daily" tasks. At midnight on the first
190 day of the week, that process also executes the "weekly" tasks. A
191 single process iterates over each registered repository, performing the
192 scheduled tasks for that frequency. Depending on the number of
193 registered repositories and their sizes, this process may take longer
194 than an hour. In this case, multiple git maintenance run commands may
195 run on the same repository at the same time, colliding on the object
196 database lock. This results in one of the two tasks not running.
197 If you find that some maintenance windows are taking longer than one
199 hour to complete, then consider reducing the complexity of your
200 maintenance tasks. For example, the gc task is much slower than the
201 incremental-repack task. However, this comes at a cost of a slightly
202 larger object database. Consider moving more expensive tasks to be run
203 less frequently.
204 Expert users may consider scheduling their own maintenance tasks using
206 a different schedule than is available through git maintenance start
207 and Git configuration options. These users should be aware of the
208 object database lock and how concurrent git maintenance run commands
209 behave. Further, the git gc command should not be combined with git
210 maintenance run commands. git gc modifies the object database but does
211 not take the lock in the same way as git maintenance run. If possible,
212 use git maintenance run --task=gc instead of git gc.
213 The following sections describe the mechanisms put in place to run
215 background maintenance by git maintenance start and how to customize
216 them.
217
219 The standard mechanism for scheduling background tasks on POSIX systems
220 is cron(8). This tool executes commands based on a given schedule. The
221 current list of user-scheduled tasks can be found by running crontab
222 -l. The schedule written by git maintenance start is similar to this:
223 # BEGIN GIT MAINTENANCE SCHEDULE
225 # The following schedule was created by Git
226 # Any edits made in this region might be
227 # replaced in the future by a Git command.
228 0 1-23 * * * "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=hourly
230 0 0 * * 1-6 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=daily
231 0 0 * * 0 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=weekly
232 # END GIT MAINTENANCE SCHEDULE
234 The comments are used as a region to mark the schedule as written by
236 Git. Any modifications within this region will be completely deleted by
237 git maintenance stop or overwritten by git maintenance start.
238 The crontab entry specifies the full path of the git executable to
240 ensure that the executed git command is the same one with which git
241 maintenance start was issued independent of PATH. If the same user runs
242 git maintenance start with multiple Git executables, then only the
243 latest executable is used.
244 These commands use git for-each-repo --config=maintenance.repo to run
246 git maintenance run --schedule=<frequency> on each repository listed in
247 the multi-valued maintenance.repo config option. These are typically
248 loaded from the user-specific global config. The git maintenance
249 process then determines which maintenance tasks are configured to run
250 on each repository with each <frequency> using the
251 maintenance.<task>.schedule config options. These values are loaded
252 from the global or repository config values.
253 If the config values are insufficient to achieve your desired
255 background maintenance schedule, then you can create your own schedule.
256 If you run crontab -e, then an editor will load with your user-specific
257 cron schedule. In that editor, you can add your own schedule lines. You
258 could start by adapting the default schedule listed earlier, or you
259 could read the crontab(5) documentation for advanced scheduling
260 techniques. Please do use the full path and --exec-path techniques from
261 the default schedule to ensure you are executing the correct binaries
262 in your schedule.
263
265 While macOS technically supports cron, using crontab -e requires
266 elevated privileges and the executed process does not have a full user
267 context. Without a full user context, Git and its credential helpers
268 cannot access stored credentials, so some maintenance tasks are not
269 functional.
270 Instead, git maintenance start interacts with the launchctl tool, which
272 is the recommended way to schedule timed jobs in macOS. Scheduling
273 maintenance through git maintenance (start|stop) requires some
274 launchctl features available only in macOS 10.11 or later.
275 Your user-specific scheduled tasks are stored as XML-formatted .plist
277 files in ~/Library/LaunchAgents/. You can see the currently-registered
278 tasks using the following command:
279 $ ls ~/Library/LaunchAgents/org.git-scm.git*
281 org.git-scm.git.daily.plist
282 org.git-scm.git.hourly.plist
283 org.git-scm.git.weekly.plist
284 One task is registered for each --schedule=<frequency> option. To
286 inspect how the XML format describes each schedule, open one of these
287 .plist files in an editor and inspect the <array> element following the
288 <key>StartCalendarInterval</key> element.
289 git maintenance start will overwrite these files and register the tasks
291 again with launchctl, so any customizations should be done by creating
292 your own .plist files with distinct names. Similarly, the git
293 maintenance stop command will unregister the tasks with launchctl and
294 delete the .plist files.
295 To create more advanced customizations to your background tasks, see
297 launchctl.plist(5) for more information.
298
300 Windows does not support cron and instead has its own system for
301 scheduling background tasks. The git maintenance start command uses the
302 schtasks command to submit tasks to this system. You can inspect all
303 background tasks using the Task Scheduler application. The tasks added
304 by Git have names of the form Git Maintenance (<frequency>). The Task
305 Scheduler GUI has ways to inspect these tasks, but you can also export
306 the tasks to XML files and view the details there.
307 Note that since Git is a console application, these background tasks
309 create a console window visible to the current user. This can be
310 changed manually by selecting the "Run whether user is logged in or
311 not" option in Task Scheduler. This change requires a password input,
312 which is why git maintenance start does not select it by default.
313 If you want to customize the background tasks, please rename the tasks
315 so future calls to git maintenance (start|stop) do not overwrite your
316 custom tasks.
317
319 Part of the git(1) suite
320Git 2.33.1 2021-10-12 GIT-MAINTENANCE(1)