6 git-maintenance - Run tasks to optimize Git repository data
12 'git maintenance' run [<options>]
17 Run tasks to optimize Git repository data, speeding up other Git commands
18 and reducing storage requirements for the repository.
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
26 The `git maintenance` command provides flexibility for how to optimize the
33 Run one or more maintenance tasks. If one or more `--task` options
34 are specified, then those tasks are run in that order. Otherwise,
35 the tasks are determined by which `maintenance.<task>.enabled`
36 config options are true. By default, only `maintenance.gc.enabled`
43 The `commit-graph` job updates the `commit-graph` files incrementally,
44 then verifies that the written data is correct. The incremental
45 write is safe to run alongside concurrent Git processes since it
46 will not expire `.graph` files that were in the previous
47 `commit-graph-chain` file. They will be deleted by a later run based
48 on the expiration delay.
51 The `prefetch` task updates the object directory with the latest
52 objects from all registered remotes. For each remote, a `git fetch`
53 command is run. The refmap is custom to avoid updating local or remote
54 branches (those in `refs/heads` or `refs/remotes`). Instead, the
55 remote refs are stored in `refs/prefetch/<remote>/`. Also, tags are
58 This is done to avoid disrupting the remote-tracking branches. The end users
59 expect these refs to stay unmoved unless they initiate a fetch. With prefetch
60 task, however, the objects necessary to complete a later real fetch would
61 already be obtained, so the real fetch would go faster. In the ideal case,
62 it will just become an update to bunch of remote-tracking branches without
66 Clean up unnecessary files and optimize the local repository. "GC"
67 stands for "garbage collection," but this task performs many
68 smaller tasks. This task can be expensive for large repositories,
69 as it repacks all Git objects into a single pack-file. It can also
70 be disruptive in some situations, as it deletes stale data. See
71 linkgit:git-gc[1] for more details on garbage collection in Git.
74 The `loose-objects` job cleans up loose objects and places them into
75 pack-files. In order to prevent race conditions with concurrent Git
76 commands, it follows a two-step process. First, it deletes any loose
77 objects that already exist in a pack-file; concurrent Git processes
78 will examine the pack-file for the object data instead of the loose
79 object. Second, it creates a new pack-file (starting with "loose-")
80 containing a batch of loose objects. The batch size is limited to 50
81 thousand objects to prevent the job from taking too long on a
82 repository with many loose objects. The `gc` task writes unreachable
83 objects as loose objects to be cleaned up by a later step only if
84 they are not re-added to a pack-file; for this reason it is not
85 advisable to enable both the `loose-objects` and `gc` tasks at the
89 The `incremental-repack` job repacks the object directory
90 using the `multi-pack-index` feature. In order to prevent race
91 conditions with concurrent Git commands, it follows a two-step
92 process. First, it calls `git multi-pack-index expire` to delete
93 pack-files unreferenced by the `multi-pack-index` file. Second, it
94 calls `git multi-pack-index repack` to select several small
95 pack-files and repack them into a bigger one, and then update the
96 `multi-pack-index` entries that refer to the small pack-files to
97 refer to the new pack-file. This prepares those small pack-files
98 for deletion upon the next run of `git multi-pack-index expire`.
99 The selection of the small pack-files is such that the expected
100 size of the big pack-file is at least the batch size; see the
101 `--batch-size` option for the `repack` subcommand in
102 linkgit:git-multi-pack-index[1]. The default batch-size is zero,
103 which is a special case that attempts to repack all pack-files
104 into a single pack-file.
109 When combined with the `run` subcommand, run maintenance tasks
110 only if certain thresholds are met. For example, the `gc` task
111 runs when the number of loose objects exceeds the number stored
112 in the `gc.auto` config setting, or when the number of pack-files
113 exceeds the `gc.autoPackLimit` config setting.
116 Do not report progress or other information over `stderr`.
119 If this option is specified one or more times, then only run the
120 specified tasks in the specified order. If no `--task=<task>`
121 arguments are specified, then only the tasks with
122 `maintenance.<task>.enabled` configured as `true` are considered.
123 See the 'TASKS' section for the list of accepted `<task>` values.
127 Part of the linkgit:git[1] suite