path: root/Documentation
diff options
authorJunio C Hamano <>2020-11-18 21:32:53 (GMT)
committerJunio C Hamano <>2020-11-18 21:32:53 (GMT)
commit7660da161821ab79b8ecd5019c28843ed7e770a6 (patch)
treed0993b4af829e0275d6ff7cd0f87b17f69819b7c /Documentation
parentc042c455d4ffb9b5ed0c280301b5661f3efad572 (diff)
parent0016b618182f642771dc589cf0090289f9fe1b4f (diff)
Merge branch 'ds/maintenance-part-3'
Parts of "git maintenance" to ease writing crontab entries (and other scheduling system configuration) for it. * ds/maintenance-part-3: maintenance: add troubleshooting guide to docs maintenance: use 'incremental' strategy by default maintenance: create maintenance.strategy config maintenance: add start/stop subcommands maintenance: add [un]register subcommands for-each-repo: run subcommands on configured repos maintenance: add --schedule option and config maintenance: optionally skip --auto process
Diffstat (limited to 'Documentation')
3 files changed, 182 insertions, 1 deletions
diff --git a/Documentation/config/maintenance.txt b/Documentation/config/maintenance.txt
index a0706d8..a5ead09 100644
--- a/Documentation/config/maintenance.txt
+++ b/Documentation/config/maintenance.txt
@@ -1,3 +1,23 @@
+ This boolean config option controls whether some commands run
+ `git maintenance run --auto` after doing their normal work. Defaults
+ to true.
+ 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 `git maintenance run --schedule=X`
+ commands, provided no `--task=<task>` arguments are provided.
+ Further, if a `maintenance.<task>.schedule` config value is set,
+ then that value is used instead of the one provided by
+ `maintenance.strategy`. The possible strategy strings are:
+* `none`: This default setting implies no task are run at any schedule.
+* `incremental`: This setting optimizes for performing small maintenance
+ activities that do not delete any data. This does not schedule the `gc`
+ task, but runs the `prefetch` and `commit-graph` tasks hourly and the
+ `loose-objects` and `incremental-repack` tasks daily.
This boolean config option controls whether the maintenance task
with name `<task>` is run when no `--task` option is specified to
@@ -5,6 +25,11 @@ maintenance.<task>.enabled::
`--task` option exists. By default, only `maintenance.gc.enabled`
is true.
+ This config option controls whether or not the given `<task>` runs
+ during a `git maintenance run --schedule=<frequency>` command. The
+ value must be one of "hourly", "daily", or "weekly".
This integer config option controls how often the `commit-graph` task
should be run as part of `git maintenance run --auto`. If zero, then
diff --git a/Documentation/git-for-each-repo.txt b/Documentation/git-for-each-repo.txt
new file mode 100644
index 0000000..94bd19d
--- /dev/null
+++ b/Documentation/git-for-each-repo.txt
@@ -0,0 +1,59 @@
+git-for-each-repo - Run a Git command on a list of repositories
+'git for-each-repo' --config=<config> [--] <arguments>
+Run a Git command on a list of repositories. The arguments after the
+known options or `--` indicator are used as the arguments for the Git
+For example, we could run maintenance on each of a list of repositories
+stored in a `maintenance.repo` config variable using
+git for-each-repo --config=maintenance.repo maintenance run
+This will run `git -C <repo> maintenance run` for each value `<repo>`
+in the multi-valued config variable `maintenance.repo`.
+ Use the given config variable as a multi-valued list storing
+ absolute path names. Iterate on that list of paths to run
+ the given arguments.
+These config values are loaded from system, global, and local Git config,
+as available. If `git for-each-repo` is run in a directory that is not a
+Git repository, then only the system and global config is used.
+If any `git -C <repo> <arguments>` subprocess returns a non-zero exit code,
+then the `git for-each-repo` process returns that exit code without running
+more subprocesses.
+Each `git -C <repo> <arguments>` subprocess inherits the standard file
+descriptors `stdin`, `stdout`, and `stderr`.
+Part of the linkgit:git[1] suite
diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt
index 3f5d894..6fec1eb 100644
--- a/Documentation/git-maintenance.txt
+++ b/Documentation/git-maintenance.txt
@@ -29,6 +29,32 @@ Git repository.
+ Initialize Git config values so any scheduled maintenance will
+ start running on this repository. This adds the repository to the
+ `maintenance.repo` config variable in the current user's global
+ config and enables some recommended configuration values for
+ `maintenance.<task>.schedule`. The tasks that are enabled are safe
+ for running in the background without disrupting foreground
+ processes.
+The `register` subcomand will also set the `maintenance.strategy` config
+value to `incremental`, if this value is not previously set. The
+`incremental` strategy uses the following schedule for each maintenance
+* `gc`: disabled.
+* `commit-graph`: hourly.
+* `prefetch`: hourly.
+* `loose-objects`: daily.
+* `incremental-repack`: daily.
+`git maintenance register` will also disable foreground maintenance by
+setting ` = false` in the current repository. This config
+setting will remain after a `git maintenance unregister` command.
Run one or more maintenance tasks. If one or more `--task` options
are specified, then those tasks are run in that order. Otherwise,
@@ -36,6 +62,22 @@ run::
config options are true. By default, only `maintenance.gc.enabled`
is true.
+ Start running maintenance on the current repository. This performs
+ the same config updates as the `register` subcommand, then updates
+ the background scheduler to run `git maintenance run --scheduled`
+ on an hourly basis.
+ 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.
+ 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.
@@ -110,7 +152,18 @@ OPTIONS
only if certain thresholds are met. For example, the `gc` task
runs when the number of loose objects exceeds the number stored
in the `` config setting, or when the number of pack-files
- exceeds the `gc.autoPackLimit` config setting.
+ exceeds the `gc.autoPackLimit` config setting. Not compatible with
+ the `--schedule` option.
+ When combined with the `run` subcommand, run maintenance tasks
+ only if certain time conditions are met, as specified by the
+ `maintenance.<task>.schedule` config value for each `<task>`.
+ This config value specifies a number of seconds since the last
+ time that task ran, according to the `maintenance.<task>.lastRun`
+ config value. The tasks that are tested are those provided by
+ the `--task=<task>` option(s) or those with
+ `maintenance.<task>.enabled` set to true.
Do not report progress or other information over `stderr`.
@@ -122,6 +175,50 @@ OPTIONS
`maintenance.<task>.enabled` configured as `true` are considered.
See the 'TASKS' section for the list of accepted `<task>` values.
+The `git maintenance` 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.
+Users may find some cases where scheduled maintenance tasks do not run as
+frequently as intended. Each `git maintenance run` command takes a lock on
+the repository's object database, and this prevents other concurrent
+`git maintenance run` commands from running on the same repository. Without
+this safeguard, competing processes could leave the repository in an
+unpredictable state.
+The background maintenance schedule runs `git maintenance run` 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. Depending on the number of registered
+repositories and their sizes, this process may take longer than an hour.
+In this case, multiple `git maintenance run` 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.
+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 `gc` task is much slower than the
+`incremental-repack` task. However, this comes at a cost of a slightly
+larger object database. Consider moving more expensive tasks to be run
+less frequently.
+Expert users may consider scheduling their own maintenance tasks using a
+different schedule than is available through `git maintenance start` and
+Git configuration options. These users should be aware of the object
+database lock and how concurrent `git maintenance run` commands behave.
+Further, the `git gc` command should not be combined with
+`git maintenance run` commands. `git gc` modifies the object database
+but does not take the lock in the same way as `git maintenance run`. If
+possible, use `git maintenance run --task=gc` instead of `git gc`.
Part of the linkgit:git[1] suite