| 1 | extensions.*:: |
| 2 | Unless otherwise stated, is an error to specify an extension if |
| 3 | `core.repositoryFormatVersion` is not `1`. See |
| 4 | linkgit:gitrepository-layout[5]. |
| 5 | + |
| 6 | compatObjectFormat::: |
| 7 | Specify a compatibility hash algorithm to use. The acceptable values |
| 8 | are `sha1` and `sha256`. The value specified must be different from the |
| 9 | value of `extensions.objectFormat`. This allows client level |
| 10 | interoperability between git repositories whose objectFormat matches |
| 11 | this compatObjectFormat. In particular when fully implemented the |
| 12 | pushes and pulls from a repository in whose objectFormat matches |
| 13 | compatObjectFormat. As well as being able to use oids encoded in |
| 14 | compatObjectFormat in addition to oids encoded with objectFormat to |
| 15 | locally specify objects. |
| 16 | + |
| 17 | Note that the functionality enabled by this extension is incomplete and subject |
| 18 | to change. It currently exists only to allow development and testing of |
| 19 | the underlying feature and is not designed to be enabled by end users. |
| 20 | |
| 21 | noop::: |
| 22 | This extension does not change git's behavior at all. It is useful only |
| 23 | for testing format-1 compatibility. |
| 24 | + |
| 25 | For historical reasons, this extension is respected regardless of the |
| 26 | `core.repositoryFormatVersion` setting. |
| 27 | |
| 28 | noop-v1::: |
| 29 | This extension does not change git's behavior at all. It is useful only |
| 30 | for testing format-1 compatibility. |
| 31 | |
| 32 | objectFormat::: |
| 33 | Specify the hash algorithm to use. The acceptable values are `sha1` and |
| 34 | `sha256`. If not specified, `sha1` is assumed. |
| 35 | + |
| 36 | Note that this setting should only be set by linkgit:git-init[1] or |
| 37 | linkgit:git-clone[1]. Trying to change it after initialization will not |
| 38 | work and will produce hard-to-diagnose issues. |
| 39 | |
| 40 | partialClone::: |
| 41 | When enabled, indicates that the repo was created with a partial clone |
| 42 | (or later performed a partial fetch) and that the remote may have |
| 43 | omitted sending certain unwanted objects. Such a remote is called a |
| 44 | "promisor remote" and it promises that all such omitted objects can |
| 45 | be fetched from it in the future. |
| 46 | + |
| 47 | The value of this key is the name of the promisor remote. |
| 48 | + |
| 49 | For historical reasons, this extension is respected regardless of the |
| 50 | `core.repositoryFormatVersion` setting. |
| 51 | |
| 52 | preciousObjects::: |
| 53 | If enabled, indicates that objects in the repository MUST NOT be deleted |
| 54 | (e.g., by `git-prune` or `git repack -d`). |
| 55 | + |
| 56 | For historical reasons, this extension is respected regardless of the |
| 57 | `core.repositoryFormatVersion` setting. |
| 58 | |
| 59 | refStorage::: |
| 60 | Specify the ref storage format and a corresponding payload. The value |
| 61 | can be either a format name or a URI: |
| 62 | + |
| 63 | -- |
| 64 | * A format name alone (e.g., `reftable` or `files`). |
| 65 | |
| 66 | * A URI format `<format>://<payload>` explicitly specifies both the |
| 67 | format and payload (e.g., `reftable:///foo/bar`). |
| 68 | |
| 69 | Supported format names are: |
| 70 | |
| 71 | include::../ref-storage-format.adoc[] |
| 72 | |
| 73 | The payload is passed directly to the reference backend. For the files and |
| 74 | reftable backends, this must be a filesystem path where the references will |
| 75 | be stored. Defaulting to the commondir when no payload is provided. Relative |
| 76 | paths are resolved relative to the `$GIT_DIR`. Future backends may support |
| 77 | other payload schemes, e.g., postgres://127.0.0.1:5432?database=myrepo. |
| 78 | -- |
| 79 | + |
| 80 | Note that this setting should only be set by linkgit:git-init[1] or |
| 81 | linkgit:git-clone[1]. Trying to change it after initialization will not |
| 82 | work and will produce hard-to-diagnose issues. |
| 83 | |
| 84 | relativeWorktrees::: |
| 85 | If enabled, indicates at least one worktree has been linked with |
| 86 | relative paths. Automatically set if a worktree has been created or |
| 87 | repaired with either the `--relative-paths` option or with the |
| 88 | `worktree.useRelativePaths` config set to `true`. |
| 89 | |
| 90 | submodulePathConfig::: |
| 91 | This extension is for the minority of users who: |
| 92 | + |
| 93 | -- |
| 94 | * Encounter errors like `refusing to create ... in another submodule's git dir` |
| 95 | due to a number of reasons, like case-insensitive filesystem conflicts when |
| 96 | creating modules named `foo` and `Foo`. |
| 97 | * Require more flexible submodule layouts, for example due to nested names like |
| 98 | `foo`, `foo/bar` and `foo/baz` not supported by the default gitdir mechanism |
| 99 | which uses `.git/modules/<plain-name>` locations, causing further conflicts. |
| 100 | -- |
| 101 | + |
| 102 | When `extensions.submodulePathConfig` is enabled, the `submodule.<name>.gitdir` |
| 103 | config becomes the single source of truth for all submodule gitdir paths and is |
| 104 | automatically set for all new submodules both during clone and init operations. |
| 105 | + |
| 106 | Git will error out if a module does not have a corresponding |
| 107 | `submodule.<name>.gitdir` set. |
| 108 | + |
| 109 | Existing (pre-extension) submodules need to be migrated by adding the missing |
| 110 | config entries. This can be done manually, e.g. for each submodule: |
| 111 | `git config submodule.<name>.gitdir .git/modules/<name>`, or via the |
| 112 | `git submodule--helper migrate-gitdir-configs` command which iterates over all |
| 113 | submodules and attempts to migrate them. |
| 114 | + |
| 115 | The extension can be enabled automatically for new repositories by setting |
| 116 | `init.defaultSubmodulePathConfig` to `true`, for example by running |
| 117 | `git config --global init.defaultSubmodulePathConfig true`. |
| 118 | |
| 119 | worktreeConfig::: |
| 120 | If enabled, then worktrees will load config settings from the |
| 121 | `$GIT_DIR/config.worktree` file in addition to the |
| 122 | `$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and |
| 123 | `$GIT_DIR` are the same for the main working tree, while other |
| 124 | working trees have `$GIT_DIR` equal to |
| 125 | `$GIT_COMMON_DIR/worktrees/<id>/`. The settings in the |
| 126 | `config.worktree` file will override settings from any other |
| 127 | config files. |
| 128 | + |
| 129 | When enabling this extension, you must be careful to move |
| 130 | certain values from the common config file to the main working tree's |
| 131 | `config.worktree` file, if present: |
| 132 | + |
| 133 | -- |
| 134 | * `core.worktree` must be moved from `$GIT_COMMON_DIR/config` to |
| 135 | `$GIT_COMMON_DIR/config.worktree`. |
| 136 | * If `core.bare` is true, then it must be moved from `$GIT_COMMON_DIR/config` |
| 137 | to `$GIT_COMMON_DIR/config.worktree`. |
| 138 | -- |
| 139 | + |
| 140 | It may also be beneficial to adjust the locations of `core.sparseCheckout` |
| 141 | and `core.sparseCheckoutCone` depending on your desire for customizable |
| 142 | sparse-checkout settings for each worktree. By default, the `git |
| 143 | sparse-checkout` builtin enables this extension, assigns |
| 144 | these config values on a per-worktree basis, and uses the |
| 145 | `$GIT_DIR/info/sparse-checkout` file to specify the sparsity for each |
| 146 | worktree independently. See linkgit:git-sparse-checkout[1] for more |
| 147 | details. |
| 148 | + |
| 149 | For historical reasons, this extension is respected regardless of the |
| 150 | `core.repositoryFormatVersion` setting. |