'\" t
.\"     Title: scalar
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2026-06-29
.\"    Manual: Git Manual
.\"    Source: Git 2.55.0
.\"  Language: English
.\"
.TH "SCALAR" "1" "2026\-06\-29" "Git 2\&.55\&.0" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
scalar \- A tool for managing large Git repositories
.SH "SYNOPSIS"
.sp
.nf
scalar clone [\-\-single\-branch] [\-\-branch <main\-branch>] [\-\-full\-clone]
        [\-\-[no\-]src] [\-\-[no\-]tags] [\-\-[no\-]maintenance] <url> [<enlistment>]
scalar list
scalar register [\-\-[no\-]maintenance] [<enlistment>]
scalar unregister [<enlistment>]
scalar run ( all | config | commit\-graph | fetch | loose\-objects | pack\-files ) [<enlistment>]
scalar reconfigure [\-\-maintenance=(enable|disable|keep)] [ \-\-all | <enlistment> ]
scalar diagnose [<enlistment>]
scalar delete <enlistment>
.fi
.sp
.SH "DESCRIPTION"
.sp
Scalar is a repository management tool that optimizes Git for use in large repositories\&. Scalar improves performance by configuring advanced Git settings, maintaining repositories in the background, and helping to reduce data sent across the network\&.
.sp
An important Scalar concept is the enlistment: this is the top\-level directory of the project\&. It usually contains the subdirectory \fBsrc/\fR which is a Git worktree\&. This encourages the separation between tracked files (inside \fBsrc/\fR) and untracked files, such as build artifacts (outside \fBsrc/\fR)\&. When registering an existing Git worktree with Scalar whose name is not \fBsrc\fR, the enlistment will be identical to the worktree\&.
.sp
The \fBscalar\fR command implements various subcommands, and different options depending on the subcommand\&. With the exception of \fBclone\fR, \fBlist\fR and \fBreconfigure\fR \fB\-\-all\fR, all subcommands expect to be run in an enlistment\&.
.sp
The following options can be specified \fIbefore\fR the subcommand:
.PP
\-C <directory>
.RS 4
Before running the subcommand, change the working directory\&. This option imitates the same option of
\fBgit\fR(1)\&.
.RE
.PP
\-c <key>=<value>
.RS 4
For the duration of running the specified subcommand, configure this setting\&. This option imitates the same option of
\fBgit\fR(1)\&.
.RE
.SH "COMMANDS"
.SS "Clone"
.PP
clone [<options>] <url> [<enlistment>]
.RS 4
Clones the specified repository, similar to
\fBgit-clone\fR(1)\&. By default, only commit and tree objects are cloned\&. Once finished, the worktree is located at
\fI<enlistment>\fR\fB/src\fR\&.
.sp
The sparse\-checkout feature is enabled (except when run with
\fB\-\-full\-clone\fR) and the only files present are those in the top\-level directory\&. Use
\fBgit\fR
\fBsparse\-checkout\fR
\fBset\fR
to expand the set of directories you want to see, or
\fBgit\fR
\fBsparse\-checkout\fR
\fBdisable\fR
to expand to all files (see
\fBgit-sparse-checkout\fR(1)
for more details)\&. You can explore the subdirectories outside your sparse\-checkout by using
\fBgit\fR
\fBls\-tree\fR
\fBHEAD\fR[\fB:\fR\fI<directory>\fR]\&.
.RE
.PP
\-b <name>, \-\-branch <name>
.RS 4
Instead of checking out the branch pointed to by the cloned repository\(cqs HEAD, check out the
\fI<name>\fR
branch instead\&.
.RE
.PP
\-\-single\-branch, \-\-no\-single\-branch
.RS 4
Clone only the history leading to the tip of a single branch, either specified by the
\fB\-\-branch\fR
option or the primary branch remote\(cqs
\fBHEAD\fR
points at\&.
.sp
Further fetches into the resulting repository will only update the remote\-tracking branch for the branch this option was used for the initial cloning\&. If the HEAD at the remote did not point at any branch when
\fB\-\-single\-branch\fR
clone was made, no remote\-tracking branch is created\&.
.RE
.PP
\-\-src, \-\-no\-src
.RS 4
By default,
\fBscalar\fR
\fBclone\fR
places the cloned repository within a
\fI<entlistment>\fR\fB/src\fR
directory\&. Use
\fB\-\-no\-src\fR
to place the cloned repository directly in the
\fI<enlistment>\fR
directory\&.
.RE
.PP
\-\-tags, \-\-no\-tags
.RS 4
By default,
\fBscalar\fR
\fBclone\fR
will fetch the tag objects advertised by the remote and future
\fBgit\fR
\fBfetch\fR
commands will do the same\&. Use
\fB\-\-no\-tags\fR
to avoid fetching tags in
\fBscalar\fR
\fBclone\fR
and to configure the repository to avoid fetching tags in the future\&. To fetch tags after cloning with
\fB\-\-no\-tags\fR, run
\fBgit\fR
\fBfetch\fR
\fB\-\-tags\fR\&.
.RE
.PP
\-\-full\-clone, \-\-no\-full\-clone
.RS 4
A sparse\-checkout is initialized by default\&. This behavior can be turned off via
\fB\-\-full\-clone\fR\&.
.RE
.PP
\-\-maintenance, \-\-no\-maintenance
.RS 4
By default,
\fBscalar\fR
\fBclone\fR
configures the enlistment to use Git\(cqs background maintenance feature\&. Use the
\fB\-\-no\-maintenance\fR
to skip this configuration\&.
.RE
.SS "List"
.PP
list
.RS 4
List enlistments that are currently registered by Scalar\&. This subcommand does not need to be run inside an enlistment\&.
.RE
.SS "Register"
.PP
register [<enlistment>]
.RS 4
Adds the enlistment\(cqs repository to the list of registered repositories and starts background maintenance\&. If
\fI<enlistment>\fR
is not provided, then the enlistment associated with the current working directory is registered\&.
.sp
Note: when this subcommand is called in a worktree that is called
\fBsrc/\fR, its parent directory is considered to be the Scalar enlistment\&. If the worktree is
\fInot\fR
called
\fBsrc/\fR, it itself will be considered to be the Scalar enlistment\&.
.RE
.PP
\-\-maintenance, \-\-no\-maintenance
.RS 4
By default,
\fBscalar\fR
\fBregister\fR
configures the enlistment to use Git\(cqs background maintenance feature\&. Use the
\fB\-\-no\-maintenance\fR
to skip this configuration\&. This does not disable any maintenance that may already be enabled in other ways\&.
.RE
.SS "Unregister"
.PP
unregister [<enlistment>]
.RS 4
Remove the specified repository from the list of repositories registered with Scalar and stop the scheduled background maintenance\&.
.RE
.SS "Run"
.PP
scalar run ( all | config | commit\-graph | fetch | loose\-objects | pack\-files ) [<enlistment>]
.RS 4
Run the given maintenance task (or all tasks, if
\fBall\fR
was specified)\&. Except for
\fBall\fR
and
\fBconfig\fR, this subcommand simply hands off to
\fBgit-maintenance\fR(1)
(mapping
\fBfetch\fR
to
\fBprefetch\fR
and
\fBpack\-files\fR
to
\fBincremental\-repack\fR)\&.
.sp
These tasks are run automatically as part of the scheduled maintenance, as soon as the repository is registered with Scalar\&. It should therefore not be necessary to run this subcommand manually\&.
.sp
The
\fBconfig\fR
task is specific to Scalar and configures all those opinionated default settings that make Git work more efficiently with large repositories\&. As this task is run as part of
\fBscalar\fR
\fBclone\fR
automatically, explicit invocations of this task are rarely needed\&.
.RE
.SS "Reconfigure"
.sp
After a Scalar upgrade, or when the configuration of a Scalar enlistment was somehow corrupted or changed by mistake, this subcommand allows to reconfigure the enlistment\&.
.PP
\-\-all
.RS 4
When
\fB\-\-all\fR
is specified, reconfigure all enlistments currently registered with Scalar by the
\fBscalar\&.repo\fR
config key\&. Use this option after each upgrade to get the latest features\&.
.RE
.PP
\-\-maintenance=(enable|disable|keep)
.RS 4
By default, Scalar configures the enlistment to use Git\(cqs background maintenance feature; this is the same as using the \(oqenable` value for this option\&. Use the
\fBdisable\fR
value to remove each considered enlistment from background maintenance\&. Use `keep\(cq to leave the background maintenance configuration untouched for these repositories\&.
.RE
.SS "Diagnose"
.PP
diagnose [<enlistment>]
.RS 4
When reporting issues with Scalar, it is often helpful to provide the information gathered by this command, including logs and certain statistics describing the data shape of the current enlistment\&.
.sp
The output of this command is a
\fB\&.zip\fR
file that is written into a directory adjacent to the worktree in the
\fBsrc\fR
directory\&.
.RE
.SS "Delete"
.PP
delete <enlistment>
.RS 4
This subcommand lets you delete an existing Scalar enlistment from your local file system, unregistering the repository\&.
.RE
.SH "RECOMMENDED CONFIG VALUES"
.sp
As part of both \fBscalar\fR \fBclone\fR and \fBscalar\fR \fBregister\fR, certain Git config values are set to optimize for large repositories or cross\-platform support\&. These options are updated in new Git versions according to the best known advice for large repositories, and users can get the latest recommendations by running \fBscalar\fR \fBreconfigure\fR [\fB\-\-all\fR]\&.
.sp
This section lists justifications for the config values that are set in the latest version\&.
.PP
am\&.keepCR=true
.RS 4
This setting is important for cross\-platform development across Windows and non\-Windows platforms and keeping carriage return (\fB\er\fR) characters in certain workflows\&.
.RE
.PP
commitGraph\&.changedPaths=true
.RS 4
This setting helps the background maintenance steps that compute the serialized commit\-graph to also store changed\-path Bloom filters\&. This accelerates file history commands and allows users to automatically benefit without running a foreground command\&.
.RE
.PP
commitGraph\&.generationVersion=1
.RS 4
While the preferred version is 2 for performance reasons, existing users that had version 1 by default will need special care in upgrading to version 2\&. This is likely to change in the future as the upgrade story solidifies\&.
.RE
.PP
core\&.autoCRLF=false
.RS 4
This removes the transformation of worktree files to add CRLF line endings when only LF line endings exist\&. This is removed for performance reasons\&. Repositories that use tools that care about CRLF line endings should commit the necessary files with those line endings instead\&.
.RE
.PP
core\&.logAllRefUpdates=true
.RS 4
This enables the reflog on all branches\&. While this is a performance cost for large repositories, it is frequently an important data source for users to get out of bad situations or to seek support from experts\&.
.RE
.PP
core\&.safeCRLF=false
.RS 4
Similar to
\fBcore\&.autoCRLF=false\fR, this disables checks around whether the CRLF conversion is reversible\&. This is a performance improvement, but can be dangerous if
\fBcore\&.autoCRLF\fR
is reenabled by the user\&.
.RE
.PP
credential\&.https://dev\&.azure\&.com\&.useHttpPath=true
.RS 4
This setting enables the
\fBcredential\&.useHttpPath\fR
feature only for web URLs for Azure DevOps\&. This is important for users interacting with that service using multiple organizations and thus multiple credential tokens\&.
.RE
.PP
feature\&.experimental=false
.RS 4
This disables the "experimental" optimizations grouped under this feature config\&. The expectation is that all valuable optimizations are also set explicitly by Scalar config, and any differences are intentional\&. Notable differences include several bitmap\-related config options which are disabled for client\-focused Scalar repos\&.
.RE
.PP
feature\&.manyFiles=false
.RS 4
This disables the "many files" optimizations grouped under this feature config\&. The expectation is that all valuable optimizations are also set explicitly by Scalar config, and any differences are intentional\&.
.RE
.PP
fetch\&.showForcedUpdates=false
.RS 4
This disables the check at the end of
\fBgit\fR
\fBfetch\fR
that notifies the user if the ref update was a forced update (one where the previous position is not reachable from the latest position)\&. This check can be very expensive in large repositories, so is disabled and replaced with an advice message\&. Set
\fBadvice\&.fetchShowForcedUpdates=false\fR
to disable this advice message\&.
.RE
.PP
fetch\&.unpackLimit=1
.RS 4
This setting prevents Git from unpacking packfiles into loose objects as they are downloaded from the server\&. The default limit of 100 was intended as a way to prevent performance issues from too many packfiles, but Scalar uses background maintenance to group packfiles and cover them with a multi\-pack\-index, removing this issue\&.
.RE
.PP
fetch\&.writeCommitGraph=false
.RS 4
This config setting was created to help users automatically update their commit\-graph files as they perform fetches\&. However, this takes time from foreground fetches and pulls and Scalar uses background maintenance for this function instead\&.
.RE
.PP
gc\&.auto=0
.RS 4
This disables automatic garbage collection, since Scalar uses background maintenance to keep the repository data in good shape\&.
.RE
.PP
gui\&.GCWarning=false
.RS 4
Since Scalar disables garbage collection by setting
\fBgc\&.auto=0\fR, the
\fBgit\-gui\fR
tool may start to warn about this setting\&. Disable this warning as Scalar\(cqs background maintenance configuration makes the warning irrelevant\&.
.RE
.PP
index\&.skipHash=true
.RS 4
Disable computing the hash of the index contents as it is being written\&. This assists with performance, especially for large index files\&.
.RE
.PP
index\&.threads=true
.RS 4
This tells Git to automatically detect how many threads it should use when reading the index due to the default value of
\fBcore\&.preloadIndex\fR, which enables parallel index reads\&. This explicit setting also enables
\fBindex\&.recordOffsetTable=true\fR
to speed up parallel index reads\&.
.RE
.PP
index\&.version=4
.RS 4
This index version adds compression to the path names, reducing the size of the index in a significant way for large repos\&. This is an important performance boost\&.
.RE
.PP
log\&.excludeDecoration=refs/prefetch/*
.RS 4
Since Scalar enables background maintenance with the
\fBincremental\fR
strategy, this setting avoids polluting
\fBgit\fR
\fBlog\fR
output with refs stored by the background prefetch operations\&.
.RE
.PP
merge\&.renames=true
.RS 4
When computing merges in large repos, it is particularly important to detect renames to maximize the potential for a result that will validate correctly\&. Users performing merges locally are more likely to be doing so because a server\-side merge (via pull request or similar) resulted in conflicts\&. While this is the default setting, it is set specifically to override a potential change to
\fBdiff\&.renames\fR
which a user may set for performance reasons\&.
.RE
.PP
merge\&.stat=false
.RS 4
This disables a diff output after computing a merge\&. This improves performance of
\fBgit\fR
\fBmerge\fR
for large repos while reducing noisy output\&.
.RE
.PP
pack\&.useBitmaps=false
.RS 4
This disables the use of
\fB\&.bitmap\fR
files attached to packfiles\&. Bitmap files are optimized for server\-side use, not client\-side use\&. Scalar disables this to avoid some performance issues that can occur if a user accidentally creates
\fB\&.bitmap\fR
files\&.
.RE
.PP
pack\&.usePathWalk=true
.RS 4
This enables the
\fB\-\-path\-walk\fR
option to
\fBgit\fR
\fBpack\-objects\fR
by default\&. This can accelerate the computation and compression of packfiles created by
\fBgit\fR
\fBpush\fR
and other repack operations\&.
.RE
.PP
receive\&.autoGC=false
.RS 4
Similar to
\fBgc\&.auto\fR, this setting is disabled in preference of background maintenance\&.
.RE
.PP
status\&.aheadBehind=false
.RS 4
This disables the ahead/behind calculation that would normally happen during a
\fBgit\fR
\fBstatus\fR
command\&. This information is frequently ignored by users but can be expensive to calculate in large repos that receive thousands of commits per day\&. The calculation is replaced with an advice message that can be disabled by disabling the
\fBadvice\&.statusAheadBehind\fR
config\&.
.RE
.sp
The following settings are different based on which platform is in use:
.PP
core\&.untrackedCache=(true|false)
.RS 4
The untracked cache feature is important for performance benefits on large repositories, but has demonstrated some bugs on Windows filesystems\&. Thus, this is set for other platforms but disabled on Windows\&.
.RE
.PP
http\&.sslBackend=schannel
.RS 4
On Windows, the
\fBopenssl\fR
backend has some issues with certain types of remote providers and certificate types\&. Override the default setting to avoid these common problems\&.
.RE
.SH "SEE ALSO"
.sp
\fBgit-clone\fR(1), \fBgit-maintenance\fR(1)\&.
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite