scalar: document config settings
Add user-facing documentation that justifies the values being set by 'scalar clone', 'scalar register', and 'scalar reconfigure'. Helped-by: Junio C Hamano <gitster@pobox.com> Helped-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Derrick Stolee <stolee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Derrick Stolee committed
Dec 12, 2025 at 15:15 UTC
4ce170c522cd91e73e7d500667a4718af125bcf3
2 files changed
+168
Documentation/scalar.adoc
+164
@@ -197,6 +197,170 @@ delete <enlistment>::
197
This subcommand lets you delete an existing Scalar enlistment from your
198
local file system, unregistering the repository.
199
200
+RECOMMENDED CONFIG VALUES
201
+-------------------------
202
+
203
+As part of both `scalar clone` and `scalar register`, certain Git config
204
+values are set to optimize for large repositories or cross-platform support.
205
+These options are updated in new Git versions according to the best known
206
+advice for large repositories, and users can get the latest recommendations
207
+by running `scalar reconfigure [--all]`.
208
+
209
+This section lists justifications for the config values that are set in the
210
+latest version.
211
+
212
+am.keepCR=true::
213
+ This setting is important for cross-platform development across Windows
214
+ and non-Windows platforms and keeping carriage return (`\r`) characters
215
+ in certain workflows.
216
+
217
+commitGraph.changedPaths=true::
218
+ This setting helps the background maintenance steps that compute the
219
+ serialized commit-graph to also store changed-path Bloom filters. This
220
+ accelerates file history commands and allows users to automatically
221
+ benefit without running a foreground command.
222
+
223
+commitGraph.generationVersion=1::
224
+ While the preferred version is 2 for performance reasons, existing users
225
+ that had version 1 by default will need special care in upgrading to
226
+ version 2. This is likely to change in the future as the upgrade story
227
+ solidifies.
228
+
229
+core.autoCRLF=false::
230
+ This removes the transformation of worktree files to add CRLF line
231
+ endings when only LF line endings exist. This is removed for performance
232
+ reasons. Repositories that use tools that care about CRLF line endings
233
+ should commit the necessary files with those line endings instead.
234
+
235
+core.logAllRefUpdates=true::
236
+ This enables the reflog on all branches. While this is a performance
237
+ cost for large repositories, it is frequently an important data source
238
+ for users to get out of bad situations or to seek support from experts.
239
+
240
+core.safeCRLF=false::
241
+ Similar to `core.autoCRLF=false`, this disables checks around whether
242
+ the CRLF conversion is reversible. This is a performance improvement,
243
+ but can be dangerous if `core.autoCRLF` is reenabled by the user.
244
+
245
+credential.https://dev.azure.com.useHttpPath=true::
246
+ This setting enables the `credential.useHttpPath` feature only for web
247
+ URLs for Azure DevOps. This is important for users interacting with that
248
+ service using multiple organizations and thus multiple credential
249
+ tokens.
250
+
251
+feature.experimental=false::
252
+ This disables the "experimental" optimizations grouped under this
253
+ feature config. The expectation is that all valuable optimizations are
254
+ also set explicitly by Scalar config, and any differences are
255
+ intentional. Notable differences include several bitmap-related config
256
+ options which are disabled for client-focused Scalar repos.
257
+
258
+feature.manyFiles=false::
259
+ This disables the "many files" optimizations grouped under this feature
260
+ config. The expectation is that all valuable optimizations are also set
261
+ explicitly by Scalar config, and any differences are intentional.
262
+
263
+fetch.showForcedUpdates=false::
264
+ This disables the check at the end of `git fetch` that notifies the user
265
+ if the ref update was a forced update (one where the previous position
266
+ is not reachable from the latest position). This check can be very
267
+ expensive in large repositories, so is disabled and replaced with an
268
+ advice message. Set `advice.fetchShowForcedUpdates=false` to disable
269
+ this advice message.
270
+
271
+fetch.unpackLimit=1::
272
+ This setting prevents Git from unpacking packfiles into loose objects
273
+ as they are downloaded from the server. The default limit of 100 was
274
+ intended as a way to prevent performance issues from too many packfiles,
275
+ but Scalar uses background maintenance to group packfiles and cover them
276
+ with a multi-pack-index, removing this issue.
277
+
278
+fetch.writeCommitGraph=false::
279
+ This config setting was created to help users automatically update their
280
+ commit-graph files as they perform fetches. However, this takes time
281
+ from foreground fetches and pulls and Scalar uses background maintenance
282
+ for this function instead.
283
+
284
+gc.auto=0::
285
+ This disables automatic garbage collection, since Scalar uses background
286
+ maintenance to keep the repository data in good shape.
287
+
288
+gui.GCWarning=false::
289
+ Since Scalar disables garbage collection by setting `gc.auto=0`, the
290
+ `git-gui` tool may start to warn about this setting. Disable this
291
+ warning as Scalar's background maintenance configuration makes the
292
+ warning irrelevant.
293
+
294
+index.skipHash=true::
295
+ Disable computing the hash of the index contents as it is being written.
296
+ This assists with performance, especially for large index files.
297
+
298
+index.threads=true::
299
+ This tells Git to automatically detect how many threads it should use
300
+ when reading the index due to the default value of `core.preloadIndex`,
301
+ which enables parallel index reads. This explicit setting also enables
302
+ `index.recordOffsetTable=true` to speed up parallel index reads.
303
+
304
+index.version=4::
305
+ This index version adds compression to the path names, reducing the size
306
+ of the index in a significant way for large repos. This is an important
307
+ performance boost.
308
+
309
+log.excludeDecoration=refs/prefetch/*::
310
+ Since Scalar enables background maintenance with the `incremental`
311
+ strategy, this setting avoids polluting `git log` output with refs
312
+ stored by the background prefetch operations.
313
+
314
+merge.renames=true::
315
+ When computing merges in large repos, it is particularly important to
316
+ detect renames to maximize the potential for a result that will validate
317
+ correctly. Users performing merges locally are more likely to be doing
318
+ so because a server-side merge (via pull request or similar) resulted in
319
+ conflicts. While this is the default setting, it is set specifically to
320
+ override a potential change to `diff.renames` which a user may set for
321
+ performance reasons.
322
+
323
+merge.stat=false::
324
+ This disables a diff output after computing a merge. This improves
325
+ performance of `git merge` for large repos while reducing noisy output.
326
+
327
+pack.useBitmaps=false::
328
+ This disables the use of `.bitmap` files attached to packfiles. Bitmap
329
+ files are optimized for server-side use, not client-side use. Scalar
330
+ disables this to avoid some performance issues that can occur if a user
331
+ accidentally creates `.bitmap` files.
332
+
333
+pack.usePathWalk=true::
334
+ This enables the `--path-walk` option to `git pack-objects` by default.
335
+ This can accelerate the computation and compression of packfiles created
336
+ by `git push` and other repack operations.
337
+
338
+receive.autoGC=false::
339
+ Similar to `gc.auto`, this setting is disabled in preference of
340
+ background maintenance.
341
+
342
+status.aheadBehind=false::
343
+ This disables the ahead/behind calculation that would normally happen
344
+ during a `git status` command. This information is frequently ignored by
345
+ users but can be expensive to calculate in large repos that receive
346
+ thousands of commits per day. The calculation is replaced with an advice
347
+ message that can be disabled by disabling the `advice.statusAheadBehind`
348
+ config.
349
+
350
+The following settings are different based on which platform is in use:
351
+
352
+core.untrackedCache=(true|false)::
353
+ The untracked cache feature is important for performance benefits on
354
+ large repositories, but has demonstrated some bugs on Windows
355
+ filesystems. Thus, this is set for other platforms but disabled on
356
+ Windows.
357
+
358
+http.sslBackend=schannel::
359
+ On Windows, the `openssl` backend has some issues with certain types of
360
+ remote providers and certificate types. Override the default setting to
361
+ avoid these common problems.
362
+
363
+
364
SEE ALSO
365
--------
366
linkgit:git-clone[1], linkgit:git-maintenance[1].
scalar.c
+4
@@ -132,6 +132,10 @@ static int have_fsmonitor_support(void)
132
133
static int set_recommended_config(int reconfigure)
134
{
135
+ /*
136
+ * Be sure to update Documentation/scalar.adoc if you add, update,
137
+ * or remove any of these recommended settings.
138
+ */
139
struct scalar_config config[] = {
140
{ "am.keepCR", "true" },
141
{ "commitGraph.changedPaths", "true" },