Documentation/config/extensions.adoc

extensions.*::
	Unless otherwise stated, is an error to specify an extension if
	`core.repositoryFormatVersion` is not `1`. See
	linkgit:gitrepository-layout[5].
+
compatObjectFormat:::
	Specify a compatibility hash algorithm to use.  The acceptable values
	are `sha1` and `sha256`.  The value specified must be different from the
	value of `extensions.objectFormat`.  This allows client level
	interoperability between git repositories whose objectFormat matches
	this compatObjectFormat.  In particular when fully implemented the
	pushes and pulls from a repository in whose objectFormat matches
	compatObjectFormat.  As well as being able to use oids encoded in
	compatObjectFormat in addition to oids encoded with objectFormat to
	locally specify objects.
+
Note that the functionality enabled by this extension is incomplete and subject
to change.  It currently exists only to allow development and testing of
the underlying feature and is not designed to be enabled by end users.

noop:::
	This extension does not change git's behavior at all. It is useful only
	for testing format-1 compatibility.
+
For historical reasons, this extension is respected regardless of the
`core.repositoryFormatVersion` setting.

noop-v1:::
	This extension does not change git's behavior at all. It is useful only
	for testing format-1 compatibility.

objectFormat:::
	Specify the hash algorithm to use.  The acceptable values are `sha1` and
	`sha256`.  If not specified, `sha1` is assumed.
+
Note that this setting should only be set by linkgit:git-init[1] or
linkgit:git-clone[1].  Trying to change it after initialization will not
work and will produce hard-to-diagnose issues.

partialClone:::
	When enabled, 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.
+
The value of this key is the name of the promisor remote.
+
For historical reasons, this extension is respected regardless of the
`core.repositoryFormatVersion` setting.

preciousObjects:::
	If enabled, indicates that objects in the repository MUST NOT be deleted
	(e.g., by `git-prune` or `git repack -d`).
+
For historical reasons, this extension is respected regardless of the
`core.repositoryFormatVersion` setting.

refStorage:::
	Specify the ref storage format and a corresponding payload. The value
	can be either a format name or a URI:
+
--
* A format name alone (e.g., `reftable` or `files`).

* A URI format `<format>://<payload>` explicitly specifies both the
  format and payload (e.g., `reftable:///foo/bar`).

Supported format names are:

include::../ref-storage-format.adoc[]

The payload is passed directly to the reference backend. For the files and
reftable backends, this must be a filesystem path where the references will
be stored. Defaulting to the commondir when no payload is provided. Relative
paths are resolved relative to the `$GIT_DIR`. Future backends may support
other payload schemes, e.g., postgres://127.0.0.1:5432?database=myrepo.
--
+
Note that this setting should only be set by linkgit:git-init[1] or
linkgit:git-clone[1]. Trying to change it after initialization will not
work and will produce hard-to-diagnose issues.

relativeWorktrees:::
	If enabled, indicates at least one worktree has been linked with
	relative paths. Automatically set if a worktree has been created or
	repaired with either the `--relative-paths` option or with the
	`worktree.useRelativePaths` config set to `true`.

submodulePathConfig:::
	This extension is for the minority of users who:
+
--
* Encounter errors like `refusing to create ... in another submodule's git dir`
  due to a number of reasons, like case-insensitive filesystem conflicts when
  creating modules named `foo` and `Foo`.
* Require more flexible submodule layouts, for example due to nested names like
  `foo`, `foo/bar` and `foo/baz` not supported by the default gitdir mechanism
  which uses `.git/modules/<plain-name>` locations, causing further conflicts.
--
+
When `extensions.submodulePathConfig` is enabled, the `submodule.<name>.gitdir`
config becomes the single source of truth for all submodule gitdir paths and is
automatically set for all new submodules both during clone and init operations.
+
Git will error out if a module does not have a corresponding
`submodule.<name>.gitdir` set.
+
Existing (pre-extension) submodules need to be migrated by adding the missing
config entries. This can be done manually, e.g. for each submodule:
`git config submodule.<name>.gitdir .git/modules/<name>`, or via the
`git submodule--helper migrate-gitdir-configs` command which iterates over all
submodules and attempts to migrate them.
+
The extension can be enabled automatically for new repositories by setting
`init.defaultSubmodulePathConfig` to `true`, for example by running
`git config --global init.defaultSubmodulePathConfig true`.

worktreeConfig:::
	If enabled, then worktrees will load config settings from the
	`$GIT_DIR/config.worktree` file in addition to the
	`$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and
	`$GIT_DIR` are the same for the main working tree, while other
	working trees have `$GIT_DIR` equal to
	`$GIT_COMMON_DIR/worktrees/<id>/`. The settings in the
	`config.worktree` file will override settings from any other
	config files.
+
When enabling this extension, you must be careful to move
certain values from the common config file to the main working tree's
`config.worktree` file, if present:
+
--
* `core.worktree` must be moved from `$GIT_COMMON_DIR/config` to
  `$GIT_COMMON_DIR/config.worktree`.
* If `core.bare` is true, then it must be moved from `$GIT_COMMON_DIR/config`
  to `$GIT_COMMON_DIR/config.worktree`.
--
+
It may also be beneficial to adjust the locations of `core.sparseCheckout`
and `core.sparseCheckoutCone` depending on your desire for customizable
sparse-checkout settings for each worktree. By default, the `git
sparse-checkout` builtin enables this extension, assigns
these config values on a per-worktree basis, and uses the
`$GIT_DIR/info/sparse-checkout` file to specify the sparsity for each
worktree independently. See linkgit:git-sparse-checkout[1] for more
details.
+
For historical reasons, this extension is respected regardless of the
`core.repositoryFormatVersion` setting.