]>
Commit | Line | Data |
---|---|---|
2057d750 DS |
1 | git-maintenance(1) |
2 | ================== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-maintenance - Run tasks to optimize Git repository data | |
7 | ||
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
11 | [verse] | |
12 | 'git maintenance' run [<options>] | |
13 | ||
14 | ||
15 | DESCRIPTION | |
16 | ----------- | |
17 | Run tasks to optimize Git repository data, speeding up other Git commands | |
18 | and reducing storage requirements for the repository. | |
19 | ||
20 | Git commands that add repository data, such as `git add` or `git fetch`, | |
21 | are optimized for a responsive user experience. These commands do not take | |
22 | time to optimize the Git data, since such optimizations scale with the full | |
23 | size of the repository while these user commands each perform a relatively | |
24 | small action. | |
25 | ||
26 | The `git maintenance` command provides flexibility for how to optimize the | |
27 | Git repository. | |
28 | ||
29 | SUBCOMMANDS | |
30 | ----------- | |
31 | ||
0c18b700 DS |
32 | register:: |
33 | Initialize Git config values so any scheduled maintenance will | |
34 | start running on this repository. This adds the repository to the | |
35 | `maintenance.repo` config variable in the current user's global | |
36 | config and enables some recommended configuration values for | |
37 | `maintenance.<task>.schedule`. The tasks that are enabled are safe | |
38 | for running in the background without disrupting foreground | |
39 | processes. | |
61f7a383 | 40 | + |
7efc3782 | 41 | The `register` subcommand will also set the `maintenance.strategy` config |
61f7a383 DS |
42 | value to `incremental`, if this value is not previously set. The |
43 | `incremental` strategy uses the following schedule for each maintenance | |
44 | task: | |
45 | + | |
46 | -- | |
47 | * `gc`: disabled. | |
48 | * `commit-graph`: hourly. | |
49 | * `prefetch`: hourly. | |
50 | * `loose-objects`: daily. | |
51 | * `incremental-repack`: daily. | |
52 | -- | |
53 | + | |
54 | `git maintenance register` will also disable foreground maintenance by | |
55 | setting `maintenance.auto = false` in the current repository. This config | |
56 | setting will remain after a `git maintenance unregister` command. | |
0c18b700 | 57 | |
2057d750 | 58 | run:: |
65d655b5 DS |
59 | Run one or more maintenance tasks. If one or more `--task` options |
60 | are specified, then those tasks are run in that order. Otherwise, | |
61 | the tasks are determined by which `maintenance.<task>.enabled` | |
62 | config options are true. By default, only `maintenance.gc.enabled` | |
63 | is true. | |
2057d750 | 64 | |
2fec604f DS |
65 | start:: |
66 | Start running maintenance on the current repository. This performs | |
67 | the same config updates as the `register` subcommand, then updates | |
68 | the background scheduler to run `git maintenance run --scheduled` | |
69 | on an hourly basis. | |
70 | ||
71 | stop:: | |
72 | Halt the background maintenance schedule. The current repository | |
73 | is not removed from the list of maintained repositories, in case | |
74 | the background maintenance is restarted later. | |
75 | ||
0c18b700 DS |
76 | unregister:: |
77 | Remove the current repository from background maintenance. This | |
78 | only removes the repository from the configured list. It does not | |
79 | stop the background maintenance processes from running. | |
80 | ||
2057d750 DS |
81 | TASKS |
82 | ----- | |
83 | ||
663b2b1b DS |
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 | ||
28cb5e66 DS |
92 | 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 refmap is custom to avoid updating local or remote | |
96 | branches (those in `refs/heads` or `refs/remotes`). Instead, the | |
97 | remote refs are stored in `refs/prefetch/<remote>/`. Also, tags are | |
98 | not updated. | |
99 | + | |
100 | This is done to avoid disrupting the remote-tracking branches. The end users | |
101 | expect these refs to stay unmoved unless they initiate a fetch. With prefetch | |
102 | task, however, the objects necessary to complete a later real fetch would | |
103 | already be obtained, so the real fetch would go faster. In the ideal case, | |
83fcadd6 | 104 | it will just become an update to a bunch of remote-tracking branches without |
28cb5e66 DS |
105 | any object transfer. |
106 | ||
2057d750 DS |
107 | gc:: |
108 | Clean up unnecessary files and optimize the local repository. "GC" | |
109 | stands for "garbage collection," but this task performs many | |
110 | smaller tasks. This task can be expensive for large repositories, | |
111 | as it repacks all Git objects into a single pack-file. It can also | |
112 | be disruptive in some situations, as it deletes stale data. See | |
113 | linkgit:git-gc[1] for more details on garbage collection in Git. | |
114 | ||
252cfb7c DS |
115 | loose-objects:: |
116 | The `loose-objects` job cleans up loose objects and places them into | |
117 | pack-files. In order to prevent race conditions with concurrent Git | |
118 | commands, it follows a two-step process. First, it deletes any loose | |
119 | objects that already exist in a pack-file; concurrent Git processes | |
120 | will examine the pack-file for the object data instead of the loose | |
121 | object. Second, it creates a new pack-file (starting with "loose-") | |
122 | containing a batch of loose objects. The batch size is limited to 50 | |
123 | thousand objects to prevent the job from taking too long on a | |
124 | repository with many loose objects. The `gc` task writes unreachable | |
125 | objects as loose objects to be cleaned up by a later step only if | |
126 | they are not re-added to a pack-file; for this reason it is not | |
127 | advisable to enable both the `loose-objects` and `gc` tasks at the | |
128 | same time. | |
129 | ||
52fe41ff DS |
130 | incremental-repack:: |
131 | The `incremental-repack` job repacks the object directory | |
132 | using the `multi-pack-index` feature. In order to prevent race | |
133 | conditions with concurrent Git commands, it follows a two-step | |
134 | process. First, it calls `git multi-pack-index expire` to delete | |
135 | pack-files unreferenced by the `multi-pack-index` file. Second, it | |
136 | calls `git multi-pack-index repack` to select several small | |
137 | pack-files and repack them into a bigger one, and then update the | |
138 | `multi-pack-index` entries that refer to the small pack-files to | |
139 | refer to the new pack-file. This prepares those small pack-files | |
140 | for deletion upon the next run of `git multi-pack-index expire`. | |
141 | The selection of the small pack-files is such that the expected | |
142 | size of the big pack-file is at least the batch size; see the | |
143 | `--batch-size` option for the `repack` subcommand in | |
144 | linkgit:git-multi-pack-index[1]. The default batch-size is zero, | |
145 | which is a special case that attempts to repack all pack-files | |
146 | into a single pack-file. | |
147 | ||
2057d750 DS |
148 | OPTIONS |
149 | ------- | |
150 | --auto:: | |
151 | When combined with the `run` subcommand, run maintenance tasks | |
152 | only if certain thresholds are met. For example, the `gc` task | |
153 | runs when the number of loose objects exceeds the number stored | |
154 | in the `gc.auto` config setting, or when the number of pack-files | |
b08ff1fe DS |
155 | exceeds the `gc.autoPackLimit` config setting. Not compatible with |
156 | the `--schedule` option. | |
157 | ||
158 | --schedule:: | |
159 | When combined with the `run` subcommand, run maintenance tasks | |
160 | only if certain time conditions are met, as specified by the | |
161 | `maintenance.<task>.schedule` config value for each `<task>`. | |
162 | This config value specifies a number of seconds since the last | |
163 | time that task ran, according to the `maintenance.<task>.lastRun` | |
164 | config value. The tasks that are tested are those provided by | |
165 | the `--task=<task>` option(s) or those with | |
166 | `maintenance.<task>.enabled` set to true. | |
2057d750 | 167 | |
3ddaad0e DS |
168 | --quiet:: |
169 | Do not report progress or other information over `stderr`. | |
170 | ||
090511bc DS |
171 | --task=<task>:: |
172 | If this option is specified one or more times, then only run the | |
65d655b5 DS |
173 | specified tasks in the specified order. If no `--task=<task>` |
174 | arguments are specified, then only the tasks with | |
175 | `maintenance.<task>.enabled` configured as `true` are considered. | |
176 | See the 'TASKS' section for the list of accepted `<task>` values. | |
090511bc | 177 | |
0016b618 DS |
178 | |
179 | TROUBLESHOOTING | |
180 | --------------- | |
181 | The `git maintenance` command is designed to simplify the repository | |
182 | maintenance patterns while minimizing user wait time during Git commands. | |
183 | A variety of configuration options are available to allow customizing this | |
184 | process. The default maintenance options focus on operations that complete | |
185 | quickly, even on large repositories. | |
186 | ||
187 | Users may find some cases where scheduled maintenance tasks do not run as | |
188 | frequently as intended. Each `git maintenance run` command takes a lock on | |
189 | the repository's object database, and this prevents other concurrent | |
190 | `git maintenance run` commands from running on the same repository. Without | |
191 | this safeguard, competing processes could leave the repository in an | |
192 | unpredictable state. | |
193 | ||
194 | The background maintenance schedule runs `git maintenance run` processes | |
195 | on an hourly basis. Each run executes the "hourly" tasks. At midnight, | |
196 | that process also executes the "daily" tasks. At midnight on the first day | |
197 | of the week, that process also executes the "weekly" tasks. A single | |
198 | process iterates over each registered repository, performing the scheduled | |
199 | tasks for that frequency. Depending on the number of registered | |
200 | repositories and their sizes, this process may take longer than an hour. | |
201 | In this case, multiple `git maintenance run` commands may run on the same | |
202 | repository at the same time, colliding on the object database lock. This | |
203 | results in one of the two tasks not running. | |
204 | ||
205 | If you find that some maintenance windows are taking longer than one hour | |
206 | to complete, then consider reducing the complexity of your maintenance | |
207 | tasks. For example, the `gc` task is much slower than the | |
208 | `incremental-repack` task. However, this comes at a cost of a slightly | |
209 | larger object database. Consider moving more expensive tasks to be run | |
210 | less frequently. | |
211 | ||
212 | Expert users may consider scheduling their own maintenance tasks using a | |
213 | different schedule than is available through `git maintenance start` and | |
214 | Git configuration options. These users should be aware of the object | |
215 | database lock and how concurrent `git maintenance run` commands behave. | |
216 | Further, the `git gc` command should not be combined with | |
217 | `git maintenance run` commands. `git gc` modifies the object database | |
218 | but does not take the lock in the same way as `git maintenance run`. If | |
219 | possible, use `git maintenance run --task=gc` instead of `git gc`. | |
220 | ||
221 | ||
2057d750 DS |
222 | GIT |
223 | --- | |
224 | Part of the linkgit:git[1] suite |