Autogenerated HTML docs for v2.29.2-334-gfaefd

1 files changed, 140 insertions, 2 deletions

diff --git a/git-maintenance.html b/git-maintenance.html
index 6e9204cea..8ce958c50 100644
--- a/git-maintenance.html
+++ b/git-maintenance.html
@@ -773,6 +773,57 @@ Git repository.</p></div>
 <div class="sectionbody">

 <div class="dlist"><dl>

 <dt class="hdlist1">

+register

+</dt>

+<dd>

+<p>

+        Initialize Git config values so any scheduled maintenance will

+        start running on this repository. This adds the repository to the

+        <code>maintenance.repo</code> config variable in the current user&#8217;s global

+        config and enables some recommended configuration values for

+        <code>maintenance.&lt;task&gt;.schedule</code>. The tasks that are enabled are safe

+        for running in the background without disrupting foreground

+        processes.

+</p>

+<div class="paragraph"><p>The <code>register</code> subcomand will also set the <code>maintenance.strategy</code> config

+value to <code>incremental</code>, if this value is not previously set. The

+<code>incremental</code> strategy uses the following schedule for each maintenance

+task:</p></div>

+<div class="openblock">

+<div class="content">

+<div class="ulist"><ul>

+<li>

+<p>

+<code>gc</code>: disabled.

+</p>

+</li>

+<li>

+<p>

+<code>commit-graph</code>: hourly.

+</p>

+</li>

+<li>

+<p>

+<code>prefetch</code>: hourly.

+</p>

+</li>

+<li>

+<p>

+<code>loose-objects</code>: daily.

+</p>

+</li>

+<li>

+<p>

+<code>incremental-repack</code>: daily.

+</p>

+</li>

+</ul></div>

+</div></div>

+<div class="paragraph"><p><code>git maintenance register</code> will also disable foreground maintenance by

+setting <code>maintenance.auto = false</code> in the current repository. This config

+setting will remain after a <code>git maintenance unregister</code> command.</p></div>

+</dd>

+<dt class="hdlist1">

 run

 </dt>

 <dd>

@@ -784,6 +835,37 @@ run
         is true.

 </p>

 </dd>

+<dt class="hdlist1">

+start

+</dt>

+<dd>

+<p>

+        Start running maintenance on the current repository. This performs

+        the same config updates as the <code>register</code> subcommand, then updates

+        the background scheduler to run <code>git maintenance run --scheduled</code>

+        on an hourly basis.

+</p>

+</dd>

+<dt class="hdlist1">

+stop

+</dt>

+<dd>

+<p>

+        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.

+</p>

+</dd>

+<dt class="hdlist1">

+unregister

+</dt>

+<dd>

+<p>

+        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.

+</p>

+</dd>

 </dl></div>

 </div>

 </div>

@@ -895,7 +977,23 @@ incremental-repack
         only if certain thresholds are met. For example, the <code>gc</code> task

         runs when the number of loose objects exceeds the number stored

         in the <code>gc.auto</code> config setting, or when the number of pack-files

-        exceeds the <code>gc.autoPackLimit</code> config setting.

+        exceeds the <code>gc.autoPackLimit</code> config setting. Not compatible with

+        the <code>--schedule</code> option.

+</p>

+</dd>

+<dt class="hdlist1">

+--schedule

+</dt>

+<dd>

+<p>

+        When combined with the <code>run</code> subcommand, run maintenance tasks

+        only if certain time conditions are met, as specified by the

+        <code>maintenance.&lt;task&gt;.schedule</code> config value for each <code>&lt;task&gt;</code>.

+        This config value specifies a number of seconds since the last

+        time that task ran, according to the <code>maintenance.&lt;task&gt;.lastRun</code>

+        config value. The tasks that are tested are those provided by

+        the <code>--task=&lt;task&gt;</code> option(s) or those with

+        <code>maintenance.&lt;task&gt;.enabled</code> set to true.

 </p>

 </dd>

 <dt class="hdlist1">

@@ -922,6 +1020,46 @@ incremental-repack
 </div>

 </div>

 <div class="sect1">

+<h2 id="_troubleshooting">TROUBLESHOOTING</h2>

+<div class="sectionbody">

+<div class="paragraph"><p>The <code>git maintenance</code> 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.</p></div>

+<div class="paragraph"><p>Users may find some cases where scheduled maintenance tasks do not run as

+frequently as intended. Each <code>git maintenance run</code> command takes a lock on

+the repository&#8217;s object database, and this prevents other concurrent

+<code>git maintenance run</code> commands from running on the same repository. Without

+this safeguard, competing processes could leave the repository in an

+unpredictable state.</p></div>

+<div class="paragraph"><p>The background maintenance schedule runs <code>git maintenance run</code> 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 <code>git maintenance run</code> 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.</p></div>

+<div class="paragraph"><p>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 <code>gc</code> task is much slower than the

+<code>incremental-repack</code> task. However, this comes at a cost of a slightly

+larger object database. Consider moving more expensive tasks to be run

+less frequently.</p></div>

+<div class="paragraph"><p>Expert users may consider scheduling their own maintenance tasks using a

+different schedule than is available through <code>git maintenance start</code> and

+Git configuration options. These users should be aware of the object

+database lock and how concurrent <code>git maintenance run</code> commands behave.

+Further, the <code>git gc</code> command should not be combined with

+<code>git maintenance run</code> commands. <code>git gc</code> modifies the object database

+but does not take the lock in the same way as <code>git maintenance run</code>. If

+possible, use <code>git maintenance run --task=gc</code> instead of <code>git gc</code>.</p></div>

+</div>

+</div>

+<div class="sect1">

 <h2 id="_git">GIT</h2>

 <div class="sectionbody">

 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>

@@ -932,7 +1070,7 @@ incremental-repack
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2020-10-27 15:58:27 PDT

+ 2020-11-18 14:12:24 PST

 </div>

 </div>

 </body>