Autogenerated HTML docs for v2.20.0-rc0

1 files changed, 113 insertions, 1 deletions

diff --git a/gitrepository-layout.html b/gitrepository-layout.html
index 8da611a59..4d3171856 100644
--- a/gitrepository-layout.html
+++ b/gitrepository-layout.html
@@ -1237,6 +1237,118 @@ worktrees/<id>/config.worktree
 </div>

 </div>

 <div class="sect1">

+<h2 id="_git_repository_format_versions">Git Repository Format Versions</h2>

+<div class="sectionbody">

+<div class="paragraph"><p>Every git repository is marked with a numeric version in the

+<code>core.repositoryformatversion</code> key of its <code>config</code> file. This version

+specifies the rules for operating on the on-disk repository data. An

+implementation of git which does not understand a particular version

+advertised by an on-disk repository MUST NOT operate on that repository;

+doing so risks not only producing wrong results, but actually losing

+data.</p></div>

+<div class="paragraph"><p>Because of this rule, version bumps should be kept to an absolute

+minimum. Instead, we generally prefer these strategies:</p></div>

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

+<li>

+<p>

+bumping format version numbers of individual data files (e.g.,

+    index, packfiles, etc). This restricts the incompatibilities only to

+    those files.

+</p>

+</li>

+<li>

+<p>

+introducing new data that gracefully degrades when used by older

+    clients (e.g., pack bitmap files are ignored by older clients, which

+    simply do not take advantage of the optimization they provide).

+</p>

+</li>

+</ul></div>

+<div class="paragraph"><p>A whole-repository format version bump should only be part of a change

+that cannot be independently versioned. For instance, if one were to

+change the reachability rules for objects, or the rules for locking

+refs, that would require a bump of the repository format version.</p></div>

+<div class="paragraph"><p>Note that this applies only to accessing the repository&#8217;s disk contents

+directly. An older client which understands only format <code>0</code> may still

+connect via <code>git://</code> to a repository using format <code>1</code>, as long as the

+server process understands format <code>1</code>.</p></div>

+<div class="paragraph"><p>The preferred strategy for rolling out a version bump (whether whole

+repository or for a single file) is to teach git to read the new format,

+and allow writing the new format with a config switch or command line

+option (for experimentation or for those who do not care about backwards

+compatibility with older gits). Then after a long period to allow the

+reading capability to become common, we may switch to writing the new

+format by default.</p></div>

+<div class="paragraph"><p>The currently defined format versions are:</p></div>

+<div class="sect2">

+<h3 id="_version_code_0_code">Version <code>0</code></h3>

+<div class="paragraph"><p>This is the format defined by the initial version of git, including but

+not limited to the format of the repository directory, the repository

+configuration file, and the object and ref storage. Specifying the

+complete behavior of git is beyond the scope of this document.</p></div>

+</div>

+<div class="sect2">

+<h3 id="_version_code_1_code">Version <code>1</code></h3>

+<div class="paragraph"><p>This format is identical to version <code>0</code>, with the following exceptions:</p></div>

+<div class="olist arabic"><ol class="arabic">

+<li>

+<p>

+When reading the <code>core.repositoryformatversion</code> variable, a git

+     implementation which supports version 1 MUST also read any

+     configuration keys found in the <code>extensions</code> section of the

+     configuration file.

+</p>

+</li>

+<li>

+<p>

+If a version-1 repository specifies any <code>extensions.*</code> keys that

+     the running git has not implemented, the operation MUST NOT

+     proceed. Similarly, if the value of any known key is not understood

+     by the implementation, the operation MUST NOT proceed.

+</p>

+</li>

+</ol></div>

+<div class="paragraph"><p>Note that if no extensions are specified in the config file, then

+<code>core.repositoryformatversion</code> SHOULD be set to <code>0</code> (setting it to <code>1</code>

+provides no benefit, and makes the repository incompatible with older

+implementations of git).</p></div>

+<div class="paragraph"><p>This document will serve as the master list for extensions. Any

+implementation wishing to define a new extension should make a note of

+it here, in order to claim the name.</p></div>

+<div class="paragraph"><p>The defined extensions are:</p></div>

+<div class="sect3">

+<h4 id="_code_noop_code"><code>noop</code></h4>

+<div class="paragraph"><p>This extension does not change git&#8217;s behavior at all. It is useful only

+for testing format-1 compatibility.</p></div>

+</div>

+<div class="sect3">

+<h4 id="_code_preciousobjects_code"><code>preciousObjects</code></h4>

+<div class="paragraph"><p>When the config key <code>extensions.preciousObjects</code> is set to <code>true</code>,

+objects in the repository MUST NOT be deleted (e.g., by <code>git-prune</code> or

+<code>git repack -d</code>).</p></div>

+</div>

+<div class="sect3">

+<h4 id="_code_partialclone_code"><code>partialclone</code></h4>

+<div class="paragraph"><p>When the config key <code>extensions.partialclone</code> is set, it indicates

+that the repo was created with a partial clone (or later performed

+a partial fetch) and that the remote may have omitted sending

+certain unwanted objects.  Such a remote is called a "promisor remote"

+and it promises that all such omitted objects can be fetched from it

+in the future.</p></div>

+<div class="paragraph"><p>The value of this key is the name of the promisor remote.</p></div>

+</div>

+<div class="sect3">

+<h4 id="_code_worktreeconfig_code"><code>worktreeConfig</code></h4>

+<div class="paragraph"><p>If set, by default "git config" reads from both "config" and

+"config.worktree" file from GIT_DIR in that order. In

+multiple working directory mode, "config" file is shared while

+"config.worktree" is per-working directory (i.e., it&#8217;s in

+GIT_COMMON_DIR/worktrees/&lt;id&gt;/config.worktree)</p></div>

+</div>

+</div>

+</div>

+</div>

+<div class="sect1">

 <h2 id="_see_also">SEE ALSO</h2>

 <div class="sectionbody">

 <div class="paragraph"><p><a href="git-init.html">git-init(1)</a>,

@@ -1260,7 +1372,7 @@ worktrees/&lt;id&gt;/config.worktree
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2018-11-13 23:05:48 JST

+ 2018-11-18 21:41:21 JST

 </div>

 </div>

 </body>